CKM_ENCODE_X_509

Supported Operations

Encrypt and Decrypt	No
Sign and Verify	No
SignRecover and VerifyRecover	No
Digest	No
Generate Key/Key-Pair	No
Wrap and Unwrap	No
Derive	Yes
Available in FIPS Mode	Yes
Restrictions in FIPS Mode	None

Key Size Range and Parameters

Minimum	0
FIPS Minimum	0
Maximum	None
Parameter	CK_MECH_TYPE_AND_OBJECT

Description

This mechanism is used with the C_DeriveKey function to derive an X.509 certificate from a public key or a PKCS#10 certification request. This mechanism creates a new X.509 certificate based on the provided public key or certification request signed with a CA key. This mechanism takes no parameter.

The new certificate validity period is based on the CKA_START_DATE and CKA_END_DATE attributes on the base object. If the start date is missing the current time is used. If the end date is missing the certificate is valid for one year. These dates may be specified as relative values by adding the + character at the start of the date value.  The start date is relative to 'now' and the end date is relative to the start date if relative times are specified. Negative relative times are not allowed. If the start or end date is invalid then the error CKR_TEMPLATE_INCONSISTENT is returned.

The certificate’s serial number is taken from the template’s CKA_SERIAL_NUMBER, CKA_SERIAL_NUMBER_INT or the signing key’s CKA_USAGE_COUNT in that order. If none of these values is available CKR_WRAPPING_KEY_HANDLE_INVALID error is returned.

To determine the Subject distinguished name for the new certificate if the base object is a public key the algorithm will use the CKA_SUBJECT_STR, CKA_SUBJECT from the template or the base key (in that order). If none of these values is available CKR_KEY_HANDLE_INVALID is returned.

It is also possible to include arbitrary X.509 extensions in the certificate. These are not verified for validity nor parsed for correctness. Rather they are included verbatim in the newly generated certificate. In order to specify an extension use the CKA_PKI_ATTRIBUTE_BER_ENCODED attribute with the value specified as a BER encoding of the attribute. If the base object is a Certification request or a self-signed certificate the subject is taken from the objects encoded subject name.

Currently this mechanism supports generation of RSA or DSA certificates. On success, a handle to a new CKO_CERTIFICATE object is returned. The certificate will include the CKA_ISSUER, CKA_SERIAL_NUMBER and CKA_SUBJECT attributes as well as a CKA_VALUE attribute which will contain the DER encoded certificate.

To create a X.509 certificate that uses EC keys, either provide a PKCS#10 certificate request that was created with EC keys, or provide an EC public key for the hBaseKey parameter to the function. To sign the certificate as a CA using EC keys, use the CKM_ECDSA_SHA1 mechanism to initialize the sign operation before calling C_DeriveKey().

Usage:

>Create a key-pair using the CKM_RSA_PKCS mechanism (this is the key-pair for the new certificate), or

>Create a CKO_CERTIFICATE_REQUEST object (with the object's CKA_VALUE attribute set to the PKCS#10 data)

>This object is the "base-key" used in the C_DeriveKey function

>Initialize the signature mechanism to sign the request using C_SignInit. Note that a digest / sign mechanism must be chosen.  For example, CKM_SHA1_RSA_PKCS

>Call C_DeriveKey with CKM_ENCODE_X_509 to perform the generation

The new certificate's template may contain:

CKA_ISSUER_STR CKA_ISSUER	The distinguished name of the issuer of the new certificate.  If this attribute is not included the issuer is taken from the signing key's CKA_SUBJECT attribute.  CKA_ISSUER is the encoded version of this attribute.
CKA_SERIAL_NUMBER_INT CKA_SERIAL_NUMBER	The serial number of the new certificate.  If this attribute is not included the serial number is set to the value of the CKA_USAGE_COUNT attribute of the signing key.  CKA_SERIAL_NUMBER is the encoded version of this attribute.
CKA_SUBJECT_STR CKA_SUBJECT	If the base key (i.e. the input object) is a public key then either the template must contain this attribute or the public key must have a CKA_SUBJECT attribute.  This attribute contains the distinguished name of the subject.  When the base key is a PKCS#10 certification request the CKA_SUBJECT information is taken from there.  CKA_SUBJECT is the encoded version of this attribute.
CKA_START_DATE CKA_END_DATE	These attributes are used to determine the new certificate’s validity period.  If the start date is missing the current date is used.  If the end date is missing the date is set to one year from the start date.  Relative values may be specified (see above).
CKA_PKI_ATTRIBUTE_BER _ENCODED	These attributes are used to determine the new certificate’s extended attributes.

Return to ProtectToolkit-C Mechanisms