Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Crypt::PKCS10(3)      User Contributed Perl Documentation     Crypt::PKCS10(3)

       Crypt::PKCS10 - parse PKCS #10 certificate requests

	   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

       "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.

       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

       If PEM, other data (such	as mail	headers) may precede or	follow the

	   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.


       The options are specified as "name => value".

       If the first option is a	HASHREF, it is expanded	and any	remaining
       options are added.

	   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.

	   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.

	   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

	   Defaults to false if	acceptPEM is true, otherwise true.

	   If true, any	API function that sets an error	string will also

	   If false, exceptions	are only generated for fatal conditions.

	   The default is false.  API version 1	only..

	   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.

	   The default is true.

	   If true, most invalid base64	characters in PEM data will be
	   ignored.  For example, this will accept CSRs	prefixed with '> ', as
	   e-mail when the PEM is inadvertently	quoted.	 Note that the BEGIN
	   and END lines may not be corrupted.

	   If false, invalid base64 characters in PEM data will	cause the CSR
	   to be rejected.

	   The default is false.

	   If true, $csr is the	name of	a file containing the CSR.

	   If false, $csr contains the CSR or is an open file handle.

	   The default is false.

	   If true, the	CSR's signature	is checked.  If	verification fails,
	   "new" will fail.  Requires API version 1.

	   If false, the CSR's signature is not	checked.

	   The default is true for API version 1 and false for API version 0.

	   See "checkSignature"	for requirements and limitations.

       No exceptions are generated, unless "dieOnError"	is set or "new()" is
       called in void context.

       The defaults will accept	either PEM or DER from a string	or file	hande,
       which will not be set to	binary mode.  Automatic	detection of the data
       format may not be reliable on file systems that represent text and
       binary files differently. Set "acceptPEM" to false and "PEMonly"	to
       match the file type on these systems.

       The object will stringify to a human-readable representation of the
       CSR.  This is useful for	debugging and perhaps for displaying a
       request.	 However, the format is	not part of the	API and	may change.
       It should not be	parsed by automated tools.

       Exception: The public key and extracted request are PEM blocks, which
       other tools can extract.

       If another object inherits from "Crypt::PKCS10",	it can extend the
       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.

       Returns the binary (ASN.1) section of the request that is signed	by the

       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
	 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.


       Returns the common name(s) from the subject.

	   my $cn = $decoded->commonName();


       Returns the organizational unit name(s) from the	subject


       Returns the organization	name(s)	from the subject.


       Returns the email address from the subject.


       Returns the state or province name(s) from the subject.


       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:

	* rfc822Name
	* dNSName
	* 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
	In scalar context, returns the SAN as a	string.

       Returns the structure version as	a string, e.g. "v1" "v2", or "v3"

       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

       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.

       Returns the signature algorithm according to its	object identifier.

       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

       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 Table of	known OID names	below for a list of names.

       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

       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

   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

       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 Table of	known OID names	below for a list of names.

   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 Table of	known OID names	below for a list of names.

   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. ''

       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.

       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 => '', $longname => 'commonName',
       $shortname => 'CN'"

       To register a shortname for an existing OID without one,	specify
       $longname as "undef".

       E.g. To register	/E for emailAddress, use:
	 "Crypt::PKCS10->registerOID( '1.2.840.113549.1.9.1', undef, 'e' )"

       Generates an exception if any argument is not valid, or is in use.

       Returns true otherwise.

       Verifies	the signature of a CSR.	 (Useful if new() specified
       "verifySignature	=> 0".)

       Returns true if the signature is	OK.

       Returns false if	the signature is incorrect.  "error()" returns the

       Returns undef if	it was not possible to complete	the verification
       process (e.g. a required	Perl module could not be loaded	or an
       unsupported key/signature type is present.)

       Note: Requires Crypt::PK::* for the used	algorithm to be	installed. For
       RSA v1.5	padding	is assumed, PSS	is not supported (validation fails).

       "CertificateTemplate" returns the certificateTemplate attribute.

       Equivalent to "extensionValue( 'certificateTemplate' )",	which is

   Table of known OID names
       The following OID names are known.  They	are used in returned strings
       and structures, and as names by methods such as extensionValue.

       Unknown OIDs are	returned in numeric form, or can be registered with

	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			      (DSA)
	1.2.840.10040.4.3	   dsaWithSha1		      (DSA with	SHA1)
	1.2.840.10045.2.1	   ecPublicKey
	1.2.840.10045.3.1.1	   secp192r1
	1.2.840.10045.3.1.7	   secp256r1
	1.2.840.10045.4.3.1	   ecdsa-with-SHA224
	1.2.840.10045.4.3.2	   ecdsa-with-SHA256
	1.2.840.10045.4.3.3	   ecdsa-with-SHA384
	1.2.840.10045.4.3.4	   ecdsa-with-SHA512
	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)	   CERT_EXTENSIONS	   msCodeInd	   msCodeCom	   msCTLSign	   msTimeStamping	   msSGC	   msEFS   msEFSRecovery	   msWHQLCrypto	   msNT5Crypto	   msOEMWHQLCrypto	   msEmbeddedNTCrypto	   msRootListSigner	   msQualifiedSubordination	   msKeyRecovery	   msDocumentSigning	   msLifetimeSigning	   msMobileDeviceSoftware	   RENEWAL_CERTIFICATE	   ENROLLMENT_NAME_VALUE_PAIR	   ENROLLMENT_CSP_PROVIDER	   OS_Version	   certificateTemplateName	   msSmartCardLogon	   certificateTemplate	   ApplicationCertPolicies	   ClientInformation		   keyPurposeKdc	      (KDC Authentication)	   CPS	   userNotice	   serverAuth	   clientAuth	   codeSigning	   emailProtection	   timeStamping	   OCSPSigning	   sshClient	   sshServer	   countryOfResidence		   sha1WithRSAEncryption      (SHA1 with RSA signature)	   brainpoolP160r1	   brainpoolP160t1	   brainpoolP192r1	   brainpoolP192t1	   brainpoolP224r1	   brainpoolP224t1	   brainpoolP256r1	   brainpoolP256t1	   brainpoolP320r1	   brainpoolP320t1	   brainpoolP384r1	   brainpoolP384t1	   brainpoolP512r1	   brainpoolP512t1		   sect163k1		   sect163r2		   sect283k1		   sect283r1		   sect233k1		   sect233r1		   secp224r1		   secp384r1		   secp521r1		   sect409k1		   sect409r1		   sect571k1		   sect571r1			   commonName			   surname		      (Surname)			   serialNumber			   countryName			   localityName			   stateOrProvinceName			   streetAddress		   organizationName		   organizationalUnitName		   title		      (Title)		   description		      (Description)		   searchGuide		   businessCategory		   postalAddress		   postalCode		   postOfficeBox		   physicalDeliveryOfficeName		   telephoneNumber		   facsimileTelephoneNumber		   name			      (Name)		   givenName		   initials		   generationQualifier		   uniqueIdentifier		   dnQualifier		   houseIdentifier		   pseudonym		   subjectKeyIdentifier	      (SubjectKeyIdentifier)		   keyUsage		      (KeyUsage)		   subjectAltName		   basicConstraints	      (Basic Constraints)		   certificatePolicies		   anyPolicy		   extKeyUsage		      (EnhancedKeyUsage)
	2.16.840.	   sha256		      (SHA-256)
	2.16.840.	   sha384		      (SHA-384)
	2.16.840.	   sha512		      (SHA-512)
	2.16.840.	   sha224		      (SHA-224)
	2.16.840.	   dsaWithSha224
	2.16.840.	   dsaWithSha256
	2.16.840.	   dsaWithSha384
	2.16.840.	   dsaWithSha512
	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	   netscapeComment
	2.16.840.1.113730.4.1	   nsSGC

       In addition to the code snippets	contained in this document, the
       examples/ directory of the distribution contains	some sample

       Also, the t/ directory of the distribution contains a number of tests
       that exercise the API.  Although	artificial, they are another good
       source of examples.

       Note that the type of data returned when	extracting attributes and
       extensions is dependent on the specific OID used.

       Also note that some functions not listed	in this	document are tested.
       The fact	that they are tested does not imply that they are stable, or
       that they will be present in any	future release.

       The test	data was selected to exercise the API; the CSR contents	are
       not representative of realistic certificate requests.

       Martin Bartosch contributed preliminary EC support:  OIDs and tests.

       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.

       Gideon Knocke <>	Timothe	Litt <>

       GPL v1 -- See LICENSE file for details

perl v5.32.0			  2018-12-14		      Crypt::PKCS10(3)


Want to link to this manual page? Use this URL:

home | help