GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CRYPT::X509 (3)

.ds Aq ’

NAME

Crypt::X509 - Parse a X.509 certificate

CONTENTS

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

<B>Crypt::X509B> 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. <B>The contents of generalTime-entries are not well defined in the RFC and are returned by this module unmodifiedB>, 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. <B>The contents of generalTime-entries are not well defined in the RFC and are returned by this module unmodifiedB>, 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



    pubkey_components

If this certificate contains an RSA key, this function returns a hashref { modulus => $m, exponent => $e) from that key; each value in the hash will be an integer scalar or a Math::BigInt object.

For other pubkey types, it returns undef (implementations welcome!).

    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_locality

Returns the string value for subject’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 subject contains no locality 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



    ExtKeyUsage

returns a pointer to an array of ExtKeyUsage strings (or OIDs for unknown OIDs) or undef if the extension is not filled. OIDs of the following ExtKeyUsages are known: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, OCSPSigning

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



  $decoded= Crypt::X509->new($cert);
  print "ExtKeyUsage extension of this Certificates is: ", join(", ", @{$decoded->ExtKeyUsage}), "\n";
 
  Example Output: ExtKeyUsage extension of this Certificates is: critical, serverAuth



    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



    PGPExtension

Returns the creation timestamp of the corresponding OpenPGP key. (see http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)



                print "PGPExtension: ";
                if ( defined $decoded->PGPExtension ) {
                        my $creationtime = $decoded->PGPExtension;
                        printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
                }

        Example Output:
                PGPExtension:
                    whatever



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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CRYPT::X509 (3) 2011-07-06

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.