1Crypt-X509-CRL version 0.4
2
3Crypt::X509::CRL is an object oriented X.509 certificate revocation list
4parser with numerous methods for directly extracting information from
5certificate revocation lists.
6
7
8INSTALLATION
9
10To install this module, run the following commands:
11
12 perl Makefile.PL
13 make
14 make test
15 make install
16
17
18SUPPORT AND DOCUMENTATION
19
20After installing, you can find documentation for this module with the
21perldoc command.
22
23 perldoc Crypt::X509::CRL
24
25You can also look for information at:
26
27 RT, CPAN's request tracker (report bugs here)
28 https://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-X509-CRL
29
30 CPAN Ratings
31 https://cpanratings.perl.org/d/Crypt-X509-CRL
32
33 Search CPAN
34 https://metacpan.org/release/Crypt-X509-CRL
35
36
37DEPENDENCIES
38 This module requires:
39
40 Convert::ASN1
41
42
43NAME
44 Crypt::X509::CRL - Parses an X.509 certificate revocation list
45
46
47SYNOPSIS
48 use Crypt::X509::CRL;
49
50 $decoded = Crypt::X509::CRL->new( crl => $crl );
51
52 $subject_email = $decoded->subject_email;
53 print "do not use after: ".gmtime($decoded->not_after)." GMT\n";
54
55
56REQUIRES
57 Convert::ASN1
58
59DESCRIPTION
60 Crypt::X509::CRL parses X.509 certificate revocation lists. Methods are
61 provided for accessing most CRL elements.
62
63 It is based on the generic ASN.1 module by Graham Barr, on the
64 x509decode example by Norbert Klasen and contributions on the
65 perl-ldap-dev-Mailinglist by Chriss Ridd. It is also based upon the
66 works of Mike Jackson and Alexander Jung perl module Crypt::X509.
67
68 The following RFC 3280 Extensions are available (noted are the ones I
69 have implemented).
70
71 Authority Key Identifier (implemented)
72 CRL Number (implemented)
73 Issuing Distribution Point (implemented)
74 Issuer Alternative Name
75 Delta CRL Indicator
76 Freshest CRL (a.k.a. Delta CRL Distribution Point)
77
78 The following RFC 3280 CRL Entry Extensions are available (noted are the
79 ones I have implemented).
80
81 Reason Code (implemented)
82 Hold Instruction Code (implemented)
83 Invalidity Date (implemented)
84 Certificate Issuer
85
86 NOTE: The use of 'utcTime' in determining the revocation date of a given
87 certificate is based on RFC 3280 for dates through the year 2049.
88 Starting with dates in 2050 and beyond the RFC calls for revocation
89 dates to be listed as 'generalTime'.
90
91CONSTRUCTOR
92 new ( OPTIONS )
93 Creates and returns a parsed X.509 CRL hash, containing the parsed
94 contents. The data is organised as specified in RFC 2459. By default
95 only the first ASN.1 Layer is decoded. Nested decoding is done
96 automagically through the data access methods.
97
98 crl => $crl
99 A variable containing the DER formatted crl to be parsed (eg. as
100 stored in "certificateRevocationList;binary" attribute in an
101 LDAP-directory).
102
103 Example:
104 use Crypt::X509::CRL;
105 use Data::Dumper;
106
107 $decoded = Crypt::X509::CRL->new( crl => $crl );
108
109 print Dumper $decoded;
110
111METHODS
112 error
113 Returns the last error from parsing, "undef" when no error occured. This
114 error is updated on deeper parsing with the data access methods.
115
116 Example:
117 $decoded= Crypt::X509::CRL->new(crl => $crl);
118 if ( $decoded->error ) {
119 warn "Error on parsing Certificate Revocation List: ", $decoded->error;
120 }
121
122DATA ACCESS METHODS
123 You can access all parsed data directly from the returned hash. For
124 convenience the following data access methods have been implemented to
125 give quick access to the most-used crl attributes.
126
127 version
128 Returns the certificate revocation list's version as an integer. Returns
129 undef if the version is not specified, since it is an optional field in
130 some cases.
131
132 NOTE that version is defined as an Integer where:
133 0 = v1
134 1 = v2
135 2 = v3
136
137 version_string
138 Returns the certificate revocation list's version as a string value (ie 'v1', 'v2', or 'v3').
139
140 this_update
141 Returns either the utcTime or generalTime of the certificate revocation
142 list's date of publication. Returns undef if not defined.
143
144 Example:
145 $decoded = Crypt::X509::CRL->new(crl => $crl);
146 print "CRL was published at ", gmtime( $decoded->this_update ), " GMT\n";
147
148 next_update
149 Returns either the utcTime or generalTime of the certificate revocation
150 list's date of expiration. Returns undef if not defined.
151
152 Example:
153 $decoded = Crypt::X509::CRL->new(crl => $crl);
154 if ( $decoded->next_update > time() ) {
155 warn "CRL has expired!";
156 }
157
158 signature
159 Return's the certificate's signature in binary DER format.
160
161 signature_length
162 Return's the length of the certificate's signature.
163
164 signature_algorithm
165 Returns the certificate's signature algorithm as an OID string.
166
167 Example:
168 $decoded = Crypt::X509::CRL->new(crl => $crl);
169 print "CRL signature is encrypted with:", $decoded->signature_algorithm, "\n";
170
171 Example Output: CRL signature is encrypted with: 1.2.840.113549.1.1.5
172
173 SigEncAlg
174 Returns the signature encryption algorithm (e.g. 'RSA') as a string.
175
176 Example:
177 $decoded = Crypt::X509::CRL->new(crl => $crl);
178 print "CRL signature is encrypted with:", $decoded->SigEncAlg, "\n";
179
180 Example Output:
181 CRL signature is encrypted with: RSA
182
183 SigHashAlg
184 Returns the signature hashing algorithm (e.g. 'SHA1') as a string.
185
186 Example:
187 $decoded = Crypt::X509::CRL->new(crl => $crl);
188 print "CRL signature is hashed with:", $decoded->SigHashAlg, "\n";
189
190 Example Output:
191 CRL signature is encrypted with: SHA1
192
193 Issuer
194 Returns a pointer to an array of strings building the DN of the
195 certificate issuer (= the DN of the CA). Attribute names for the most
196 common Attributes are translated from the OID-Numbers, unknown numbers
197 are output verbatim.
198
199 Example:
200 $decoded = Crypt::X509::CRL->new( $crl );
201 print "CRL was issued by: ", join( ', ' , @{ $decoded->Issuer } ), "\n";
202
203 issuer_cn
204 Returns the string value for issuer's common name (= the value with the
205 OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the first
206 entry is returned. "undef" if issuer contains no common name attribute.
207
208 issuer_country
209 Returns the string value for issuer's country (= the value with the OID
210 2.5.4.6 or in DN Syntax everything after "C="). Only the first entry is
211 returned. "undef" if issuer contains no country attribute.
212
213 issuer_state
214 Returns the string value for issuer's state or province (= the value
215 with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the
216 first entry is returned. "undef" if issuer contains no state attribute.
217
218 issuer_locality
219 Returns the string value for issuer's locality (= the value with the OID
220 2.5.4.7 or in DN Syntax everything after "L="). Only the first entry is
221 returned. "undef" if issuer contains no locality attribute.
222
223 issuer_org
224 Returns the string value for issuer's organization (= the value with the
225 OID 2.5.4.10 or in DN Syntax everything after "O="). Only the first
226 entry is returned. "undef" if issuer contains no organization attribute.
227
228 issuer_email
229 Returns the string value for issuer's email address (= the value with
230 the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E=").
231 Only the first entry is returned. "undef" if issuer contains no email
232 attribute.
233
234 key_identifier
235 Returns the authority key identifier as a bit string.
236
237 Example:
238 $decoded = Crypt::X509::CRL->new( $crl );
239 my $s = unpack("H*" , $decoded->key_identifier);
240 print "The Authority Key Identifier in HEX is: $s\n";
241
242 Example output:
243 The Authority Key Identifier in HEX is: 86595f93caf32da620a4f9595a4a935370e792c9
244
245 authorityCertIssuer
246 Returns a pointer to an array of strings building the DN of the
247 Authority Cert Issuer. Attribute names for the most common Attributes
248 are translated from the OID-Numbers, unknown numbers are output
249 verbatim. Returns undef if the extension is not set in the certificate.
250
251 Example:
252 $decoded = Crypt::X509::CRL->new($cert);
253 print "Certificate was authorised by:", join( ', ', @{ $decoded->authorityCertIssuer } ), "\n";
254
255 authority_serial
256 Returns the authority's certificate serial number.
257
258 authority_cn
259 Returns the authority's ca.
260
261 authority_country
262 Returns the authority's country.
263
264 authority_state
265 Returns the authority's state.
266
267 authority_locality
268 Returns the authority's locality.
269
270 authority_org
271 Returns the authority's organization.
272
273 authority_email
274 Returns the authority's email.
275
276 crl_number
277 Returns the CRL Number as an integer.
278
279 IDPs
280 Returns the Issuing Distribution Points as a hash providing for the
281 default values.
282
283 Example:
284 print "Issuing Distribution Points:\n";
285 my $IDPs = $decoded->IDPs;
286 for my $key ( sort keys %{ $IDPs } ) {
287 print "$key = ";
288 if ( defined $IDPs->{ $key } ) {
289 print $IDPs->{ $key }, "\n";
290 } else {
291 print "undef\n";
292 }
293 }
294
295 Example Output:
296 Issuing Distribution Points:
297 critical = 1
298 directory_addr = CN=CRL2, O=U.S. Government, C=US
299 indirectCRL = 0
300 onlyAttribCerts = 0
301 onlyCaCerts = 0
302 onlyUserCerts = 1
303 reasonFlags = undef
304 url = undef
305
306 Example of returned data structure:
307 critical = 0 or 1 # default is FALSE
308 directory_addr = CN=CR1,c=US # default is undef
309 url = ldap://ldap.gov/cn=CRL1,c=US # default is undef
310 onlyUserCerts = 0 or 1 # default is FALSE
311 onlyCaCerts = 0 or 1 # default is FALSE
312 onlyAttribCerts = 0 or 1 # default is FALSE
313 indirectCRL = 0 or 1 # default is FALSE
314 reasonFlags = BIT STRING # default is undef
315
316 revocation_list
317 Returns an array of hashes for the revoked certificates listed on the
318 given CRL. The keys to the hash are the certificate serial numbers in
319 decimal format.
320
321 Example:
322 print "Revocation List:\n";
323 my $rls = $decoded->revocation_list;
324 my $count_of_rls = keys %{ $rls };
325 print "Found $count_of_rls revoked certificate(s) on this CRL.\n";
326 for my $key ( sort keys %{ $rls } ) {
327 print "Certificate: ", DecimalToHex( $key ), "\n";
328 for my $extn ( sort keys %{ $rls->{ $key } } ) {
329 if ( $extn =~ /date/i ) {
330 print "\t$extn: ", ConvertTime( $rls->{ $key }{ $extn } ), "\n";
331 } else {
332 print "\t$extn: ", $rls->{ $key }{ $extn }, "\n";
333 }
334 }
335 }
336
337 Example Output:
338 Revocation List:
339 Found 1 revoked certificate(s) on this CRL.
340 Certificate: 44 53 a0 f3
341 crlReason: keyCompromise
342 invalidityDate: Wednesday, September 27, 2006 12:54:51 PM
343 revocationDate: Wednesday, September 27, 2006 1:29:36 PM
344
345SEE ALSO
346 See the examples of "Convert::ASN1" and the <perl-ldap@perl.org> Mailing
347 List. An example on how to load certificates can be found in
348 t\Crypt-X509-CRL.t.
349
350
351ACKNOWLEDGEMENTS
352 This module is based on the x509decode script, which was contributed to
353 Convert::ASN1 in 2002 by Norbert Klasen.
354
355 It is also based on the Crypt::X509 perl module, which was contributed
356 by Mike Jackson and Alexander Jung.
357
358
359AUTHOR
360 Duncan Segrest
361
362
363LICENSE AND COPYRIGHT
364 This software is Copyright (c) 2007 by Duncan Segrest.
365
366 This is free software, licensed under:
367
368 The Artistic License 2.0 (GPL Compatible)
369