NAME

Net::SSLeay::OO::Error - encapsulated SSLeay errors

SYNOPSIS

 use Scalar::Util qw(blessed);
 eval {
    $ctx->use_PrivateKey_file($filename, FILETYPE_PEM);
 };
 my $error = $@;
 if (blessed $error and
      ( $error->error_code == 0x0B080074 or
        $error->reason_string =~ /key.*mismatch/i ) ) {
    # deal with some known error condition differently..
    die "Private key file mismatches certificate file, did "
        ."you update both settings?";
 }
 elsif ($error) {
    die $error;
 }

 # if you need to manually check for errors ever
 use Net::SSLeay::OO::Error qw(die_if_ssl_error ssl_error_pending);
 die_if_ssl_error("Initialization");

DESCRIPTION

Unlike Net::SSLeay, with Net::SSLeay::OO functions, if an error occurs in a low level library an exception is raised via die.

OpenSSL has an 'error queue', which normally represents something like a stack trace indicating the context of the error. The first error will be the "deepest" error and usually has the most relevant error message. To represent this, the Net::SSLeay::OO::Error object has a next property, which represents a level further up the exception heirarchy.

METHODS

The following methods are defined (some via Moose attributes):

error_string()

Returns the error string from OpenSSL.

as_string()

Returns the error string, turned into a marginally more user-friendly message. Also available as the overloaded '""' operator (ie, when interpreted as a string you will get a message)

error_code()

A fixed error code corresponding to the error.

reason_string()

The human-readable part, or (apparently) "system lib" if the error is part of a stack trace.

library_name()

function_name()

Where the error occurred, or where this part of the stack trace applies.

next()

The next (shallower) Net::SSLeay::OO::Error object, corresponding to the next level up the stack trace.

message( [$message] )

The caller-supplied message that this error will be prefixed with. If this is a single word (no whitespace) then it will be printed as During `$message':.

FUNCTIONS

These functions are available for export.

die_if_ssl_error($message)

This is similar to Net::SSLeay's function of the same name, except;

1. The entire error queue is cleared, and wrapped into a single chain of exception objects

2. The message is parceled to be hopefully a little more human-readable.

Here is an example, an error raised during the test suite script t/03-ssl.t:

  During `use_certificate_file': OpenSSL error 02001002: No such file or directory during fopen (system library)
      then 20074002: trace: FILE_CTRL (BIO routines)
      then 140c8002: trace: SSL_use_certificate_file (SSL routines)

The function was called as: die_if_ssl_error("use_certificate_file")

The strings returned from OpenSSL as a "human readable" error messages were:

  error:02001002:system library:fopen:No such file or directory
  error:20074002:BIO routines:FILE_CTRL:system lib
  error:140C8002:SSL routines:SSL_use_certificate_file:system lib

ssl_error_pending()

Returns a non-zero integer if there is an error pending. To fetch it, just create a new Net::SSLeay::OO::Error object.

AUTHOR

Sam Vilain, samv@cpan.org

COPYRIGHT

Copyright (C) 2009 NZ Registry Services

This program is free software: you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or later. You should have received a copy of the Artistic License the file COPYING.txt. If not, see <http://www.perlfoundation.org/artistic_license_2_0>

SEE ALSO

Net::SSLeay::OO