Crypt-PKCS10
view release on metacpan or search on metacpan
NAME
Crypt::PKCS10 - parse PKCS #10 certificate requests
VERSION
version 1.800201
SYNOPSIS
use Crypt::PKCS10;
Crypt::PKCS10->setAPIversion( 1 );
my $decoded = Crypt::PKCS10->new( $csr ) or die Crypt::PKCS10->error;
print $decoded;
@names = $decoded->extensionValue('subjectAltName' );
@names = $decoded->subject unless( @names );
%extensions = map { $_ => $decoded->extensionValue( $_ ) } $decoded->extensions
DESCRIPTION
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. The format of returned data varies by accessor.
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.
true values should be specified as 1 and false values as 0. Future API
changes may provide different functions when other values are used.
This file is automatically generated by pod2readme from PKCS10.pm and Changes.
NAME
Crypt::PKCS10 - parse PKCS #10 certificate requests
RELEASE NOTES
Version 1.4 made several API changes. Most users should have a painless
migration.
ALL users must call Crypt::PKCS10->setAPIversion. If not, a warning
will be generated by the first class method called. This warning will
be made a fatal exception in a future release.
Other than that requirement, the legacy mode is compatible with
previous versions.
new will no longer generate exceptions. undef is returned on all
errors. Use the error class method to retrieve the reason.
new will accept an open file handle in addition to a request.
Users are encouraged to migrate to the version 1 API. It is much easier
to use, and does not require the application to navigate internal data
structures.
Version 1.7 provides support for DSA and ECC public keys. By default,
it verifies the signature of CSRs. It also allows the caller to verify
the signature of a CSR. subjectPublicKeyParams and signatureParams
provide additional information. The readFile option to new() will
open() a file containing a CSR by name. The ignoreNonBase64 option
allows PEM to contain extraneous characters. Changes describes
additional improvements. Details follow.
INSTALLATION
Crypt::PKCS10 supports DSA, RSA and ECC public keys in CSRs.
It depends on Crypt::OpenSSL::DSA, Crypt::OpenSSL::RSA and
Crypt::PK::ECC for some operations. All are recommended. Some methods
will return errors if Crypt::PKCS10 is presented with a CSR containing
an unsupported public key type.
To install this module type the following:
perl Makefile.PL
make
make test
make install
REQUIRES
Convert::ASN1
Crypt::OpenSSL::DSA
Crypt::OpenSSL::RSA
Crypt::PK::ECC
Digest::SHA
For ECC: Crypt::PK::ECC
Very old CSRs may require DIGEST::MD{5,4,2}
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.
class method setAPIversion( $version )
Selects the API version (0 or 1) expected.
Must be called before calling any other method.
The API version determines how a CSR is parsed. Changing the API
version after parsing a CSR will cause accessors to produce
unpredictable results.
Version 0 - DEPRECATED
Some OID names have spaces and descriptions
This is the format used for Crypt::PKCS10 version 1.3 and lower. The
attributes method returns legacy data.
Some new API functions are disabled.
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).
class method getAPIversion
Returns the current API version.
Returns undef if setAPIversion has never been called.
class method new( $csr, %options )
Constructor, creates a new object containing the parsed PKCS #10
certificate request.
$csr may be a scalar containing the request, a file name, or a file
handle from which to read it.
If a file name is specified, the readFile option must be specified.
If a file handle is supplied, the caller should specify acceptPEM => 0
if the contents are DER.
The request may be PEM or binary DER encoded. Only one request is
processed.
If PEM, other data (such as mail headers) may precede or follow the
CSR.
my $decoded = Crypt::PKCS10->new( $csr ) or die Crypt::PKCS10->error;
Returns undef if there is an I/O error or the request can not be parsed
successfully.
Call error() to obtain more detail.
options
The options are specified as name => value.
If the first option is a HASHREF, it is expanded and any remaining
options are added.
acceptPEM
If false, the input must be in DER format. binmode will be called on
a file handle.
If true, the input is checked for a CERTIFICATE REQUEST header. If
not found, the csr is assumed to be in DER format.
Default is true.
PEMonly
If true, the input must be in PEM format. An error will be returned
if the input doesn't contain a CERTIFICATE REQUEST header. If false,
the input is parsed according to acceptPEM.
Default is false.
binaryMode
If true, an input file or file handle will be set to binary mode
prior to reading.
If false, an input file or file handle's binmode will not be
modified.
Defaults to false if acceptPEM is true, otherwise true.
dieOnError
If true, any API function that sets an error string will also die.
If false, exceptions are only generated for fatal conditions.
The default is false. API version 1 only..
escapeStrings
If true, strings returned for extension and attribute values are
'\'-escaped when formatted. This is compatible with OpenSSL
configuration files.
The special characters are: '\', '$', and '"'
If false, these strings are not '\'-escaped. This is useful when they
are being displayed to a human.
representation by overloading or calling as_string.
{class} method error
Returns a string describing the last error encountered;
If called as an instance method, last error encountered by the object.
If called as a class method, last error encountered by the class.
Any method can reset the string to undef, so the results are only valid
immediately after a method call.
class method name2oid( $oid )
Returns the OID corresponding to a name returned by an access method.
Not in API v0;
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.
certificationRequest
Returns the binary (ASN.1) section of the request that is signed by the
requestor.
The caller can verify the signature using signatureAlgorithm,
certificationRequest and signature(1).
Access methods for the subject's distinguished name
Note that subjectAltName is prefered, and that 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 they exist.
e.g. /countryName=AU/organizationalUnitName=Big org/organizationalUnitName=Smaller org
or /C=AU/OU=Big org/OU=Smaller org
In 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
* registeredID
The 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
subjectPublicKeyParams
Returns a hash describing the public key. The contents vary depending
on the public key type.
Standard items:
keytype - ECC, RSA, DSA or undef
keytype will be undef if the key type is not supported. In this case,
error() returns a diagnostic message.
keylen - Approximate length of the key in bits.
Other items include:
For RSA, modulus and publicExponent.
For DSA, G, P and Q.
For ECC, curve, pub_x and pub_y. curve is an OID name.
Additional detail
subjectPublicKeyParams(1) returns the standard items, and may also
return detail, which is a hashref.
For ECC, the detail hash includes the curve definition constants.
signatureAlgorithm
Returns the signature algorithm according to its object identifier.
signatureParams
Returns the parameters associated with the signatureAlgorithm as
binary. Returns undef if none, or if NULL.
Note: In the future, some signatureAlgorithms may return a hashref of
decoded fields.
Callers are advised to check for a ref before decoding...
signature( $format )
The CSR's signature is returned.
If $format is 1, in binary.
If $format is 2, decoded as an ECDSA signature - returns hashref to r
and s.
Otherwise, 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. $name
can be specified as a numeric OID.
In scalar context, a single string is returned, which may include lists
and labels.
cspName="Microsoft Strong Cryptographic Provider",keySpec=2,signature=("",0)
Special characters are escaped as described in options.
In array context, the value(s) are returned as a list of items, which
may be references.
print( " $_: ", scalar $decoded->attributes($_), "\n" )
foreach ($decoded->attributes);
See the module documentation for a list of known OID names.
It is too long to include here.
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, extensionPresent, and name2oid.
The values of extensions vary, however the following code fragment will
dump most extensions and their value(s).
print( "$_: ", $decoded->extensionValue($_,1), "\n" ) foreach ($decoded->extensions);
The sample code fragment is not guaranteed to handle all cases.
Production code needs to select the extensions that it understands and
should respect the critical boolean. critical can be obtained with
extensionPresent.
extensionValue( $name, $format )
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. The name can also be specified as a numeric
OID.
If $format is 1, the value is a formatted string, which may include
lists and labels. Special characters are escaped as described in
options;
If $format is 0 or not defined, a string, or an array reference may be
returned. The array many contain any Perl variable type.
To interpret the value(s), you need to know the structure of the OID.
See the module documentation for a list of known OID names.
It is too long to include here.
extensionPresent( $name )
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 name can also be specified as a numeric OID.
See the module documentation for a list of known OID names.
It is too long to include here.
registerOID( )
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. This enables
the OID to be translated to a name in output.
( run in 0.756 second using v1.01-cache-2.11-cpan-39bf76dae61 )