Crypt-X509 version 0.31
=======================

Crypt::X509 is an object oriented X.509 certificate parser with numerous
methods for directly extracting information from certificates.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires:

  Convert::ASN1

NAME
    Crypt::X509 - Parse a X.509 certificate

SYNOPSIS
     use Crypt::X509;

     $decoded = Crypt::X509->new( cert => $cert );

     $subject_email = $decoded->subject_email;
     print "do not use after: ".gmtime($decoded->not_after)." GMT\n";

REQUIRES
    Convert::ASN1

DESCRIPTION
    Crypt::X509 parses X.509 certificates. Methods are provided for
    accessing most certificate elements.

    It is based on the generic ASN.1 module by Graham Barr, on the
    x509decode example by Norbert Klasen and contributions on the
    perl-ldap-dev-Mailinglist by Chriss Ridd.

CONSTRUCTOR
  new ( OPTIONS )
    Creates and returns a parsed X.509 certificate hash, containing the
    parsed contents. The data is organised as specified in RFC 2459. By
    default only the first ASN.1 Layer is decoded. Nested decoding is done
    automagically through the data access methods.

    cert => $certificate
        A variable containing the DER formatted certificate to be parsed
        (eg. as stored in "usercertificate;binary" attribute in an
        LDAP-directory).

      use Crypt::X509;
      use Data::Dumper;
  
      $decoded= Crypt::X509->new(cert => $cert);
  
      print Dumper($decoded);

METHODS
  error
    Returns the last error from parsing, "undef" when no error occured. This
    error is updated on deeper parsing with the data access methods.

      $decoded= Crypt::X509->new(cert => $cert);
      if ($decoded->error) {
            warn "Error on parsing Certificate:".$decoded->error;
      }

DATA ACCESS METHODS
    You can access all parsed data directly from the returned hash. For
    convenience the following methods have been implemented to give quick
    access to the most-used certificate attributes.

  version
    Returns the certificate's version as an integer. NOTE that version is
    defined as an Integer where 0 = v1, 1 = v2, and 2 = v3.

  version_string
    Returns the certificate's version as a string value.

  serial
    returns the serial number (integer or Math::BigInt Object, that gets
    automagic evaluated in scalar context) from the certificate

      $decoded= Crypt::X509->new(cert => $cert);
      print "Certificate has serial number:".$decoded->serial."\n";  

  not_before
    returns the GMT-timestamp of the certificate's beginning date of
    validity. If the Certificate holds this Entry in utcTime, it is
    guaranteed by the RFC to been correct.

    As utcTime is limited to 32-bit values (like unix-timestamps) newer
    certificates hold the timesamps as "generalTime"-entries. The contents
    of "generalTime"-entries are not well defined in the RFC and are
    returned by this module unmodified, if no utcTime-entry is found.

      $decoded= Crypt::X509->new(cert => $cert);
      if ($decoded->notBefore < time()) {
            warn "Certificate: not yet valid!";
      }

  not_after
    returns the GMT-timestamp of the certificate's ending date of validity.
    If the Certificate holds this Entry in utcTime, it is guaranteed by the
    RFC to been correct.

    As utcTime is limited to 32-bit values (like unix-timestamps) newer
    certificates hold the timesamps as "generalTime"-entries. The contents
    of "generalTime"-entries are not well defined in the RFC and are
    returned by this module unmodified, if no utcTime-entry is found.

      $decoded= Crypt::X509->new(cert => $cert);
      print "Certificate expires on ".gmtime($decoded->not_after)." GMT\n";

  signature
    Return's the certificate's signature in binary DER format.

  pubkey
    Returns the certificate's public key in binary DER format.

  pubkey_size
    Returns the certificate's public key size.

  pubkey_algorithm
    Returns the algorithm as OID string which the public key was created
    with.

  PubKeyAlg
    returns the subject public key encryption algorithm (e.g. 'RSA') as
    string.

      $decoded= Crypt::X509->new(cert => $cert);
      print "Certificate public key is encrypted with:".$decoded->PubKeyAlg."\n";
  
      Example Output: Certificate public key is encrypted with: RSA
  
  sig_algorithm
    Returns the certificate's signature algorithm as OID string

      $decoded= Crypt::X509->new(cert => $cert);
      print "Certificate signature is encrypted with:".$decoded->sig_algorithm."\n";>
  
      Example Output: Certificate signature is encrypted with: 1.2.840.113549.1.1.5

  SigEncAlg
    returns the signature encryption algorithm (e.g. 'RSA') as string.

      $decoded= Crypt::X509->new(cert => $cert);
      print "Certificate signature is encrypted with:".$decoded->SigEncAlg."\n";
  
      Example Output: Certificate signature is encrypted with: RSA

  SigHashAlg
    returns the signature hashing algorithm (e.g. 'SHA1') as string.

      $decoded= Crypt::X509->new(cert => $cert);
      print "Certificate signature is hashed with:".$decoded->SigHashAlg."\n";

      Example Output: Certificate signature is encrypted with: SHA1

  Subject
    returns a pointer to an array of strings containing subject nameparts of
    the certificate. Attributenames for the most common Attributes are
    translated from the OID-Numbers, unknown numbers are output verbatim.

      $decoded= Convert::ASN1::X509->new($cert);
      print "DN for this Certificate is:".join(',',@{$decoded->Subject})."\n";

  subject_country
    Returns the string value for subject's country (= the value with the OID
    2.5.4.6 or in DN Syntax everything after "C="). Only the first entry is
    returned. "undef" if subject contains no country attribute.

  subject_state
    Returns the string value for subject's state or province (= the value
    with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the
    first entry is returned. "undef" if subject contains no state attribute.

  subject_org
    Returns the string value for subject's organization (= the value with
    the OID 2.5.4.10 or in DN Syntax everything after "O="). Only the first
    entry is returned. "undef" if subject contains no organization
    attribute.

  subject_ou
    Returns the string value for subject's organizational unit (= the value
    with the OID 2.5.4.11 or in DN Syntax everything after "OU="). Only the
    first entry is returned. "undef" if subject contains no organization
    attribute.

  subject_cn
    Returns the string value for subject's common name (= the value with the
    OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the first
    entry is returned. "undef" if subject contains no common name attribute.

  subject_email
    Returns the string value for subject's email address (= the value with
    the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E=").
    Only the first entry is returned. "undef" if subject contains no email
    attribute.

  Issuer
    returns a pointer to an array of strings building the DN of the
    certificate issuer (= the DN of the CA). Attributenames for the most
    common Attributes are translated from the OID-Numbers, unknown numbers
    are output verbatim.

      $decoded= Crypt::X509->new($cert);
      print "Certificate was issued by:".join(',',@{$decoded->Issuer})."\n";

  issuer_cn
    Returns the string value for issuer's common name (= the value with the
    OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the first
    entry is returned. "undef" if issuer contains no common name attribute.

  issuer_country
    Returns the string value for issuer's country (= the value with the OID
    2.5.4.6 or in DN Syntax everything after "C="). Only the first entry is
    returned. "undef" if issuer contains no country attribute.

  issuer_state
    Returns the string value for issuer's state or province (= the value
    with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the
    first entry is returned. "undef" if issuer contains no state attribute.

  issuer_locality
    Returns the string value for issuer's locality (= the value with the OID
    2.5.4.7 or in DN Syntax everything after "L="). Only the first entry is
    returned. "undef" if issuer contains no locality attribute.

  issuer_org
    Returns the string value for issuer's organization (= the value with the
    OID 2.5.4.10 or in DN Syntax everything after "O="). Only the first
    entry is returned. "undef" if issuer contains no organization attribute.

  issuer_email
    Returns the string value for issuer's email address (= the value with
    the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E=").
    Only the first entry is returned. "undef" if issuer contains no email
    attribute.

  KeyUsage
    returns a pointer to an array of strings describing the valid Usages for
    this certificate. "undef" is returned, when the extension is not set in
    the certificate.

    If the extension is marked critical, this is also reported.

      $decoded= Crypt::X509->new(cert => $cert);
      print "Allowed usages for this Certificate are:\n".join("\n",@{$decoded->KeyUsage})."\n";

      Example Output:
      Allowed usages for this Certificate are:
      critical 
      digitalSignature
      keyEncipherment
      dataEncipherment

  SubjectAltName
    returns a pointer to an array of strings containing alternative
    Subjectnames or "undef" if the extension is not filled. Usually this
    Extension holds the e-Mail address for person-certificates or DNS-Names
    for server certificates.

    It also pre-pends the field type (ie rfc822Name) to the returned value.

      $decoded= Crypt::X509->new($cert);
      print "E-Mail or Hostnames in this Certificates is/are:", join(", ", @{$decoded->SubjectAltName}), "\n";
  
      Example Output: E-Mail or Hostnames in this Certificates is/are: rfc822Name=user@server.com

  authorityCertIssuer
    returns a pointer to an array of strings building the DN of the
    Authority Cert Issuer. Attributenames for the most common Attributes are
    translated from the OID-Numbers, unknown numbers are output verbatim.
    undef if the extension is not set in the certificate.

      $decoded= Crypt::X509->new($cert);
      print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";

  authority_serial
    Returns the authority's certificate serial number.

  key_identifier
    Returns the authority key identifier or undef if it is a rooted cert

  authority_cn
    Returns the authority's ca.

  authority_country
    Returns the authority's country.

  authority_state
    Returns the authority's state.

  authority_locality
    Returns the authority's locality.

  authority_org
    Returns the authority's organization.

  authority_email
    Returns the authority's email.

  CRLDistributionPoints
    Returns the CRL distribution points as an array of strings (with one
    value usually)

  CRLDistributionPoints2
    Returns the CRL distribution points as an array of hashes (allowing for
    some variations)

  CertificatePolicies
    Returns the CertificatePolicies as an array of strings

  EntrustVersionInfo
    Returns the EntrustVersion as a string

            print "Entrust Version: ", $decoded->EntrustVersion, "\n";
        
            Example Output: Entrust Version: V7.0

  SubjectDirectoryAttributes
    Returns the SubjectDirectoryAttributes as an array of key = value pairs,
    to include a data type

            print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";
        
            Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)

  BasicConstraints
    Returns the BasicConstraints as an array and the criticallity
    pre-pended.

  subject_keyidentifier
    Returns the subject key identifier from the extensions.

  SubjectInfoAccess
    Returns the SubjectInfoAccess as an array of hashes with key=value
    pairs.

                    print "Subject Info Access: ";
                    if ( defined $decoded->SubjectInfoAccess ) {
                            my %SIA = $decoded->SubjectInfoAccess;
                            for my $key ( keys %SIA ) {
                                    print "\n\t$key: \n\t";
                                    print join( "\n\t" , @{ $SIA{$key} } ), "\n";
                            }
                    } else { print "\n" }
        
            Example Output: 
                    Subject Info Access: 
                            1.3.6.1.5.5.7.48.5: 
                            uniformResourceIdentifier = http://pki.treas.gov/root_sia.p7c
                            uniformResourceIdentifier = ldap://ldap.treas.gov/ou=US%20Treasury%20Root%20CA,ou=Certification%20Authorities,ou=Department%20of%20the%20Treasury,o=U.S.%20Government,c=US?cACertificate;binary,crossCertificatePair;binary

SEE ALSO
    See the examples of "Convert::ASN1" and the <perl-ldap@perl.org> Mailing
    List. An example on how to load certificates can be found in
    t\Crypt-X509.t.

ACKNOWLEDGEMENTS
    This module is based on the x509decode script, which was contributed to
    Convert::ASN1 in 2002 by Norbert Klasen.

AUTHORS
    Mike Jackson <mj@sci.fi>, Alexander Jung <alexander.w.jung@gmail.com>,
    Duncan Segrest <duncan@gigageek.info>

COPYRIGHT
    Copyright (c) 2005 Mike Jackson <mj@sci.fi>. Copyright (c) 2001-2002
    Norbert Klasen, DAASI International GmbH.

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

