NAME

Net::SSLeay::OO::X509 - OpenSSL SSL certificate

SYNOPSIS

# currently no way to create them with this module
my $cert = $ssl->get_peer_certificate;

# important stuff
my $subject = $cert->get_subject_name;
my $issuer  = $cert->get_issuer_name;

say "This cert is for ".$subject->cn.
   ", and was issued by ".$issuer->cn;

# see full description for a less cryptic example :)
my $i = 0;
my @names = grep { $i ^= 1 } $cert->get_subjectAltNames;
say "This cert also covers @names";

DESCRIPTION

This module encapsulates X509 certificates, the X509* type in OpenSSL's C library.

The functions available to this library are focused on pulling useful information out of the SSL certificates that were exchanged.

As a result, there are no methods for creating the certificates - and there is seldom need to do such things outside of the typical OpenSSL command-line set and existing programs to do that. See t/certs/make-test-certs.sh in the distribution for a shell script which uses the openssl req and openssl ca commands to create certificates which are used for the test suite.

METHODS

Certificate Information Methods

get_subject_name

get_issuer_name

The Subject Name is the X.509 Name which represents the identity of this certificate. Using a PGP analogy, it's like the KeyID. It has fields like country, cn / commonName (normally a domain name), locality and what your favourite chicken species for sacrificial use are.

The Issuer Name is another X.509 Name which represents the identity which signs this certificate. Unlike PGP, individual SSL certificates can only have one signature attached, which needs to lead back to some trusted root certificate.

These entities are not strings; they are Net::SSLeay::OO::X509::Name objects.

get_subjectAltNames

This is a method in Net::SSLeay which wraps up the new vhosting SSL certificate support, so that you can see the alternate names on that SSL certificate.

Unlike the get_*_name methods, this method returns a list of pairs; the first item in the pair being the type of name, and the second one being a string representation of that name.

get_notBefore(cert)

get_notAfter(cert)

These methods probably return validity period times for the certificate. To be confirmed.

free()

This method will cause the object to forget its internal pointer reference. Use if you have been given a reference which is not refcounted, and the reference is going to expire soon.

Arcane Internal Methods

The notes on Net::SSLeay::OO::Context about the un-triaged methods all apply to these methods.

get_ext_by_NID(x,nid,loc)

get_ext(x,loc)

These probably have something to do with extensible additions to SSL certificates; the subjectAltNames implementation calls these methods.

load_cert_file(ctx, file, type)

load_crl_file(ctx, file, type)

load_cert_crl_file(ctx, file, type)

These methods take a X509_LOOKUP* as their first argument. I really wouldn't recommend them.

verify_cert_error_string(n)

Don't call this as a method. It seems to be a function that takes an error code from some other function and returns the string corresponding to that error.

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, Net::SSLeay::OO::X509::Name, Net::SSLeay::OO::X509::Store, Net::SSLeay::X509::Context