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
201       "emailAddress=").  Only the first entry is returned. "undef" if subject
202       contains no email 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   DecodedSubjectAltNames
289       Returns a pointer to an array of strings containing all the alternative
290       subject name extensions.
291
292       Each such extension is represented as a decoded ASN.1 value, i.e. a
293       pointer to a list of pointers to objects, each object having a single
294       key with the type of the alternative name and a value specific to that
295       type.
296
297       Example return value:
298
299         [
300           [
301             {
302               'directoryName' => {
303                 'rdnSequence' => [
304                   [
305                     {
306                       'value' => { 'utf8String' => 'example' },
307                       'type' => '2.5.4.3'
308                     }
309                   ]
310                 ]
311               }
312             },
313             {
314               'dNSName' => 'example.com'
315             }
316           ]
317         ]
318
319   authorityCertIssuer
320       returns a pointer to an array of strings building the DN of the
321       Authority Cert Issuer. Attributenames for the most common Attributes
322       are translated from the OID-Numbers, unknown numbers are output
323       verbatim.  undef if the extension is not set in the certificate.
324
325         $decoded= Crypt::X509->new($cert);
326         print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";
327
328   authority_serial
329       Returns the authority's certificate serial number.
330
331   key_identifier
332       Returns the authority key identifier or undef if it is a rooted cert
333
334   authority_cn
335       Returns the authority's ca.
336
337   authority_country
338       Returns the authority's country.
339
340   authority_state
341       Returns the authority's state.
342
343   authority_locality
344       Returns the authority's locality.
345
346   authority_org
347       Returns the authority's organization.
348
349   authority_email
350       Returns the authority's email.
351
352   CRLDistributionPoints
353       Returns the CRL distribution points as an array of strings (with one
354       value usually)
355
356   CRLDistributionPoints2
357       Returns the CRL distribution points as an array of hashes (allowing for
358       some variations)
359
360   CertificatePolicies
361       Returns the CertificatePolicies as an array of strings
362
363   EntrustVersionInfo
364       Returns the EntrustVersion as a string
365
366           print "Entrust Version: ", $decoded->EntrustVersion, "\n";
367
368           Example Output: Entrust Version: V7.0
369
370   SubjectDirectoryAttributes
371       Returns the SubjectDirectoryAttributes as an array of key = value
372       pairs, to include a data type
373
374           print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";
375
376           Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)
377
378   BasicConstraints
379       Returns the BasicConstraints as an array and the criticallity pre-
380       pended.
381
382   subject_keyidentifier
383       Returns the subject key identifier from the extensions.
384
385   SubjectInfoAccess
386       Returns the SubjectInfoAccess as an array of hashes with key=value
387       pairs.
388
389               print "Subject Info Access: ";
390               if ( defined $decoded->SubjectInfoAccess ) {
391                   my %SIA = $decoded->SubjectInfoAccess;
392                   for my $key ( keys %SIA ) {
393                       print "\n\t$key: \n\t";
394                       print join( "\n\t" , @{ $SIA{$key} } ), "\n";
395                   }
396               } else { print "\n" }
397
398           Example Output:
399               Subject Info Access:
400                   1.3.6.1.5.5.7.48.5:
401                   uniformResourceIdentifier = http://pki.treas.gov/root_sia.p7c
402                   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
403
404   PGPExtension
405       Returns the creation timestamp of the corresponding OpenPGP key.  (see
406       http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)
407
408               print "PGPExtension: ";
409               if ( defined $decoded->PGPExtension ) {
410                   my $creationtime = $decoded->PGPExtension;
411                   printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
412                       }
413
414           Example Output:
415               PGPExtension:
416                           whatever
417

SEE ALSO

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

ACKNOWLEDGEMENTS

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

AUTHORS

428       Mike Jackson <mj@sci.fi>, Alexander Jung <alexander.w.jung@gmail.com>,
429       Duncan Segrest <duncan@gigageek.info> Oliver Welter
430       <owelter@whiterabbitsecurity.com>
431
433       Copyright (c) 2005 Mike Jackson <mj@sci.fi>.  Copyright (c) 2001-2002
434       Norbert Klasen, DAASI International GmbH.
435
436       All rights reserved. This program is free software; you can
437       redistribute it and/or modify it under the same terms as Perl itself.
438
439
440
441perl v5.36.0                      2022-07-22                    Crypt::X509(3)
Impressum