1Crypt::X509(3)        User Contributed Perl Documentation       Crypt::X509(3)
2
3
4

NAME

6       Crypt::X509 - Parse a X.509 certificate
7

SYNOPSIS

9        use Crypt::X509;
10
11        $decoded = Crypt::X509->new( cert => $cert );
12
13        $subject_email = $decoded->subject_email;
14        print "do not use after: ".gmtime($decoded->not_after)." GMT\n";
15

REQUIRES

17       Convert::ASN1
18

DESCRIPTION

20       Crypt::X509 parses X.509 certificates. Methods are provided for
21       accessing most certificate elements.
22
23       It is based on the generic ASN.1 module by Graham Barr, on the
24       x509decode example by Norbert Klasen and contributions on the perl-
25       ldap-dev-Mailinglist by Chriss Ridd.
26

CONSTRUCTOR

28   new ( OPTIONS )
29       Creates and returns a parsed X.509 certificate hash, containing the
30       parsed contents. The data is organised as specified in RFC 2459.  By
31       default only the first ASN.1 Layer is decoded. Nested decoding is done
32       automagically through the data access methods.
33
34       cert => $certificate
35           A variable containing the DER formatted certificate to be parsed
36           (eg. as stored in "usercertificate;binary" attribute in an LDAP-
37           directory).
38
39         use Crypt::X509;
40         use Data::Dumper;
41
42         $decoded= Crypt::X509->new(cert => $cert);
43
44         print Dumper($decoded);
45

METHODS

47   error
48       Returns the last error from parsing, "undef" when no error occured.
49       This error is updated on deeper parsing with the data access methods.
50
51         $decoded= Crypt::X509->new(cert => $cert);
52         if ($decoded->error) {
53               warn "Error on parsing Certificate:".$decoded->error;
54         }
55

DATA ACCESS METHODS

57       You can access all parsed data directly from the returned hash. For
58       convenience the following methods have been implemented to give quick
59       access to the most-used certificate attributes.
60
61   version
62       Returns the certificate's version as an integer.  NOTE that version is
63       defined as an Integer where 0 = v1, 1 = v2, and 2 = v3.
64
65   version_string
66       Returns the certificate's version as a string value.
67
68   serial
69       returns the serial number (integer or Math::BigInt Object, that gets
70       automagic evaluated in scalar context) from the certificate
71
72         $decoded= Crypt::X509->new(cert => $cert);
73         print "Certificate has serial number:".$decoded->serial."\n";
74
75   not_before
76       returns the GMT-timestamp of the certificate's beginning date of
77       validity.  If the Certificate holds this Entry in utcTime, it is
78       guaranteed by the RFC to been correct.
79
80       As utcTime is limited to 32-bit values (like unix-timestamps) newer
81       certificates hold the timesamps as "generalTime"-entries. The contents
82       of "generalTime"-entries are not well defined in the RFC and are
83       returned by this module unmodified, if no utcTime-entry is found.
84
85         $decoded= Crypt::X509->new(cert => $cert);
86         if ($decoded->notBefore < time()) {
87               warn "Certificate: not yet valid!";
88         }
89
90   not_after
91       returns the GMT-timestamp of the certificate's ending date of validity.
92       If the Certificate holds this Entry in utcTime, it is guaranteed by the
93       RFC to been correct.
94
95       As utcTime is limited to 32-bit values (like unix-timestamps) newer
96       certificates hold the timesamps as "generalTime"-entries. The contents
97       of "generalTime"-entries are not well defined in the RFC and are
98       returned by this module unmodified, if no utcTime-entry is found.
99
100         $decoded= Crypt::X509->new(cert => $cert);
101         print "Certificate expires on ".gmtime($decoded->not_after)." GMT\n";
102
103   signature
104       Return's the certificate's signature in binary DER format.
105
106   pubkey
107       Returns the certificate's public key in binary DER format.
108
109   pubkey_size
110       Returns the certificate's public key size.
111
112   pubkey_algorithm
113       Returns the algorithm as OID string which the public key was created
114       with.
115
116   PubKeyAlg
117       returns the subject public key encryption algorithm (e.g. 'RSA') as
118       string.
119
120         $decoded= Crypt::X509->new(cert => $cert);
121         print "Certificate public key is encrypted with:".$decoded->PubKeyAlg."\n";
122
123         Example Output: Certificate public key is encrypted with: RSA
124
125   pubkey_components
126       If this certificate contains an RSA key, this function returns a
127       hashref { modulus => $m, exponent => $e) from that key; each value in
128       the hash will be an integer scalar or a Math::BigInt object.
129
130       For other pubkey types, it returns undef (implementations welcome!).
131
132   sig_algorithm
133       Returns the certificate's signature algorithm as OID string
134
135         $decoded= Crypt::X509->new(cert => $cert);
136         print "Certificate signature is encrypted with:".$decoded->sig_algorithm."\n";>
137
138         Example Output: Certificate signature is encrypted with: 1.2.840.113549.1.1.5
139
140   SigEncAlg
141       returns the signature encryption algorithm (e.g. 'RSA') as string.
142
143         $decoded= Crypt::X509->new(cert => $cert);
144         print "Certificate signature is encrypted with:".$decoded->SigEncAlg."\n";
145
146         Example Output: Certificate signature is encrypted with: RSA
147
148   SigHashAlg
149       returns the signature hashing algorithm (e.g. 'SHA1') as string.
150
151         $decoded= Crypt::X509->new(cert => $cert);
152         print "Certificate signature is hashed with:".$decoded->SigHashAlg."\n";
153
154         Example Output: Certificate signature is encrypted with: SHA1
155
156   Subject
157       returns a pointer to an array of strings containing subject nameparts
158       of the certificate. Attributenames for the most common Attributes are
159       translated from the OID-Numbers, unknown numbers are output verbatim.
160
161         $decoded= Convert::ASN1::X509->new($cert);
162         print "DN for this Certificate is:".join(',',@{$decoded->Subject})."\n";
163
164   subject_country
165       Returns the string value for subject's country (= the value with the
166        OID 2.5.4.6 or in DN Syntax everything after "C=").  Only the first
167       entry is returned. "undef" if subject contains no country attribute.
168
169   subject_locality
170       Returns the string value for subject's locality (= the value with the
171       OID 2.5.4.7 or in DN Syntax everything after "l=").  Only the first
172       entry is returned. "undef" if subject contains no locality attribute.
173
174   subject_state
175       Returns the string value for subject's state or province (= the value
176       with the OID 2.5.4.8 or in DN Syntax everything after "S=").  Only the
177       first entry is returned. "undef" if subject contains no state
178       attribute.
179
180   subject_org
181       Returns the string value for subject's organization (= the value with
182       the OID 2.5.4.10 or in DN Syntax everything after "O=").  Only the
183       first entry is returned. "undef" if subject contains no organization
184       attribute.
185
186   subject_ou
187       Returns the string value for subject's organizational unit (= the value
188       with the OID 2.5.4.11 or in DN Syntax everything after "OU=").  Only
189       the first entry is returned. "undef" if subject contains no
190       organization attribute.
191
192   subject_cn
193       Returns the string value for subject's common name (= the value with
194       the OID 2.5.4.3 or in DN Syntax everything after "CN=").  Only the
195       first entry is returned. "undef" if subject contains no common name
196       attribute.
197
198   subject_email
199       Returns the string value for subject's email address (= the value with
200       the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E=").
201       Only the first entry is returned. "undef" if subject contains no email
202       attribute.
203
204   Issuer
205       returns a pointer to an array of strings building the DN of the
206       certificate issuer (= the DN of the CA). Attributenames for the most
207       common Attributes are translated from the OID-Numbers, unknown numbers
208       are output verbatim.
209
210         $decoded= Crypt::X509->new($cert);
211         print "Certificate was issued by:".join(',',@{$decoded->Issuer})."\n";
212
213   issuer_cn
214       Returns the string value for issuer's common name (= the value with the
215       OID 2.5.4.3 or in DN Syntax everything after "CN=").  Only the first
216       entry is returned. "undef" if issuer contains no common name attribute.
217
218   issuer_country
219       Returns the string value for issuer's country (= the value with the
220        OID 2.5.4.6 or in DN Syntax everything after "C=").  Only the first
221       entry is returned. "undef" if issuer contains no country attribute.
222
223   issuer_state
224       Returns the string value for issuer's state or province (= the value
225       with the OID 2.5.4.8 or in DN Syntax everything after "S=").  Only the
226       first entry is returned. "undef" if issuer contains no state attribute.
227
228   issuer_locality
229       Returns the string value for issuer's locality (= the value with the
230       OID 2.5.4.7 or in DN Syntax everything after "L=").  Only the first
231       entry is returned. "undef" if issuer contains no locality attribute.
232
233   issuer_org
234       Returns the string value for issuer's organization (= the value with
235       the OID 2.5.4.10 or in DN Syntax everything after "O=").  Only the
236       first entry is returned. "undef" if issuer contains no organization
237       attribute.
238
239   issuer_email
240       Returns the string value for issuer's email address (= the value with
241       the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E=").
242       Only the first entry is returned. "undef" if issuer contains no email
243       attribute.
244
245   KeyUsage
246       returns a pointer to an array of strings describing the valid Usages
247       for this certificate. "undef" is returned, when the extension is not
248       set in the certificate.
249
250       If the extension is marked critical, this is also reported.
251
252         $decoded= Crypt::X509->new(cert => $cert);
253         print "Allowed usages for this Certificate are:\n".join("\n",@{$decoded->KeyUsage})."\n";
254
255         Example Output:
256         Allowed usages for this Certificate are:
257         critical
258         digitalSignature
259         keyEncipherment
260         dataEncipherment
261
262   ExtKeyUsage
263       returns a pointer to an array of ExtKeyUsage strings (or OIDs for
264       unknown OIDs) or "undef" if the extension is not filled. OIDs of the
265       following ExtKeyUsages are known: serverAuth, clientAuth, codeSigning,
266       emailProtection, timeStamping, OCSPSigning
267
268       If the extension is marked critical, this is also reported.
269
270         $decoded= Crypt::X509->new($cert);
271         print "ExtKeyUsage extension of this Certificates is: ", join(", ", @{$decoded->ExtKeyUsage}), "\n";
272
273         Example Output: ExtKeyUsage extension of this Certificates is: critical, serverAuth
274
275   SubjectAltName
276       returns a pointer to an array of strings containing alternative
277       Subjectnames or "undef" if the extension is not filled. Usually this
278       Extension holds the e-Mail address for person-certificates or DNS-Names
279       for server certificates.
280
281       It also pre-pends the field type (ie rfc822Name) to the returned value.
282
283         $decoded= Crypt::X509->new($cert);
284         print "E-Mail or Hostnames in this Certificates is/are:", join(", ", @{$decoded->SubjectAltName}), "\n";
285
286         Example Output: E-Mail or Hostnames in this Certificates is/are: rfc822Name=user@server.com
287
288   authorityCertIssuer
289       returns a pointer to an array of strings building the DN of the
290       Authority Cert Issuer. Attributenames for the most common Attributes
291       are translated from the OID-Numbers, unknown numbers are output
292       verbatim.  undef if the extension is not set in the certificate.
293
294         $decoded= Crypt::X509->new($cert);
295         print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";
296
297   authority_serial
298       Returns the authority's certificate serial number.
299
300   key_identifier
301       Returns the authority key identifier or undef if it is a rooted cert
302
303   authority_cn
304       Returns the authority's ca.
305
306   authority_country
307       Returns the authority's country.
308
309   authority_state
310       Returns the authority's state.
311
312   authority_locality
313       Returns the authority's locality.
314
315   authority_org
316       Returns the authority's organization.
317
318   authority_email
319       Returns the authority's email.
320
321   CRLDistributionPoints
322       Returns the CRL distribution points as an array of strings (with one
323       value usually)
324
325   CRLDistributionPoints2
326       Returns the CRL distribution points as an array of hashes (allowing for
327       some variations)
328
329   CertificatePolicies
330       Returns the CertificatePolicies as an array of strings
331
332   EntrustVersionInfo
333       Returns the EntrustVersion as a string
334
335               print "Entrust Version: ", $decoded->EntrustVersion, "\n";
336
337               Example Output: Entrust Version: V7.0
338
339   SubjectDirectoryAttributes
340       Returns the SubjectDirectoryAttributes as an array of key = value
341       pairs, to include a data type
342
343               print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";
344
345               Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)
346
347   BasicConstraints
348       Returns the BasicConstraints as an array and the criticallity pre-
349       pended.
350
351   subject_keyidentifier
352       Returns the subject key identifier from the extensions.
353
354   SubjectInfoAccess
355       Returns the SubjectInfoAccess as an array of hashes with key=value
356       pairs.
357
358                       print "Subject Info Access: ";
359                       if ( defined $decoded->SubjectInfoAccess ) {
360                               my %SIA = $decoded->SubjectInfoAccess;
361                               for my $key ( keys %SIA ) {
362                                       print "\n\t$key: \n\t";
363                                       print join( "\n\t" , @{ $SIA{$key} } ), "\n";
364                               }
365                       } else { print "\n" }
366
367               Example Output:
368                       Subject Info Access:
369                               1.3.6.1.5.5.7.48.5:
370                               uniformResourceIdentifier = http://pki.treas.gov/root_sia.p7c
371                               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
372
373   PGPExtension
374       Returns the creation timestamp of the corresponding OpenPGP key.  (see
375       http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)
376
377                       print "PGPExtension: ";
378                       if ( defined $decoded->PGPExtension ) {
379                               my $creationtime = $decoded->PGPExtension;
380                               printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
381                       }
382
383               Example Output:
384                       PGPExtension:
385                           whatever
386

SEE ALSO

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

ACKNOWLEDGEMENTS

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

AUTHORS

397       Mike Jackson <mj@sci.fi>, Alexander Jung <alexander.w.jung@gmail.com>,
398       Duncan Segrest <duncan@gigageek.info>
399
401       Copyright (c) 2005 Mike Jackson <mj@sci.fi>.  Copyright (c) 2001-2002
402       Norbert Klasen, DAASI International GmbH.
403
404       All rights reserved. This program is free software; you can
405       redistribute it and/or modify it under the same terms as Perl itself.
406
407
408
409perl v5.28.1                      2011-07-06                    Crypt::X509(3)
Impressum