README
1NAME
2
3 Crypt::PKCS10 - parse PKCS #10 certificate requests
4
5VERSION
6
7 version 1.800201
8
9SYNOPSIS
10
11 use Crypt::PKCS10;
12
13 Crypt::PKCS10->setAPIversion( 1 );
14 my $decoded = Crypt::PKCS10->new( $csr ) or die Crypt::PKCS10->error;
15
16 print $decoded;
17
18 @names = $decoded->extensionValue('subjectAltName' );
19 @names = $decoded->subject unless( @names );
20
21 %extensions = map { $_ => $decoded->extensionValue( $_ ) } $decoded->extensions
22
23DESCRIPTION
24
25 Crypt::PKCS10 parses PKCS #10 certificate requests (CSRs) and provides
26 accessor methods to extract the data in usable form.
27
28 Common object identifiers will be translated to their corresponding
29 names. Additionally, accessor methods allow extraction of single data
30 fields. The format of returned data varies by accessor.
31
32 The access methods return the value corresponding to their name. If
33 called in scalar context, they return the first value (or an empty
34 string). If called in array context, they return all values.
35
36 true values should be specified as 1 and false values as 0. Future API
37 changes may provide different functions when other values are used.
38
39 This file is automatically generated by pod2readme from PKCS10.pm and Changes.
40
41NAME
42
43 Crypt::PKCS10 - parse PKCS #10 certificate requests
44
45RELEASE NOTES
46
47 Version 1.4 made several API changes. Most users should have a painless
48 migration.
49
50 ALL users must call Crypt::PKCS10->setAPIversion. If not, a warning
51 will be generated by the first class method called. This warning will
52 be made a fatal exception in a future release.
53
54 Other than that requirement, the legacy mode is compatible with
55 previous versions.
56
57 new will no longer generate exceptions. undef is returned on all
58 errors. Use the error class method to retrieve the reason.
59
60 new will accept an open file handle in addition to a request.
61
62 Users are encouraged to migrate to the version 1 API. It is much easier
63 to use, and does not require the application to navigate internal data
64 structures.
65
66 Version 1.7 provides support for DSA and ECC public keys. By default,
67 it verifies the signature of CSRs. It also allows the caller to verify
68 the signature of a CSR. subjectPublicKeyParams and signatureParams
69 provide additional information. The readFile option to new() will
70 open() a file containing a CSR by name. The ignoreNonBase64 option
71 allows PEM to contain extraneous characters. Changes describes
72 additional improvements. Details follow.
73
74INSTALLATION
75
76 Crypt::PKCS10 supports DSA, RSA and ECC public keys in CSRs.
77
78 It depends on Crypt::OpenSSL::DSA, Crypt::OpenSSL::RSA and
79 Crypt::PK::ECC for some operations. All are recommended. Some methods
80 will return errors if Crypt::PKCS10 is presented with a CSR containing
81 an unsupported public key type.
82
83 To install this module type the following:
84
85 perl Makefile.PL
86 make
87 make test
88 make install
89
90REQUIRES
91
92 Convert::ASN1
93
94 Crypt::OpenSSL::DSA
95
96 Crypt::OpenSSL::RSA
97
98 Crypt::PK::ECC
99
100 Digest::SHA
101
102 For ECC: Crypt::PK::ECC
103
104 Very old CSRs may require DIGEST::MD{5,4,2}
105
106METHODS
107
108 Access methods may exist for subject name components that are not
109 listed here. To test for these, use code of the form:
110
111 $locality = $decoded->localityName if( $decoded->can('localityName') );
112
113 If a name component exists in a CSR, the method will be present. The
114 converse is not (always) true.
115
116 class method setAPIversion( $version )
117
118 Selects the API version (0 or 1) expected.
119
120 Must be called before calling any other method.
121
122 The API version determines how a CSR is parsed. Changing the API
123 version after parsing a CSR will cause accessors to produce
124 unpredictable results.
125
126 Version 0 - DEPRECATED
127
128 Some OID names have spaces and descriptions
129
130 This is the format used for Crypt::PKCS10 version 1.3 and lower. The
131 attributes method returns legacy data.
132
133 Some new API functions are disabled.
134
135 Version 1
136
137 OID names from RFCs - or at least compatible with OpenSSL and ASN.1
138 notation. The attributes method conforms to version 1.
139
140 If not called, a warning will be generated and the API will default to
141 version 0.
142
143 In a future release, the warning will be changed to a fatal exception.
144
145 To ease migration, both old and new names are accepted by the API.
146
147 Every program should call setAPIversion(1).
148
149 class method getAPIversion
150
151 Returns the current API version.
152
153 Returns undef if setAPIversion has never been called.
154
155 class method new( $csr, %options )
156
157 Constructor, creates a new object containing the parsed PKCS #10
158 certificate request.
159
160 $csr may be a scalar containing the request, a file name, or a file
161 handle from which to read it.
162
163 If a file name is specified, the readFile option must be specified.
164
165 If a file handle is supplied, the caller should specify acceptPEM => 0
166 if the contents are DER.
167
168 The request may be PEM or binary DER encoded. Only one request is
169 processed.
170
171 If PEM, other data (such as mail headers) may precede or follow the
172 CSR.
173
174 my $decoded = Crypt::PKCS10->new( $csr ) or die Crypt::PKCS10->error;
175
176 Returns undef if there is an I/O error or the request can not be parsed
177 successfully.
178
179 Call error() to obtain more detail.
180
181 options
182
183 The options are specified as name => value.
184
185 If the first option is a HASHREF, it is expanded and any remaining
186 options are added.
187
188 acceptPEM
189
190 If false, the input must be in DER format. binmode will be called on
191 a file handle.
192
193 If true, the input is checked for a CERTIFICATE REQUEST header. If
194 not found, the csr is assumed to be in DER format.
195
196 Default is true.
197
198 PEMonly
199
200 If true, the input must be in PEM format. An error will be returned
201 if the input doesn't contain a CERTIFICATE REQUEST header. If false,
202 the input is parsed according to acceptPEM.
203
204 Default is false.
205
206 binaryMode
207
208 If true, an input file or file handle will be set to binary mode
209 prior to reading.
210
211 If false, an input file or file handle's binmode will not be
212 modified.
213
214 Defaults to false if acceptPEM is true, otherwise true.
215
216 dieOnError
217
218 If true, any API function that sets an error string will also die.
219
220 If false, exceptions are only generated for fatal conditions.
221
222 The default is false. API version 1 only..
223
224 escapeStrings
225
226 If true, strings returned for extension and attribute values are
227 '\'-escaped when formatted. This is compatible with OpenSSL
228 configuration files.
229
230 The special characters are: '\', '$', and '"'
231
232 If false, these strings are not '\'-escaped. This is useful when they
233 are being displayed to a human.
234
235 The default is true.
236
237 ignoreNonBase64
238
239 If true, most invalid base64 characters in PEM data will be ignored.
240 For example, this will accept CSRs prefixed with '> ', as e-mail when
241 the PEM is inadvertently quoted. Note that the BEGIN and END lines
242 may not be corrupted.
243
244 If false, invalid base64 characters in PEM data will cause the CSR to
245 be rejected.
246
247 The default is false.
248
249 readFile
250
251 If true, $csr is the name of a file containing the CSR.
252
253 If false, $csr contains the CSR or is an open file handle.
254
255 The default is false.
256
257 verifySignature
258
259 If true, the CSR's signature is checked. If verification fails, new
260 will fail. Requires API version 1.
261
262 If false, the CSR's signature is not checked.
263
264 The default is true for API version 1 and false for API version 0.
265
266 No exceptions are generated, unless dieOnError is set or new() is
267 called in void context.
268
269 The defaults will accept either PEM or DER from a string or file hande,
270 which will not be set to binary mode. Automatic detection of the data
271 format may not be reliable on file systems that represent text and
272 binary files differently. Set acceptPEM to false and PEMonly to match
273 the file type on these systems.
274
275 The object will stringify to a human-readable representation of the
276 CSR. This is useful for debugging and perhaps for displaying a request.
277 However, the format is not part of the API and may change. It should
278 not be parsed by automated tools.
279
280 Exception: The public key and extracted request are PEM blocks, which
281 other tools can extract.
282
283 If another object inherits from Crypt::PKCS10, it can extend the
284 representation by overloading or calling as_string.
285
286 {class} method error
287
288 Returns a string describing the last error encountered;
289
290 If called as an instance method, last error encountered by the object.
291
292 If called as a class method, last error encountered by the class.
293
294 Any method can reset the string to undef, so the results are only valid
295 immediately after a method call.
296
297 class method name2oid( $oid )
298
299 Returns the OID corresponding to a name returned by an access method.
300
301 Not in API v0;
302
303 csrRequest( $format )
304
305 Returns the binary (ASN.1) request (after conversion from PEM and
306 removal of any data beyond the length of the ASN.1 structure.
307
308 If $format is true, the request is returned as a PEM CSR. Otherwise as
309 a binary string.
310
311 certificationRequest
312
313 Returns the binary (ASN.1) section of the request that is signed by the
314 requestor.
315
316 The caller can verify the signature using signatureAlgorithm,
317 certificationRequest and signature(1).
318
319 Access methods for the subject's distinguished name
320
321 Note that subjectAltName is prefered, and that modern certificate users
322 will ignore the subject if subjectAltName is present.
323
324 subject( $format )
325
326 Returns the entire subject of the CSR.
327
328 In scalar context, returns the subject as a string in the form
329 /componentName=value,value. If format is true, long component names are
330 used. By default, abbreviations are used when they exist.
331
332 e.g. /countryName=AU/organizationalUnitName=Big org/organizationalUnitName=Smaller org
333 or /C=AU/OU=Big org/OU=Smaller org
334
335 In array context, returns an array of (componentName, [values]) pairs.
336 Abbreviations are not used.
337
338 Note that the order of components in a name is significant.
339
340 commonName
341
342 Returns the common name(s) from the subject.
343
344 my $cn = $decoded->commonName();
345
346 organizationalUnitName
347
348 Returns the organizational unit name(s) from the subject
349
350 organizationName
351
352 Returns the organization name(s) from the subject.
353
354 emailAddress
355
356 Returns the email address from the subject.
357
358 stateOrProvinceName
359
360 Returns the state or province name(s) from the subject.
361
362 countryName
363
364 Returns the country name(s) from the subject.
365
366 subjectAltName( $type )
367
368 Convenience method.
369
370 When $type is specified: returns the subject alternate name values of
371 the specified type in list context, or the first value of the specified
372 type in scalar context.
373
374 Returns undefined/empty list if no values of the specified type are
375 present, or if the subjectAltName extension is not present.
376
377 Types can be any of:
378
379 otherName
380 * rfc822Name
381 * dNSName
382 x400Address
383 directoryName
384 ediPartyName
385 * uniformResourceIdentifier
386 * iPAddress
387 * registeredID
388
389 The types marked with '*' are the most common.
390
391 If $type is not specified: In list context returns the types present in
392 the subjectAlternate name. In scalar context, returns the SAN as a
393 string.
394
395 version
396
397 Returns the structure version as a string, e.g. "v1" "v2", or "v3"
398
399 pkAlgorithm
400
401 Returns the public key algorithm according to its object identifier.
402
403 subjectPublicKey( $format )
404
405 If $format is true, the public key will be returned in PEM format.
406
407 Otherwise, the public key will be returned in its hexadecimal
408 representation
409
410 subjectPublicKeyParams
411
412 Returns a hash describing the public key. The contents vary depending
413 on the public key type.
414
415 Standard items:
416
417 keytype - ECC, RSA, DSA or undef
418
419 keytype will be undef if the key type is not supported. In this case,
420 error() returns a diagnostic message.
421
422 keylen - Approximate length of the key in bits.
423
424 Other items include:
425
426 For RSA, modulus and publicExponent.
427
428 For DSA, G, P and Q.
429
430 For ECC, curve, pub_x and pub_y. curve is an OID name.
431
432 Additional detail
433
434 subjectPublicKeyParams(1) returns the standard items, and may also
435 return detail, which is a hashref.
436
437 For ECC, the detail hash includes the curve definition constants.
438
439 signatureAlgorithm
440
441 Returns the signature algorithm according to its object identifier.
442
443 signatureParams
444
445 Returns the parameters associated with the signatureAlgorithm as
446 binary. Returns undef if none, or if NULL.
447
448 Note: In the future, some signatureAlgorithms may return a hashref of
449 decoded fields.
450
451 Callers are advised to check for a ref before decoding...
452
453 signature( $format )
454
455 The CSR's signature is returned.
456
457 If $format is 1, in binary.
458
459 If $format is 2, decoded as an ECDSA signature - returns hashref to r
460 and s.
461
462 Otherwise, in its hexadecimal representation.
463
464 attributes( $name )
465
466 A request may contain a set of attributes. The attributes are OIDs with
467 values. The most common is a list of requested extensions, but other
468 OIDs can also occur. Of those, challengePassword is typical.
469
470 For API version 0, this method returns a hash consisting of all
471 attributes in an internal format. This usage is deprecated.
472
473 For API version 1:
474
475 If $name is not specified, a list of attribute names is returned. The
476 list does not include the requestedExtensions attribute. For that, use
477 extensions();
478
479 If no attributes are present, the empty list (undef in scalar context)
480 is returned.
481
482 If $name is specified, the value of the extension is returned. $name
483 can be specified as a numeric OID.
484
485 In scalar context, a single string is returned, which may include lists
486 and labels.
487
488 cspName="Microsoft Strong Cryptographic Provider",keySpec=2,signature=("",0)
489
490 Special characters are escaped as described in options.
491
492 In array context, the value(s) are returned as a list of items, which
493 may be references.
494
495 print( " $_: ", scalar $decoded->attributes($_), "\n" )
496 foreach ($decoded->attributes);
497
498 See the module documentation for a list of known OID names.
499
500 It is too long to include here.
501
502 extensions
503
504 Returns an array containing the names of all extensions present in the
505 CSR. If no extensions are present, the empty list is returned.
506
507 The names vary depending on the API version; however, the returned
508 names are acceptable to extensionValue, extensionPresent, and name2oid.
509
510 The values of extensions vary, however the following code fragment will
511 dump most extensions and their value(s).
512
513 print( "$_: ", $decoded->extensionValue($_,1), "\n" ) foreach ($decoded->extensions);
514
515 The sample code fragment is not guaranteed to handle all cases.
516 Production code needs to select the extensions that it understands and
517 should respect the critical boolean. critical can be obtained with
518 extensionPresent.
519
520 extensionValue( $name, $format )
521
522 Returns the value of an extension by name, e.g. extensionValue(
523 'keyUsage' ). The name SHOULD be an API v1 name, but API v0 names are
524 accepted for compatibility. The name can also be specified as a numeric
525 OID.
526
527 If $format is 1, the value is a formatted string, which may include
528 lists and labels. Special characters are escaped as described in
529 options;
530
531 If $format is 0 or not defined, a string, or an array reference may be
532 returned. The array many contain any Perl variable type.
533
534 To interpret the value(s), you need to know the structure of the OID.
535
536 See the module documentation for a list of known OID names.
537
538 It is too long to include here.
539
540 extensionPresent( $name )
541
542 Returns true if a named extension is present: If the extension is
543 critical, returns 2. Otherwise, returns 1, indicating not critical, but
544 present.
545
546 If the extension is not present, returns undef.
547
548 The name can also be specified as a numeric OID.
549
550 See the module documentation for a list of known OID names.
551
552 It is too long to include here.
553
554 registerOID( )
555
556 Class method.
557
558 Register a custom OID, or a public OID that has not been added to
559 Crypt::PKCS10 yet.
560
561 The OID may be an extension identifier or an RDN component.
562
563 The oid is specified as a string in numeric form, e.g. '1.2.3.4'
564
565 registerOID( $oid )
566
567 Returns true if the specified OID is registered, false otherwise.
568
569 registerOID( $oid, $longname, $shortname )
570
571 Registers the specified OID with the associated long name. This enables
572 the OID to be translated to a name in output.
573
574 The long name should be Hungarian case (commonName), but this is not
575 currently enforced.
576
577 Optionally, specify the short name used for extracting the subject. The
578 short name should be upper-case (and will be upcased).
579
580 E.g. built-in are $oid => '2.4.5.3', $longname => 'commonName',
581 $shortname => 'CN'
582
583 To register a shortname for an existing OID without one, specify
584 $longname as undef.
585
586 E.g. To register /E for emailAddress, use: Crypt::PKCS10->registerOID(
587 '1.2.840.113549.1.9.1', undef, 'e' )
588
589 Generates an exception if any argument is not valid, or is in use.
590
591 Returns true otherwise.
592
593 checkSignature
594
595 Verifies the signature of a CSR. (Useful if new() specified
596 verifySignature => 0.)
597
598 Returns true if the signature is OK.
599
600 Returns false if the signature is incorrect. error() returns the
601 reason.
602
603 Returns undef if it was not possible to complete the verification
604 process (e.g. a required Perl module could not be loaded or an
605 unsupported key/signature type is present.)
606
607 certificateTemplate
608
609 CertificateTemplate returns the certificateTemplate attribute.
610
611 Equivalent to extensionValue( 'certificateTemplate' ), which is
612 prefered.
613
614CHANGES
615
616 1.0 2014-08-20
617
618
619
620 - Initial Version
621
622
623
624 1.1 2015-10-09
625
626
627
628 - Allow same OID elements in RDNs
629
630 - Support for all DirectoryStrings
631
632 - New accessor method: organizationName
633
634
635
636 1.2 2015-11-13
637
638
639
640 - Add generic method extensionValue
641
642 - Ommit unknown or damaged extensions
643
644
645
646 1.3 2015-11-17
647
648
649
650 - Experimental Perl features removed
651
652 - Refactored building process
653
654
655
656 1.4_01 2016-01-14
657
658
659
660 - Find PEM anywhere
661
662 - Support repeated attributes
663
664 - Various crashes, internal optimizations
665
666 - More OIDs
667
668 - Access methods: subject, subjectAltName, extensions
669
670 - Generate access methods for unknown OIDs in DNs at runtime
671
672 - Add extractCSR method to get CSR in binary or PEM
673
674 - subjectPublicKey option to extract in PEM format
675
676 - Convert IP addresses to strings
677
678 - Convert basicConstraints to string
679
680 - Add registerOID to allow extraction of simple custom OIDs
681
682 - More tests
683
684 - Improve documentation
685
686 - Add setAPIversion, regularize OID names in V1
687
688 - For API V1, attributes method returns names or values of attributes (except extensions)
689
690 - Improve build: Use Dist::Zilla, autogenerate README,LICENE,META,Makefile.PL
691
692 - Generate & ship Commitlog from git
693
694
695
696 1.4_02
697
698
699
700 - For API V1, omit space in key usage list
701
702 - Look for policy identifier names in all tables
703
704 - Decode certificatePolicyIdentifier, add related OIDs
705
706 - Avoid building un-necessary ASN.1 parsers
707
708 - Fully decode ApplicationCertPolicies for API V1
709
710 - Check enhanced key usage before registering OID
711
712 - Add name2oid to API
713
714 - Internal cleanup & error reporting improvements
715
716
717
718 1.4_03
719
720
721
722 - certificateTemplate ASN correction: MajorVersion is optional
723
724 - certificateTemplate returns id as a name if OID registered (API V1)
725
726 - handle some malformed requests better
727
728 - decode more M$ attributes, correct some.
729
730 - Don't croak() on missing attributes
731
732 - Convert BMPStrings from UCS2 to Perl (printable) strings
733
734 - Rework special OID handling to be scalable & cover attributes
735
736 - Don't croak in new. (API V1) Always return undef. Class method error() returns detail.
737
738 - Return reasonable strings from attributes('name') and extensionValue('name',1)
739
740 - Overload object so print can produce a useful dump.
741
742 - Handle null subject
743
744 - More enhanced key usage OIDs
745
746 - keyUsage returns array rather than comma separated string (API v1)
747
748 - Cleaned up POD
749
750 - Do a better job with error reporting
751
752 - Validate PEM's Base64 encoding.
753
754 - Ensure that only the first PEM certificate is extracted.
755
756 - Improve tests
757
758 - Enable (internal) custom formatters for extensions and attributes.
759
760 - Return basicConstraints as a hash
761
762 - Accept numeric OIDs as arguments to extensionValue, extensionPresent and attributes.
763
764
765
766 1.4_04
767
768 - Build Kwalitee issues: Minimum Perl version, Repo location, and Provides in META
769
770 - Fix test issues due to hash randomization on newer Perl versions.
771
772
773
774 1.4_05
775
776 - Sign distribution kits
777
778 - Remove execute permissions from text files
779
780 - Generate Markdown format README for github
781
782 - Use Pod::Weaver to manage authorship, copyright from dist.ini
783
784 - Add prerequisites display test
785
786 - Validate with perlcritic, pod syntax
787
788
789
790 1.5
791
792 - Uncoordinated release of 1.4_04
793
794
795
796 1.6
797
798 - Support some EC OIDs
799
800
801
802 1.7
803
804 - ECC test doesn't require Data::Dumper
805
806 - Support more EC OIDs
807
808 - Add DSA OIDs
809
810 - Add subjectPublicKeyParams(), which provides some description of the key
811
812 - Add certificationRequest and signature(1) to enable verification of CSR signatures
813
814 - Add signatureParams()
815
816 - Add signature(2) to extract ECDSA signature components.
817
818 - Fix and extend registerOID, add tests.
819
820 - Add examples/ directory with sample code
821
822 - Verify signature of CSRs in new() by default. Add checkSignature().
823
824 - Optionally allow invalid base64 character in PEM data.
825
826 - Allow new() from filename and options from hashref.
827
828
829
830 1.7_01
831
832 - Address CPANTS failures due to bugs in old versions of Crypt::PK::ECC
833
834 - Add explicit version dependency for CryptX, the parent distribution.
835
836 - For insurance, add explicit version requirements for the other modules we depend on.
837
838 - Add getAPIversion
839
840 - Make stringify use an overloadable method so it can be extended if subclassed.
841
842 - Correctly parse DER for expected length when removing padding.
843
844
845
846 1.8
847
848 - When returning PEM, ensure max line width of 64 to satisfy RFC 7468, not 76 of MIME.
849
850 - Fix test failures on some editions of 5.8.8 due to Perl bug 39185. (Tripped in test, not module.)
851
852
853
854 1.8001
855
856 - Makefile.pl: Diagnose old OpenSSL versions that fail signature verification and discard automated tests in that case.
857
858 - Print full OpenSSL configuration during automated testing.
859
860 - Require CryptX with version fix.
861
862 - Silence test warning if openssl command is missing.
863
864 - No changes to functional code.
865
866
867
868 1.8002
869
870 - Cosmetic: wrap long form OpenSSL config in test
871
872 - Make RSA, DSA and ECC support optional. Warn during install none are present or any don't work.
873
874 - Signature verification requires the corresponding module, as does decoding ECC public keys.
875
876 - subjectPublicKeyParams and checkSignature set error() for unsupported key type or hash.
877
878 - Clean up carp/croak, especially where crept into evals.
879
880 - Provide instance method for error.
881
882 - Fix stringify's interactions with API v0.
883
884 - Add binaryMode and PEMonly options to provide finer grained control of formats
885
886
887
888 1.8002_01
889
890 - Filter OpenSSL's 'WARNING: can't open config file' messages.
891
892 - Add dieOnError option to new()
893
894 - Report undefined $csr gracefully
895
896 - API v0 tests should not try to verify a signature.
897
898 - new() in void context will generate an exception.
899
900
901
902
903
904 For a more detailed list of changes, see Commitlog in the distribution.
905
906EXAMPLES
907
908 In addition to the code snippets contained in this document, the
909 examples/ directory of the distribution contains some sample
910 utilitiles.
911
912 Also, the t/ directory of the distribution contains a number of tests
913 that exercise the API. Although artificial, they are another good
914 source of examples.
915
916 Note that the type of data returned when extracting attributes and
917 extensions is dependent on the specific OID used.
918
919 Also note that some functions not listed in this document are tested.
920 The fact that they are tested does not imply that they are stable, or
921 that they will be present in any future release.
922
923 The test data was selected to exercise the API; the CSR contents are
924 not representative of realistic certificate requests.
925
926ACKNOWLEDGEMENTS
927
928 Martin Bartosch contributed preliminary EC support: OIDs and tests.
929
930 Timothe Litt made most of the changes for V1.4+
931
932 Crypt::PKCS10 is based on the generic ASN.1 module by Graham Barr and
933 on the x509decode example by Norbert Klasen. It is also based upon the
934 works of Duncan Segrest's Crypt-X509-CRL module.
935
936AUTHORS
937
938 * Gideon Knocke <gknocke@cpan.org>
939
940 * Timothe Litt <tlhackque@cpan.org>
941
942COPYRIGHT AND LICENSE
943
944 This software is copyright (c) 2014, 2016 by Gideon Knocke, Timothe
945 Litt.
946
947 This is free software; you can redistribute it and/or modify it under
948 the same terms as the Perl 5 programming language system itself.
949
950BUG REPORTS
951
952 Please report any bugs or feature requests on the bugtracker website
953 https://rt.cpan.org/Public/Dist/Display.html?Name=Crypt-PKCS10 or by
954 email to bug-crypt-pkcs10@rt.cpan.org.
955
956 When submitting a bug or request, please include a test-file or a patch
957 to an existing test-file that illustrates the bug or desired feature.
958
959
README.md
1# NAME
2
3Crypt::PKCS10 - parse PKCS #10 certificate requests
4
5# SYNOPSIS
6
7 use Crypt::PKCS10;
8
9 Crypt::PKCS10->setAPIversion( 1 );
10 my $decoded = Crypt::PKCS10->new( $csr ) or die Crypt::PKCS10->error;
11
12 print $decoded;
13
14 @names = $decoded->extensionValue('subjectAltName' );
15 @names = $decoded->subject unless( @names );
16
17 %extensions = map { $_ => $decoded->extensionValue( $_ ) } $decoded->extensions
18
19# DESCRIPTION
20
21`Crypt::PKCS10` parses PKCS #10 certificate requests (CSRs) and provides accessor methods to extract the data in usable form.
22
23Common object identifiers will be translated to their corresponding names.
24Additionally, accessor methods allow extraction of single data fields.
25The format of returned data varies by accessor.
26
27The access methods return the value corresponding to their name. If called in scalar context, they return the first value (or an empty string). If called in array context, they return all values.
28
29**true** values should be specified as 1 and **false** values as 0. Future API changes may provide different functions when other values are used.
30
31# METHODS
32
33Access methods may exist for subject name components that are not listed here. To test for these, use code of the form:
34
35 $locality = $decoded->localityName if( $decoded->can('localityName') );
36
37If a name component exists in a CSR, the method will be present. The converse is not (always) true.
38
39## class method setAPIversion( $version )
40
41Selects the API version (0 or 1) expected.
42
43Must be called before calling any other method.
44
45The API version determines how a CSR is parsed. Changing the API version after
46parsing a CSR will cause accessors to produce unpredictable results.
47
48- Version 0 - **DEPRECATED**
49
50 Some OID names have spaces and descriptions
51
52 This is the format used for `Crypt::PKCS10` version 1.3 and lower. The attributes method returns legacy data.
53
54 Some new API functions are disabled.
55
56- Version 1
57
58 OID names from RFCs - or at least compatible with OpenSSL and ASN.1 notation. The attributes method conforms to version 1.
59
60If not called, a warning will be generated and the API will default to version 0.
61
62In a future release, the warning will be changed to a fatal exception.
63
64To ease migration, both old and new names are accepted by the API.
65
66Every program should call `setAPIversion(1)`.
67
68## class method getAPIversion
69
70Returns the current API version.
71
72Returns `undef` if setAPIversion has never been called.
73
74## class method new( $csr, %options )
75
76Constructor, creates a new object containing the parsed PKCS #10 certificate request.
77
78`$csr` may be a scalar containing the request, a file name, or a file handle from which to read it.
79
80If a file name is specified, the `readFile` option must be specified.
81
82If a file handle is supplied, the caller should specify `acceptPEM => 0` if the contents are DER.
83
84The request may be PEM or binary DER encoded. Only one request is processed.
85
86If PEM, other data (such as mail headers) may precede or follow the CSR.
87
88 my $decoded = Crypt::PKCS10->new( $csr ) or die Crypt::PKCS10->error;
89
90Returns `undef` if there is an I/O error or the request can not be parsed successfully.
91
92Call `error()` to obtain more detail.
93
94### options
95
96The options are specified as `name => value`.
97
98If the first option is a HASHREF, it is expanded and any remaining options are added.
99
100- acceptPEM
101
102 If **false**, the input must be in DER format. `binmode` will be called on a file handle.
103
104 If **true**, the input is checked for a `CERTIFICATE REQUEST` header. If not found, the csr
105 is assumed to be in DER format.
106
107 Default is **true**.
108
109- PEMonly
110
111 If **true**, the input must be in PEM format. An error will be returned if the input doesn't contain a `CERTIFICATE REQUEST` header.
112 If **false**, the input is parsed according to `acceptPEM`.
113
114 Default is **false**.
115
116- binaryMode
117
118 If **true**, an input file or file handle will be set to binary mode prior to reading.
119
120 If **false**, an input file or file handle's `binmode` will not be modified.
121
122 Defaults to **false** if **acceptPEM** is **true**, otherwise **true**.
123
124- dieOnError
125
126 If **true**, any API function that sets an error string will also `die`.
127
128 If **false**, exceptions are only generated for fatal conditions.
129
130 The default is **false**. API version 1 only..
131
132- escapeStrings
133
134 If **true**, strings returned for extension and attribute values are '\\'-escaped when formatted.
135 This is compatible with OpenSSL configuration files.
136
137 The special characters are: '\\', '$', and '"'
138
139 If **false**, these strings are not '\\'-escaped. This is useful when they are being displayed
140 to a human.
141
142 The default is **true**.
143
144- ignoreNonBase64
145
146 If **true**, most invalid base64 characters in PEM data will be ignored. For example, this will
147 accept CSRs prefixed with '> ', as e-mail when the PEM is inadvertently quoted. Note that the
148 BEGIN and END lines may not be corrupted.
149
150 If **false**, invalid base64 characters in PEM data will cause the CSR to be rejected.
151
152 The default is **false**.
153
154- readFile
155
156 If **true**, `$csr` is the name of a file containing the CSR.
157
158 If **false**, `$csr` contains the CSR or is an open file handle.
159
160 The default is **false**.
161
162- verifySignature
163
164 If **true**, the CSR's signature is checked. If verification fails, `new` will fail. Requires API version 1.
165
166 If **false**, the CSR's signature is not checked.
167
168 The default is **true** for API version 1 and **false** for API version 0.
169
170 See `checkSignature` for requirements and limitations.
171
172No exceptions are generated, unless `dieOnError` is set or `new()` is called in
173void context.
174
175The defaults will accept either PEM or DER from a string or file hande, which will
176not be set to binary mode. Automatic detection of the data format may not be
177reliable on file systems that represent text and binary files differently. Set
178`acceptPEM` to **false** and `PEMonly` to match the file type on these systems.
179
180The object will stringify to a human-readable representation of the CSR. This is
181useful for debugging and perhaps for displaying a request. However, the format
182is not part of the API and may change. It should not be parsed by automated tools.
183
184Exception: The public key and extracted request are PEM blocks, which other tools
185can extract.
186
187If another object inherits from `Crypt::PKCS10`, it can extend the representation
188by overloading or calling `as_string`.
189
190## {class} method error
191
192Returns a string describing the last error encountered;
193
194If called as an instance method, last error encountered by the object.
195
196If called as a class method, last error encountered by the class.
197
198Any method can reset the string to **undef**, so the results are
199only valid immediately after a method call.
200
201## class method name2oid( $oid )
202
203Returns the OID corresponding to a name returned by an access method.
204
205Not in API v0;
206
207## csrRequest( $format )
208
209Returns the binary (ASN.1) request (after conversion from PEM and removal of any data beyond the length of the ASN.1 structure.
210
211If $format is **true**, the request is returned as a PEM CSR. Otherwise as a binary string.
212
213## certificationRequest
214
215Returns the binary (ASN.1) section of the request that is signed by the requestor.
216
217The caller can verify the signature using **signatureAlgorithm**, **certificationRequest** and **signature(1)**.
218
219## Access methods for the subject's distinguished name
220
221Note that **subjectAltName** is prefered, and that modern certificate users will ignore the subject if **subjectAltName** is present.
222
223### subject( $format )
224
225Returns the entire subject of the CSR.
226
227In scalar context, returns the subject as a string in the form `/componentName=value,value`.
228 If format is **true**, long component names are used. By default, abbreviations are used when they exist.
229
230 e.g. /countryName=AU/organizationalUnitName=Big org/organizationalUnitName=Smaller org
231 or /C=AU/OU=Big org/OU=Smaller org
232
233In array context, returns an array of `(componentName, [values])` pairs. Abbreviations are not used.
234
235Note that the order of components in a name is significant.
236
237### subjectRaw
238
239Returns the subjects RDNs as sequence of hashes without OID any mapping applied.
240
241The result is an array ref where each item is a hash:
242
243 [
244 {
245 'format' => 'ia5String',
246 'value' => 'Org',
247 'type' => '0.9.2342.19200300.100.1.25'
248 },
249 {
250 'format' => 'utf8String',
251 'value' => 'ACME',
252 'type' => '2.5.4.10'
253 },
254 {
255 'format' => 'utf8String',
256 'type' => '2.5.4.3',
257 'value' => 'Foobar'
258 }
259 ]
260
261If a component contains a SET, the component will become an array on the
262second level, too:
263
264 [
265 {
266 'format' => 'ia5String',
267 'value' => 'Org',
268 'type' => '0.9.2342.19200300.100.1.25'
269 },
270 {
271 'format' => 'utf8String',
272 'value' => 'ACME',
273 'type' => '2.5.4.10'
274 },
275 [
276 {
277 'format' => 'utf8String',
278 'type' => '2.5.4.3',
279 'value' => 'Foobar'
280 },
281 {
282 'format' => 'utf8String',
283 'type' => '0.9.2342.19200300.100.1.1',
284 'value' => 'foobar'
285 }
286 ]
287 ];
288
289### commonName
290
291Returns the common name(s) from the subject.
292
293 my $cn = $decoded->commonName();
294
295### organizationalUnitName
296
297Returns the organizational unit name(s) from the subject
298
299### organizationName
300
301Returns the organization name(s) from the subject.
302
303### emailAddress
304
305Returns the email address from the subject.
306
307### stateOrProvinceName
308
309Returns the state or province name(s) from the subject.
310
311### countryName
312
313Returns the country name(s) from the subject.
314
315## subjectAltName( $type )
316
317Convenience method.
318
319When $type is specified: returns the subject alternate name values of the specified type in list context, or the first value
320of the specified type in scalar context.
321
322Returns undefined/empty list if no values of the specified type are present, or if the **subjectAltName**
323extension is not present.
324
325Types can be any of:
326
327 otherName
328 * rfc822Name
329 * dNSName
330 x400Address
331 directoryName
332 ediPartyName
333 * uniformResourceIdentifier
334 * iPAddress
335 * registeredID
336
337The types marked with '\*' are the most common.
338
339If `$type` is not specified:
340 In list context returns the types present in the subjectAlternate name.
341 In scalar context, returns the SAN as a string.
342
343## version
344
345Returns the structure version as a string, e.g. "v1" "v2", or "v3"
346
347## pkAlgorithm
348
349Returns the public key algorithm according to its object identifier.
350
351## subjectPublicKey( $format )
352
353If `$format` is **true**, the public key will be returned in PEM format.
354
355Otherwise, the public key will be returned in its hexadecimal representation
356
357## subjectPublicKeyParams
358
359Returns a hash describing the public key. The contents vary depending on
360the public key type.
361
362### Standard items:
363
364`keytype` - ECC, RSA, DSA or `undef`
365
366`keytype` will be `undef` if the key type is not supported. In
367this case, `error()` returns a diagnostic message.
368
369`keylen` - Approximate length of the key in bits.
370
371Other items include:
372
373For RSA, `modulus` and `publicExponent`.
374
375For DSA, `G, P and Q`.
376
377For ECC, `curve`, `pub_x` and `pub_y`. `curve` is an OID name.
378
379### Additional detail
380
381`subjectPublicKeyParams(1)` returns the standard items, and may
382also return `detail`, which is a hashref.
383
384For ECC, the `detail` hash includes the curve definition constants.
385
386## signatureAlgorithm
387
388Returns the signature algorithm according to its object identifier.
389
390## signatureParams
391
392Returns the parameters associated with the **signatureAlgorithm** as binary.
393Returns **undef** if none, or if **NULL**.
394
395Note: In the future, some **signatureAlgorithm**s may return a hashref of decoded fields.
396
397Callers are advised to check for a ref before decoding...
398
399## signature( $format )
400
401The CSR's signature is returned.
402
403If `$format` is **1**, in binary.
404
405If `$format` is **2**, decoded as an ECDSA signature - returns hashref to `r` and `s`.
406
407Otherwise, in its hexadecimal representation.
408
409## attributes( $name )
410
411A request may contain a set of attributes. The attributes are OIDs with values.
412The most common is a list of requested extensions, but other OIDs can also
413occur. Of those, **challengePassword** is typical.
414
415For API version 0, this method returns a hash consisting of all
416attributes in an internal format. This usage is **deprecated**.
417
418For API version 1:
419
420If $name is not specified, a list of attribute names is returned. The list does not
421include the requestedExtensions attribute. For that, use extensions();
422
423If no attributes are present, the empty list (`undef` in scalar context) is returned.
424
425If $name is specified, the value of the extension is returned. $name can be specified
426as a numeric OID.
427
428In scalar context, a single string is returned, which may include lists and labels.
429
430 cspName="Microsoft Strong Cryptographic Provider",keySpec=2,signature=("",0)
431
432Special characters are escaped as described in options.
433
434In array context, the value(s) are returned as a list of items, which may be references.
435
436 print( " $_: ", scalar $decoded->attributes($_), "\n" )
437 foreach ($decoded->attributes);
438
439See the _Table of known OID names_ below for a list of names.
440
441## extensions
442
443Returns an array containing the names of all extensions present in the CSR. If no extensions are present,
444the empty list is returned.
445
446The names vary depending on the API version; however, the returned names are acceptable to `extensionValue`, `extensionPresent`, and `name2oid`.
447
448The values of extensions vary, however the following code fragment will dump most extensions and their value(s).
449
450 print( "$_: ", $decoded->extensionValue($_,1), "\n" ) foreach ($decoded->extensions);
451
452The sample code fragment is not guaranteed to handle all cases.
453Production code needs to select the extensions that it understands and should respect
454the **critical** boolean. **critical** can be obtained with extensionPresent.
455
456## extensionValue( $name, $format )
457
458Returns the value of an extension by name, e.g. `extensionValue( 'keyUsage' )`.
459The name SHOULD be an API v1 name, but API v0 names are accepted for compatibility.
460The name can also be specified as a numeric OID.
461
462If `$format` is 1, the value is a formatted string, which may include lists and labels.
463Special characters are escaped as described in options;
464
465If `$format` is 0 or not defined, a string, or an array reference may be returned.
466The array many contain any Perl variable type.
467
468To interpret the value(s), you need to know the structure of the OID.
469
470See the _Table of known OID names_ below for a list of names.
471
472## extensionPresent( $name )
473
474Returns **true** if a named extension is present:
475 If the extension is **critical**, returns 2.
476 Otherwise, returns 1, indicating **not critical**, but present.
477
478If the extension is not present, returns `undef`.
479
480The name can also be specified as a numeric OID.
481
482See the _Table of known OID names_ below for a list of names.
483
484## registerOID( )
485
486Class method.
487
488Register a custom OID, or a public OID that has not been added to Crypt::PKCS10 yet.
489
490The OID may be an extension identifier or an RDN component.
491
492The oid is specified as a string in numeric form, e.g. `'1.2.3.4'`
493
494### registerOID( $oid )
495
496Returns **true** if the specified OID is registered, **false** otherwise.
497
498### registerOID( $oid, $longname, $shortname )
499
500Registers the specified OID with the associated long name. This
501enables the OID to be translated to a name in output.
502
503The long name should be Hungarian case (**commonName**), but this is not currently
504enforced.
505
506Optionally, specify the short name used for extracting the subject.
507The short name should be upper-case (and will be upcased).
508
509E.g. built-in are `$oid => '2.4.5.3', $longname => 'commonName', $shortname => 'CN'`
510
511To register a shortname for an existing OID without one, specify `$longname` as `undef`.
512
513E.g. To register /E for emailAddress, use:
514 `Crypt::PKCS10->registerOID( '1.2.840.113549.1.9.1', undef, 'e' )`
515
516Generates an exception if any argument is not valid, or is in use.
517
518Returns **true** otherwise.
519
520## checkSignature
521
522Verifies the signature of a CSR. (Useful if new() specified `verifySignature => 0`.)
523
524Returns **true** if the signature is OK.
525
526Returns **false** if the signature is incorrect. `error()` returns
527the reason.
528
529Returns **undef** if it was not possible to complete the verification process (e.g. a required
530Perl module could not be loaded or an unsupported key/signature type is present.)
531
532_Note_: Requires Crypt::PK::\* for the used algorithm to be installed. For RSA
533v1.5 padding is assumed, PSS is not supported (validation fails).
534
535## certificateTemplate
536
537`CertificateTemplate` returns the **certificateTemplate** attribute.
538
539Equivalent to `extensionValue( 'certificateTemplate' )`, which is prefered.
540
541## Table of known OID names
542
543The following OID names are known. They are used in returned strings and
544structures, and as names by methods such as **extensionValue**.
545
546Unknown OIDs are returned in numeric form, or can be registered with
547**registerOID**.
548
549 OID Name (API v1) Old Name (API v0)
550 -------------------------- -------------------------- ---------------------------
551 0.9.2342.19200300.100.1.1 userID
552 0.9.2342.19200300.100.1.25 domainComponent
553 1.2.840.10040.4.1 dsa (DSA)
554 1.2.840.10040.4.3 dsaWithSha1 (DSA with SHA1)
555 1.2.840.10045.2.1 ecPublicKey
556 1.2.840.10045.3.1.1 secp192r1
557 1.2.840.10045.3.1.7 secp256r1
558 1.2.840.10045.4.3.1 ecdsa-with-SHA224
559 1.2.840.10045.4.3.2 ecdsa-with-SHA256
560 1.2.840.10045.4.3.3 ecdsa-with-SHA384
561 1.2.840.10045.4.3.4 ecdsa-with-SHA512
562 1.2.840.113549.1.1.1 rsaEncryption (RSA encryption)
563 1.2.840.113549.1.1.2 md2WithRSAEncryption (MD2 with RSA encryption)
564 1.2.840.113549.1.1.3 md4WithRSAEncryption
565 1.2.840.113549.1.1.4 md5WithRSAEncryption (MD5 with RSA encryption)
566 1.2.840.113549.1.1.5 sha1WithRSAEncryption (SHA1 with RSA encryption)
567 1.2.840.113549.1.1.6 rsaOAEPEncryptionSET
568 1.2.840.113549.1.1.7 RSAES-OAEP
569 1.2.840.113549.1.1.11 sha256WithRSAEncryption (SHA-256 with RSA encryption)
570 1.2.840.113549.1.1.12 sha384WithRSAEncryption
571 1.2.840.113549.1.1.13 sha512WithRSAEncryption (SHA-512 with RSA encryption)
572 1.2.840.113549.1.1.14 sha224WithRSAEncryption
573 1.2.840.113549.1.9.1 emailAddress
574 1.2.840.113549.1.9.2 unstructuredName
575 1.2.840.113549.1.9.7 challengePassword
576 1.2.840.113549.1.9.14 extensionRequest
577 1.2.840.113549.1.9.15 smimeCapabilities (SMIMECapabilities)
578 1.3.6.1.4.1.311.2.1.14 CERT_EXTENSIONS
579 1.3.6.1.4.1.311.2.1.21 msCodeInd
580 1.3.6.1.4.1.311.2.1.22 msCodeCom
581 1.3.6.1.4.1.311.10.3.1 msCTLSign
582 1.3.6.1.4.1.311.10.3.2 msTimeStamping
583 1.3.6.1.4.1.311.10.3.3 msSGC
584 1.3.6.1.4.1.311.10.3.4 msEFS
585 1.3.6.1.4.1.311.10.3.4.1 msEFSRecovery
586 1.3.6.1.4.1.311.10.3.5 msWHQLCrypto
587 1.3.6.1.4.1.311.10.3.6 msNT5Crypto
588 1.3.6.1.4.1.311.10.3.7 msOEMWHQLCrypto
589 1.3.6.1.4.1.311.10.3.8 msEmbeddedNTCrypto
590 1.3.6.1.4.1.311.10.3.9 msRootListSigner
591 1.3.6.1.4.1.311.10.3.10 msQualifiedSubordination
592 1.3.6.1.4.1.311.10.3.11 msKeyRecovery
593 1.3.6.1.4.1.311.10.3.12 msDocumentSigning
594 1.3.6.1.4.1.311.10.3.13 msLifetimeSigning
595 1.3.6.1.4.1.311.10.3.14 msMobileDeviceSoftware
596 1.3.6.1.4.1.311.13.1 RENEWAL_CERTIFICATE
597 1.3.6.1.4.1.311.13.2.1 ENROLLMENT_NAME_VALUE_PAIR
598 1.3.6.1.4.1.311.13.2.2 ENROLLMENT_CSP_PROVIDER
599 1.3.6.1.4.1.311.13.2.3 OS_Version
600 1.3.6.1.4.1.311.20.2 certificateTemplateName
601 1.3.6.1.4.1.311.20.2.2 msSmartCardLogon
602 1.3.6.1.4.1.311.21.7 certificateTemplate
603 1.3.6.1.4.1.311.21.10 ApplicationCertPolicies
604 1.3.6.1.4.1.311.21.20 ClientInformation
605 1.3.6.1.5.2.3.5 keyPurposeKdc (KDC Authentication)
606 1.3.6.1.5.5.7.2.1 CPS
607 1.3.6.1.5.5.7.2.2 userNotice
608 1.3.6.1.5.5.7.3.1 serverAuth
609 1.3.6.1.5.5.7.3.2 clientAuth
610 1.3.6.1.5.5.7.3.3 codeSigning
611 1.3.6.1.5.5.7.3.4 emailProtection
612 1.3.6.1.5.5.7.3.8 timeStamping
613 1.3.6.1.5.5.7.3.9 OCSPSigning
614 1.3.6.1.5.5.7.3.21 sshClient
615 1.3.6.1.5.5.7.3.22 sshServer
616 1.3.6.1.5.5.7.9.5 countryOfResidence
617 1.3.14.3.2.29 sha1WithRSAEncryption (SHA1 with RSA signature)
618 1.3.36.3.3.2.8.1.1.1 brainpoolP160r1
619 1.3.36.3.3.2.8.1.1.2 brainpoolP160t1
620 1.3.36.3.3.2.8.1.1.3 brainpoolP192r1
621 1.3.36.3.3.2.8.1.1.4 brainpoolP192t1
622 1.3.36.3.3.2.8.1.1.5 brainpoolP224r1
623 1.3.36.3.3.2.8.1.1.6 brainpoolP224t1
624 1.3.36.3.3.2.8.1.1.7 brainpoolP256r1
625 1.3.36.3.3.2.8.1.1.8 brainpoolP256t1
626 1.3.36.3.3.2.8.1.1.9 brainpoolP320r1
627 1.3.36.3.3.2.8.1.1.10 brainpoolP320t1
628 1.3.36.3.3.2.8.1.1.11 brainpoolP384r1
629 1.3.36.3.3.2.8.1.1.12 brainpoolP384t1
630 1.3.36.3.3.2.8.1.1.13 brainpoolP512r1
631 1.3.36.3.3.2.8.1.1.14 brainpoolP512t1
632 1.3.132.0.1 sect163k1
633 1.3.132.0.15 sect163r2
634 1.3.132.0.16 sect283k1
635 1.3.132.0.17 sect283r1
636 1.3.132.0.26 sect233k1
637 1.3.132.0.27 sect233r1
638 1.3.132.0.33 secp224r1
639 1.3.132.0.34 secp384r1
640 1.3.132.0.35 secp521r1
641 1.3.132.0.36 sect409k1
642 1.3.132.0.37 sect409r1
643 1.3.132.0.38 sect571k1
644 1.3.132.0.39 sect571r1
645 2.5.4.3 commonName
646 2.5.4.4 surname (Surname)
647 2.5.4.5 serialNumber
648 2.5.4.6 countryName
649 2.5.4.7 localityName
650 2.5.4.8 stateOrProvinceName
651 2.5.4.9 streetAddress
652 2.5.4.10 organizationName
653 2.5.4.11 organizationalUnitName
654 2.5.4.12 title (Title)
655 2.5.4.13 description (Description)
656 2.5.4.14 searchGuide
657 2.5.4.15 businessCategory
658 2.5.4.16 postalAddress
659 2.5.4.17 postalCode
660 2.5.4.18 postOfficeBox
661 2.5.4.19 physicalDeliveryOfficeName
662 2.5.4.20 telephoneNumber
663 2.5.4.23 facsimileTelephoneNumber
664 2.5.4.41 name (Name)
665 2.5.4.42 givenName
666 2.5.4.43 initials
667 2.5.4.44 generationQualifier
668 2.5.4.45 uniqueIdentifier
669 2.5.4.46 dnQualifier
670 2.5.4.51 houseIdentifier
671 2.5.4.65 pseudonym
672 2.5.29.14 subjectKeyIdentifier (SubjectKeyIdentifier)
673 2.5.29.15 keyUsage (KeyUsage)
674 2.5.29.17 subjectAltName
675 2.5.29.19 basicConstraints (Basic Constraints)
676 2.5.29.32 certificatePolicies
677 2.5.29.32.0 anyPolicy
678 2.5.29.37 extKeyUsage (EnhancedKeyUsage)
679 2.16.840.1.101.3.4.2.1 sha256 (SHA-256)
680 2.16.840.1.101.3.4.2.2 sha384 (SHA-384)
681 2.16.840.1.101.3.4.2.3 sha512 (SHA-512)
682 2.16.840.1.101.3.4.2.4 sha224 (SHA-224)
683 2.16.840.1.101.3.4.3.1 dsaWithSha224
684 2.16.840.1.101.3.4.3.2 dsaWithSha256
685 2.16.840.1.101.3.4.3.3 dsaWithSha384
686 2.16.840.1.101.3.4.3.4 dsaWithSha512
687 2.16.840.1.113730.1.1 netscapeCertType
688 2.16.840.1.113730.1.2 netscapeBaseUrl
689 2.16.840.1.113730.1.4 netscapeCaRevocationUrl
690 2.16.840.1.113730.1.7 netscapeCertRenewalUrl
691 2.16.840.1.113730.1.8 netscapeCaPolicyUrl
692 2.16.840.1.113730.1.12 netscapeSSLServerName
693 2.16.840.1.113730.1.13 netscapeComment
694 2.16.840.1.113730.4.1 nsSGC
695
696# EXAMPLES
697
698In addition to the code snippets contained in this document, the `examples/` directory of the distribution
699contains some sample utilitiles.
700
701Also, the `t/` directory of the distribution contains a number of tests that exercise the
702API. Although artificial, they are another good source of examples.
703
704Note that the type of data returned when extracting attributes and extensions is dependent
705on the specific OID used.
706
707Also note that some functions not listed in this document are tested. The fact that they are
708tested does not imply that they are stable, or that they will be present in any future release.
709
710The test data was selected to exercise the API; the CSR contents are not representative of
711realistic certificate requests.
712
713# ACKNOWLEDGEMENTS
714
715Martin Bartosch contributed preliminary EC support: OIDs and tests.
716
717Timothe Litt made most of the changes for V1.4+
718
719`Crypt::PKCS10` is based on the generic ASN.1 module by Graham Barr and on the
720 x509decode example by Norbert Klasen. It is also based upon the
721works of Duncan Segrest's `Crypt-X509-CRL` module.
722
723# AUTHORS
724
725Gideon Knocke <gknocke@cpan.org>
726Timothe Litt <tlhackque@cpan.org>
727
728# LICENSE
729
730GPL v1 -- See LICENSE file for details
731