1Crypt::X509(3) User Contributed Perl Documentation Crypt::X509(3)
2
6 Crypt::X509 - Parse a X.509 certificate
7
9 use Crypt::X509;
10 $decoded = Crypt::X509->new( cert => $cert );
12 $subject_email = $decoded->subject_email;
14 print "do not use after: ".gmtime($decoded->not_after)." GMT\n";
15
17 Convert::ASN1
18
20 Crypt::X509 parses X.509 certificates. Methods are provided for
21 accessing most certificate elements.
22 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
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 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 use Crypt::X509;
40 use Data::Dumper;
41 $decoded= Crypt::X509->new(cert => $cert);
43 print Dumper($decoded);
45
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 $decoded= Crypt::X509->new(cert => $cert);
52 if ($decoded->error) {
53 warn "Error on parsing Certificate:".$decoded->error;
54 }
55
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 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 version_string
66 Returns the certificate's version as a string value.
67 serial
69 returns the serial number (integer or Math::BigInt Object, that gets
70 automagic evaluated in scalar context) from the certificate
71 $decoded= Crypt::X509->new(cert => $cert);
73 print "Certificate has serial number:".$decoded->serial."\n";
74 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 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 $decoded= Crypt::X509->new(cert => $cert);
86 if ($decoded->notBefore < time()) {
87 warn "Certificate: not yet valid!";
88 }
89 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 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 $decoded= Crypt::X509->new(cert => $cert);
101 print "Certificate expires on ".gmtime($decoded->not_after)." GMT\n";
102 signature
104 Return's the certificate's signature in binary DER format.
105 pubkey
107 Returns the certificate's public key in binary DER format.
108 pubkey_size
110 Returns the certificate's public key size.
111 pubkey_algorithm
113 Returns the algorithm as OID string which the public key was created
114 with.
115 PubKeyAlg
117 returns the subject public key encryption algorithm (e.g. 'RSA') as
118 string.
119 $decoded= Crypt::X509->new(cert => $cert);
121 print "Certificate public key is encrypted with:".$decoded->PubKeyAlg."\n";
122 Example Output: Certificate public key is encrypted with: RSA
124 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 For other pubkey types, it returns undef (implementations welcome!).
131 sig_algorithm
133 Returns the certificate's signature algorithm as OID string
134 $decoded= Crypt::X509->new(cert => $cert);
136 print "Certificate signature is encrypted with:".$decoded->sig_algorithm."\n";>
137 Example Output: Certificate signature is encrypted with: 1.2.840.113549.1.1.5
139 SigEncAlg
141 returns the signature encryption algorithm (e.g. 'RSA') as string.
142 $decoded= Crypt::X509->new(cert => $cert);
144 print "Certificate signature is encrypted with:".$decoded->SigEncAlg."\n";
145 Example Output: Certificate signature is encrypted with: RSA
147 SigHashAlg
149 returns the signature hashing algorithm (e.g. 'SHA1') as string.
150 $decoded= Crypt::X509->new(cert => $cert);
152 print "Certificate signature is hashed with:".$decoded->SigHashAlg."\n";
153 Example Output: Certificate signature is encrypted with: SHA1
155 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 $decoded= Convert::ASN1::X509->new($cert);
162 print "DN for this Certificate is:".join(',',@{$decoded->Subject})."\n";
163 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 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 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 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 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 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 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 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 $decoded= Crypt::X509->new($cert);
211 print "Certificate was issued by:".join(',',@{$decoded->Issuer})."\n";
212 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 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 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 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 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 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 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 If the extension is marked critical, this is also reported.
251 $decoded= Crypt::X509->new(cert => $cert);
253 print "Allowed usages for this Certificate are:\n".join("\n",@{$decoded->KeyUsage})."\n";
254 Example Output:
256 Allowed usages for this Certificate are:
257 critical
258 digitalSignature
259 keyEncipherment
260 dataEncipherment
261 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 If the extension is marked critical, this is also reported.
269 $decoded= Crypt::X509->new($cert);
271 print "ExtKeyUsage extension of this Certificates is: ", join(", ", @{$decoded->ExtKeyUsage}), "\n";
272 Example Output: ExtKeyUsage extension of this Certificates is: critical, serverAuth
274 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 It also pre-pends the field type (ie rfc822Name) to the returned value.
282 $decoded= Crypt::X509->new($cert);
284 print "E-Mail or Hostnames in this Certificates is/are:", join(", ", @{$decoded->SubjectAltName}), "\n";
285 Example Output: E-Mail or Hostnames in this Certificates is/are: rfc822Name=user@server.com
287 DecodedSubjectAltNames
289 Returns a pointer to an array of strings containing all the alternative
290 subject name extensions.
291 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 Example return value:
298 [
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 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 $decoded= Crypt::X509->new($cert);
326 print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";
327 authority_serial
329 Returns the authority's certificate serial number.
330 key_identifier
332 Returns the authority key identifier or undef if it is a rooted cert
333 authority_cn
335 Returns the authority's ca.
336 authority_country
338 Returns the authority's country.
339 authority_state
341 Returns the authority's state.
342 authority_locality
344 Returns the authority's locality.
345 authority_org
347 Returns the authority's organization.
348 authority_email
350 Returns the authority's email.
351 CRLDistributionPoints
353 Returns the CRL distribution points as an array of strings (with one
354 value usually)
355 CRLDistributionPoints2
357 Returns the CRL distribution points as an array of hashes (allowing for
358 some variations)
359 CertificatePolicies
361 Returns the CertificatePolicies as an array of strings
362 EntrustVersionInfo
364 Returns the EntrustVersion as a string
365 print "Entrust Version: ", $decoded->EntrustVersion, "\n";
367 Example Output: Entrust Version: V7.0
369 SubjectDirectoryAttributes
371 Returns the SubjectDirectoryAttributes as an array of key = value
372 pairs, to include a data type
373 print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";
375 Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)
377 BasicConstraints
379 Returns the BasicConstraints as an array and the criticallity pre-
380 pended.
381 subject_keyidentifier
383 Returns the subject key identifier from the extensions.
384 SubjectInfoAccess
386 Returns the SubjectInfoAccess as an array of hashes with key=value
387 pairs.
388 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 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 PGPExtension
405 Returns the creation timestamp of the corresponding OpenPGP key. (see
406 http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)
407 print "PGPExtension: ";
409 if ( defined $decoded->PGPExtension ) {
410 my $creationtime = $decoded->PGPExtension;
411 printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
412 }
413 Example Output:
415 PGPExtension:
416 whatever
417
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
424 This module is based on the x509decode script, which was contributed to
425 Convert::ASN1 in 2002 by Norbert Klasen.
426
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 All rights reserved. This program is free software; you can
437 redistribute it and/or modify it under the same terms as Perl itself.
438perl v5.32.1 2021-01-27 Crypt::X509(3)