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 SubjectRaw
165 Returns the RDNs as list of hashes, values are stringified but OIDs are
166 not translated.
167 If a component contains a SET, the component will become an array of
169 hashes on the second level.
170 SubjectSequence
172 Returns the subject as returned from the ASN1 parser.
173 subject_country
175 Returns the string value for subject's country (= the value with the
176 OID 2.5.4.6 or in DN Syntax everything after "C="). Only the first
177 entry is returned. "undef" if subject contains no country attribute.
178 subject_locality
180 Returns the string value for subject's locality (= the value with the
181 OID 2.5.4.7 or in DN Syntax everything after "l="). Only the first
182 entry is returned. "undef" if subject contains no locality attribute.
183 subject_state
185 Returns the string value for subject's state or province (= the value
186 with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the
187 first entry is returned. "undef" if subject contains no state
188 attribute.
189 subject_org
191 Returns the string value for subject's organization (= the value with
192 the OID 2.5.4.10 or in DN Syntax everything after "O="). Only the
193 first entry is returned. "undef" if subject contains no organization
194 attribute.
195 subject_ou
197 Returns the string value for subject's organizational unit (= the value
198 with the OID 2.5.4.11 or in DN Syntax everything after "OU="). Only
199 the first entry is returned. "undef" if subject contains no
200 organization attribute.
201 subject_cn
203 Returns the string value for subject's common name (= the value with
204 the OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the
205 first entry is returned. "undef" if subject contains no common name
206 attribute.
207 subject_email
209 Returns the string value for subject's email address (= the value with
210 the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after
211 "emailAddress="). Only the first entry is returned. "undef" if subject
212 contains no email attribute.
213 Issuer
215 returns a pointer to an array of strings building the DN of the
216 certificate issuer (= the DN of the CA). Attributenames for the most
217 common Attributes are translated from the OID-Numbers, unknown numbers
218 are output verbatim.
219 $decoded= Crypt::X509->new($cert);
221 print "Certificate was issued by:".join(',',@{$decoded->Issuer})."\n";
222 issuer_cn
224 Returns the string value for issuer's common name (= the value with the
225 OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the first
226 entry is returned. "undef" if issuer contains no common name attribute.
227 issuer_country
229 Returns the string value for issuer's country (= the value with the
230 OID 2.5.4.6 or in DN Syntax everything after "C="). Only the first
231 entry is returned. "undef" if issuer contains no country attribute.
232 issuer_state
234 Returns the string value for issuer's state or province (= the value
235 with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the
236 first entry is returned. "undef" if issuer contains no state attribute.
237 issuer_locality
239 Returns the string value for issuer's locality (= the value with the
240 OID 2.5.4.7 or in DN Syntax everything after "L="). Only the first
241 entry is returned. "undef" if issuer contains no locality attribute.
242 issuer_org
244 Returns the string value for issuer's organization (= the value with
245 the OID 2.5.4.10 or in DN Syntax everything after "O="). Only the
246 first entry is returned. "undef" if issuer contains no organization
247 attribute.
248 issuer_email
250 Returns the string value for issuer's email address (= the value with
251 the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E=").
252 Only the first entry is returned. "undef" if issuer contains no email
253 attribute.
254 KeyUsage
256 returns a pointer to an array of strings describing the valid Usages
257 for this certificate. "undef" is returned, when the extension is not
258 set in the certificate.
259 If the extension is marked critical, this is also reported.
261 $decoded= Crypt::X509->new(cert => $cert);
263 print "Allowed usages for this Certificate are:\n".join("\n",@{$decoded->KeyUsage})."\n";
264 Example Output:
266 Allowed usages for this Certificate are:
267 critical
268 digitalSignature
269 keyEncipherment
270 dataEncipherment
271 ExtKeyUsage
273 returns a pointer to an array of ExtKeyUsage strings (or OIDs for
274 unknown OIDs) or "undef" if the extension is not filled. OIDs of the
275 following ExtKeyUsages are known: serverAuth, clientAuth, codeSigning,
276 emailProtection, timeStamping, OCSPSigning
277 If the extension is marked critical, this is also reported.
279 $decoded= Crypt::X509->new($cert);
281 print "ExtKeyUsage extension of this Certificates is: ", join(", ", @{$decoded->ExtKeyUsage}), "\n";
282 Example Output: ExtKeyUsage extension of this Certificates is: critical, serverAuth
284 SubjectAltName
286 returns a pointer to an array of strings containing alternative
287 Subjectnames or "undef" if the extension is not filled. Usually this
288 Extension holds the e-Mail address for person-certificates or DNS-Names
289 for server certificates.
290 It also pre-pends the field type (ie rfc822Name) to the returned value.
292 $decoded= Crypt::X509->new($cert);
294 print "E-Mail or Hostnames in this Certificates is/are:", join(", ", @{$decoded->SubjectAltName}), "\n";
295 Example Output: E-Mail or Hostnames in this Certificates is/are: rfc822Name=user@server.com
297 DecodedSubjectAltNames
299 Returns a pointer to an array of strings containing all the alternative
300 subject name extensions.
301 Each such extension is represented as a decoded ASN.1 value, i.e. a
303 pointer to a list of pointers to objects, each object having a single
304 key with the type of the alternative name and a value specific to that
305 type.
306 Example return value:
308 [
310 [
311 {
312 'directoryName' => {
313 'rdnSequence' => [
314 [
315 {
316 'value' => { 'utf8String' => 'example' },
317 'type' => '2.5.4.3'
318 }
319 ]
320 ]
321 }
322 },
323 {
324 'dNSName' => 'example.com'
325 }
326 ]
327 ]
328 authorityCertIssuer
330 returns a pointer to an array of strings building the DN of the
331 Authority Cert Issuer. Attributenames for the most common Attributes
332 are translated from the OID-Numbers, unknown numbers are output
333 verbatim. undef if the extension is not set in the certificate.
334 $decoded= Crypt::X509->new($cert);
336 print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";
337 authority_serial
339 Returns the authority's certificate serial number.
340 key_identifier
342 Returns the authority key identifier or undef if it is a rooted cert
343 authority_cn
345 Returns the authority's ca.
346 authority_country
348 Returns the authority's country.
349 authority_state
351 Returns the authority's state.
352 authority_locality
354 Returns the authority's locality.
355 authority_org
357 Returns the authority's organization.
358 authority_email
360 Returns the authority's email.
361 CRLDistributionPoints
363 Returns the CRL distribution points as an array of strings (with one
364 value usually)
365 CRLDistributionPoints2
367 Returns the CRL distribution points as an array of hashes (allowing for
368 some variations)
369 CertificatePolicies
371 Returns the CertificatePolicies as an array of strings
372 EntrustVersionInfo
374 Returns the EntrustVersion as a string
375 print "Entrust Version: ", $decoded->EntrustVersion, "\n";
377 Example Output: Entrust Version: V7.0
379 SubjectDirectoryAttributes
381 Returns the SubjectDirectoryAttributes as an array of key = value
382 pairs, to include a data type
383 print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";
385 Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)
387 BasicConstraints
389 Returns the BasicConstraints as an array and the criticallity pre-
390 pended.
391 subject_keyidentifier
393 Returns the subject key identifier from the extensions.
394 SubjectInfoAccess
396 Returns the SubjectInfoAccess as an array of hashes with key=value
397 pairs.
398 print "Subject Info Access: ";
400 if ( defined $decoded->SubjectInfoAccess ) {
401 my %SIA = $decoded->SubjectInfoAccess;
402 for my $key ( keys %SIA ) {
403 print "\n\t$key: \n\t";
404 print join( "\n\t" , @{ $SIA{$key} } ), "\n";
405 }
406 } else { print "\n" }
407 Example Output:
409 Subject Info Access:
410 1.3.6.1.5.5.7.48.5:
411 uniformResourceIdentifier = http://pki.treas.gov/root_sia.p7c
412 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
413 PGPExtension
415 Returns the creation timestamp of the corresponding OpenPGP key. (see
416 http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)
417 print "PGPExtension: ";
419 if ( defined $decoded->PGPExtension ) {
420 my $creationtime = $decoded->PGPExtension;
421 printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
422 }
423 Example Output:
425 PGPExtension:
426 whatever
427
429 See the examples of "Convert::ASN1" and the <perl-ldap@perl.org>
430 Mailing List. An example on how to load certificates can be found in
431 t\Crypt-X509.t.
432
434 This module is based on the x509decode script, which was contributed to
435 Convert::ASN1 in 2002 by Norbert Klasen.
436
438 Mike Jackson <mj@sci.fi>, Alexander Jung <alexander.w.jung@gmail.com>,
439 Duncan Segrest <duncan@gigageek.info> Oliver Welter
440 <owelter@whiterabbitsecurity.com>
441
443 Copyright (c) 2005 Mike Jackson <mj@sci.fi>. Copyright (c) 2001-2002
444 Norbert Klasen, DAASI International GmbH.
445 All rights reserved. This program is free software; you can
447 redistribute it and/or modify it under the same terms as Perl itself.
448perl v5.36.0 2023-03-03 Crypt::X509(3)