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 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 $decoded= Crypt::X509->new($cert);
295 print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";
296 authority_serial
298 Returns the authority's certificate serial number.
299 key_identifier
301 Returns the authority key identifier or undef if it is a rooted cert
302 authority_cn
304 Returns the authority's ca.
305 authority_country
307 Returns the authority's country.
308 authority_state
310 Returns the authority's state.
311 authority_locality
313 Returns the authority's locality.
314 authority_org
316 Returns the authority's organization.
317 authority_email
319 Returns the authority's email.
320 CRLDistributionPoints
322 Returns the CRL distribution points as an array of strings (with one
323 value usually)
324 CRLDistributionPoints2
326 Returns the CRL distribution points as an array of hashes (allowing for
327 some variations)
328 CertificatePolicies
330 Returns the CertificatePolicies as an array of strings
331 EntrustVersionInfo
333 Returns the EntrustVersion as a string
334 print "Entrust Version: ", $decoded->EntrustVersion, "\n";
336 Example Output: Entrust Version: V7.0
338 SubjectDirectoryAttributes
340 Returns the SubjectDirectoryAttributes as an array of key = value
341 pairs, to include a data type
342 print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";
344 Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)
346 BasicConstraints
348 Returns the BasicConstraints as an array and the criticallity pre-
349 pended.
350 subject_keyidentifier
352 Returns the subject key identifier from the extensions.
353 SubjectInfoAccess
355 Returns the SubjectInfoAccess as an array of hashes with key=value
356 pairs.
357 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 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 PGPExtension
374 Returns the creation timestamp of the corresponding OpenPGP key. (see
375 http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)
376 print "PGPExtension: ";
378 if ( defined $decoded->PGPExtension ) {
379 my $creationtime = $decoded->PGPExtension;
380 printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
381 }
382 Example Output:
384 PGPExtension:
385 whatever
386
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
393 This module is based on the x509decode script, which was contributed to
394 Convert::ASN1 in 2002 by Norbert Klasen.
395
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 All rights reserved. This program is free software; you can
405 redistribute it and/or modify it under the same terms as Perl itself.
406perl v5.28.1 2011-07-06 Crypt::X509(3)