NAME
Crypt::PKCS10 - parse PKCS #10 certificate requests
VERSION
version 1.401
SYNOPSIS
use Crypt::PKCS10;
Crypt::PKCS10->setAPIversion( 1 );
my $decoded = Crypt::PKCS10->new( $csr );
my @names;
@names = $decoded->extensionValue('subjectAltName' );
@names = $decoded->subject unless( @names );
my %extensions = map { $_ => $decoded->extensionValue( $_ ) } $decoded->extensionsDESCRIPTION
Crypt::PKCS10 parses PKCS #10 certificate requests (CSRs) and provides accessor methods to extract the data in usable form.
Common object identifiers will be translated to their corresponding names. Additionally, accessor methods allow extraction of single data fields. Bit Strings like signatures will be returned in their hexadecimal representation.
The 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.
NAME
Crypt::PKCS10 - parse PKCS #10 certificate requests
METHODS
Access methods may exist for subject name components that are not listed here. To test for these, use code of the form:
$locality = $decoded->localityName if( $decoded->can('localityName') );If a name component exists in a CSR, the method will be present. The converse is not (always) true.
setAPIversion( $version )
Selects the API version expected.
Must be called before calling any other method.
- o
-
Version 0 = Some OID names have spaces and descriptions - DEPRECATED
This is the format used for Crypt::PKCS10 version 1.3 and lower. The attributes method returns legacy data.
- o
-
Version 1 = OID names from RFCs - or at least compatible with OpenSSL and ASN.1 notation. The attributes method conforms to version 1.
If not called, a warning will be generated and the API will default to version 0.
In a future release, the warning will be changed to a fatal exception.
To ease migration, both old and new names are accepted by the API.
Every program should call setAPIversion(1).
new
Constructor, creates a new object containing the parsed PKCS #10 request It takes the request itself as an argument. PEM and DER encoding is supported.
If PEM, other data (such as mail headers) may precede or follow the CSR.
my $decoded = Crypt::PKCS10->new( $csr );csrRequest( $format )
Returns the binary (ASN.1) request (after conversion from PEM and removal of any data beyond the length of the ASN.1 structure.
If $format is true, the request is returned as a PEM CSR. Otherwise as a binary string.
Access methods for the subject's distinguished name
Note that subjectAltName is prefered, and modern certificate users will ignore the subject if subjectAltName is present.
subject(format)
Returns the entire subject of the CSR.
In scalar context, returns the subject as a string in the form /componentName=value,value. If format is true, long component names are used. By default, abbreviations are used when known.
e.g. /countryName=AU/organizationalUnitName=Big org/organizationalUnitName=Smaller org
or /C=AU/OU=Big org/OU=Smaller orgIn array context, returns an array of (componentName, [values]) pairs. Abbreviations are not used.
Note that the order of components in a name is significant.
commonName
Returns the common name(s) from the subject.
my $cn = $decoded->commonName();organizationalUnitName
Returns the organizational unit name(s) from the subject
organizationName
Returns the organization name(s) from the subject.
emailAddress
Returns the email address from the subject.
stateOrProvinceName
Returns the state or province name(s) from the subject.
countryName
Returns the country name(s) from the subject.
subjectAltName($type)
Convenience method.
When $type is specified: returns the subject alternate name values of the specified type in list context, or the first value of the specified type in scalar context.
Returns undefined/empty list if no values of the specified type are present, or if the subjectAltName extension is not present.
Types can be any of:
otherName
* rfc822Name
* dNSName
x400Address
directoryName
ediPartyName
* uniformResourceIdentifier
* iPAddress
* registeredIDThe types marked with '*' are the most common.
If $type is not specified: In list context returns the types present in the subjectAlternate name. In scalar context, returns the SAN as a string.
version
Returns the structure version as a string, e.g. "v1" "v2", or "v3"
pkAlgorithm
Returns the public key algorithm according to its object identifier.
subjectPublicKey( $format )
If $format is true, the public key will be returned in PEM format.
Otherwise, the public key will be returned in its hexadecimal representation
signatureAlgorithm
Returns the signature algorithm according to its object identifier.
signature
The signature will be returned in its hexadecimal representation
attributes( $name )
A request may contain a set of attributes. The attributes are OIDs with values. The most common is a list of requested extensions, but other OIDs can also occur. Of those, challengePassword is typical.
For API version 0, this method returns a hash consisting of all attributes in an internal format. This usage is deprecated.
For API version 1:
If $name is not specified, a list of attribute names is returned. The list does not include the requestedExtensions attribute. For that, use extensions();
If no attributes are present, the empty list (undef in scalar context) is returned.
If $name is specified, the value of the extension is returned. (Only string values are currently supported.) In scalar context, a single string is returned with multiple values separated by ',' or '+'. In array context, the value(s) are returned.
print "$_: ", scalar $decoded->attributes($_), "\n"
foreach ($decoded->attributes);extensions
Returns an array containing the names of all extensions present in the CSR. If no extensions are present, the empty list is returned.
The names vary depending on the API version; however, the returned names are acceptable to extensionValue and extensionPresent.
The values of extensions vary, however the following code fragment will dump most extensions and their value(s).
foreach my $ext ($decoded->extensions) {
my $val = $decoded->extensionValue($ext);
$val = join( ',', map { ref $_ eq 'HASH'?
join( ':', (keys %$_)[0], (values %$_)[0] ): $_} @$val )
if( ref $val eq 'ARRAY' );
print( "$ext: ", $val, "\n" );
}The sample code fragment is not guaranteed to handle all cases. Realistic code needs to select the extensions that it understands.
extensionValue
Returns the value of an extension by name, e.g. extensionValue( 'keyUsage' ). The name SHOULD be an API v1 name, but API v0 names are accepted for compatibility.
To interpret the value, you need to know the structure of the OID.
Depending on the extension, the value may be a string, an array of strings, or an array of hashes.
extensionPresent
Returns true if a named extension is present: If the extension is 'critical', returns 2. Otherwise, returns 1, indicating 'not critical', but present.
If the extension is not present, returns undef.
The following OID names are known (not all are extensions):
OID Name (API v1) Old Name (API v0)
-------------------------- -------------------------- ---------------------------
0.9.2342.19200300.100.1.1 userID
0.9.2342.19200300.100.1.25 domainComponent
1.2.840.10040.4.1 DSA
1.2.840.10040.4.3 dsaWithSha1 (DSA with SHA1)
1.2.840.113549.1.1.1 rsaEncryption (RSA encryption)
1.2.840.113549.1.1.2 md2WithRSAEncryption (MD2 with RSA encryption)
1.2.840.113549.1.1.3 md4WithRSAEncryption
1.2.840.113549.1.1.4 md5WithRSAEncryption (MD5 with RSA encryption)
1.2.840.113549.1.1.5 sha1WithRSAEncryption (SHA1 with RSA encryption)
1.2.840.113549.1.1.6 rsaOAEPEncryptionSET
1.2.840.113549.1.1.7 RSAES-OAEP
1.2.840.113549.1.1.11 sha256WithRSAEncryption (SHA-256 with RSA encryption)
1.2.840.113549.1.1.12 sha384WithRSAEncryption
1.2.840.113549.1.1.13 sha512WithRSAEncryption (SHA-512 with RSA encryption)
1.2.840.113549.1.1.14 sha224WithRSAEncryption
1.2.840.113549.1.9.1 emailAddress
1.2.840.113549.1.9.2 unstructuredName
1.2.840.113549.1.9.7 challengePassword
1.2.840.113549.1.9.14 extensionRequest
1.2.840.113549.1.9.15 smimeCapabilities (SMIMECapabilities)
1.3.6.1.4.1.311.2.1.14 CERT_EXTENSIONS
1.3.6.1.4.1.311.13.1 RENEWAL_CERTIFICATE
1.3.6.1.4.1.311.13.2.1 ENROLLMENT_NAME_VALUE_PAIR
1.3.6.1.4.1.311.13.2.2 ENROLLMENT_CSP_PROVIDER
1.3.6.1.4.1.311.13.2.3 OS_Version
1.3.6.1.4.1.311.20.2 certificateTemplateName
1.3.6.1.4.1.311.21.7 certificateTemplate
1.3.6.1.4.1.311.21.10 ApplicationCertPolicies
1.3.6.1.4.1.311.21.20 ClientInformation
1.3.6.1.5.2.3.5 keyPurposeKdc (KDC Authentication)
1.3.6.1.5.5.7.3.1 serverAuth
1.3.6.1.5.5.7.3.2 clientAuth
1.3.6.1.5.5.7.3.3 codeSigning
1.3.6.1.5.5.7.3.4 emailProtection
1.3.6.1.5.5.7.3.8 timeStamping
1.3.6.1.5.5.7.3.9 OCSPSigning
1.3.6.1.5.5.7.9.5 countryOfResidence
1.3.14.3.2.29 sha1WithRSAEncryption (SHA1 with RSA signature)
2.5.4.3 commonName
2.5.4.4 surname (Surname)
2.5.4.5 serialNumber
2.5.4.6 countryName
2.5.4.7 localityName
2.5.4.8 stateOrProvinceName
2.5.4.9 streetAddress
2.5.4.10 organizationName
2.5.4.11 organizationalUnitName
2.5.4.12 title (Title)
2.5.4.13 description (Description)
2.5.4.14 searchGuide
2.5.4.15 businessCategory
2.5.4.16 postalAddress
2.5.4.17 postalCode
2.5.4.18 postOfficeBox
2.5.4.19 physicalDeliveryOfficeName
2.5.4.20 telephoneNumber
2.5.4.23 facsimileTelephoneNumber
2.5.4.41 name (Name)
2.5.4.42 givenName
2.5.4.43 initials
2.5.4.44 generationQualifier
2.5.4.45 uniqueIdentifier
2.5.4.46 dnQualifier
2.5.4.51 houseIdentifier
2.5.4.65 pseudonym
2.5.29.14 subjectKeyIdentifier (SubjectKeyIdentifier)
2.5.29.15 keyUsage (KeyUsage)
2.5.29.17 subjectAltName
2.5.29.19 basicConstraints (Basic Constraints)
2.5.29.37 extKeyUsage (EnhancedKeyUsage)
2.16.840.1.101.3.4.2.1 sha256 (SHA-256)
2.16.840.1.113730.1.1 netscapeCertType
2.16.840.1.113730.1.2 netscapeBaseUrl
2.16.840.1.113730.1.4 netscapeCaRevocationUrl
2.16.840.1.113730.1.7 netscapeCertRenewalUrl
2.16.840.1.113730.1.8 netscapeCaPolicyUrl
2.16.840.1.113730.1.12 netscapeSSLServerName
2.16.840.1.113730.1.13 netscapeCommentregisterOID
Class method.
Register a custom OID, or a public OID that has not been added to Crypt::PKCS10 yet.
The OID may be an extension identifier or an RDN component.
The oid is specified as a string in numeric form, e.g. '1.2.3.4'
registerOID( $oid )
Returns true if the specified OID is registered, false otherwise.
registerOID( $oid, $longname, $shortname )
Registers the specified OID with the associated long name. The long name should be Hungarian case (commonName), but this is not currently enforced.
Optionally, specify the short name used for extracting the subject. The short name should be upper-case (and will be upcased).
E.g. built-in are $oid => '2.4.5.3', $longname => 'commonName', $shortname => 'CN'
Generates an exception if any argument is not valid, or is in use.
Returns true otherwise.
certificateTemplate
CertificateTemplate is an attribute widely used by Windows certification authorities.
AUTHORS
Gideon Knocke
Timothe Litt made most of the changes for V1.4
Crypt::PKCS10 is based on the generic ASN.1 module by Graham Barr and on the x509decode example by Norbert Klasen. It is also based upon the works of Duncan Segrest's Crypt-X509-CRL module.
COPYRIGHT
This software is copyright (c) 2014 by Gideon Knocke.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Terms of the Perl programming language system itself
a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
b) the "Artistic License"
AUTHORS
Gideon Knocke <gknocke@cpan.org>
Timothe Litt <tlhackque@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Gideon Knocke.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.