To import an X509 Certificate a valid template must be created.
The template is a collection of attributes, implemented in the class
CryptokiCollection.
The meaning of "valid template" may vary from one token to another. This means that a specific template (like the one below in the sample code) may work with a token but may not work with another.
The following snippest imports an X509 certificate in the most of the tokens using a template with the most used attributes. If it doesn't work with your token refer to the reference manual of your token and see what are the valid certificate attributes in the list below the snippet.
// read the certificate
X509Certificate2 cert = new X509Certificate2(Convert.FromBase64String(certPEM));
// gets the id in binary format
byte[] id = Encoding.ASCII.GetBytes("MyKeyPairID");
// creates the template
CryptokiCollection template = new CryptokiCollection();
template.Add(new ObjectAttribute(ObjectAttribute.CKA_CLASS, CryptokiObject.CKO_CERTIFICATE));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_CERTIFICATE_TYPE, Certificate.CKC_X_509));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_TOKEN, true));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_PRIVATE, false));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_LABEL, "MyLabel"));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_ID, id));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_SUBJECT, cert.SubjectName.RawData));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_ISSUER, cert.Issuer));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_SERIAL_NUMBER,cert.SerialNumber));
template.Add(new ObjectAttribute(ObjectAttribute.CKA_VALUE, cert.RawData));
// creates the certificate object in the token
CryptokiObject certificate = session.Objects.Create(template);
The following are the attributes that can be used for an X509 Certificate, as described in the PKCS#11 2.20 specifications:
Common certificate attributes:- CKA_CERTIFICATE_TYPE - Type of certificate
- CKA_TRUSTED (boolean) The certificate can be trusted for the application that it was created.
- CKA_CERTIFICATE_CATEGORY - Categorization of the certificate: 0 = unspecified (default value), 1 = token user, 2 = authority, 3 = other entity
- CKA_CHECK_VALUE - Checksum
- CKA_START_DATE - Start date for the certificate (default empty)
- CKA_END_DATE - End date for the certificate (default empty)
The CKA_CERTIFICATE_TYPE attribute may not be modified after an object is
created. The version 2.20 of PKCS#11 specs supports the following certificate types:
- X.509 public key certificate
- WTLS public key certificate
- X.509 attribute certificate
The CKA_TRUSTED attribute cannot be set to true by an application. It must be
set by a token initialization application or by the token’s SO. Trusted certificates cannot
be modified.
The CKA_CERTIFICATE_CATEGORY attribute is used to indicate if a stored
certificate is a user certificate for which the corresponding private key is available on the
token (“token user”), a CA certificate (“authority”), or an other end-entity certificate
(“other entity”). This attribute may not be modified after an object is created.
The CKA_CERTIFICATE_CATEGORY and CKA_TRUSTED attributes will
together be used to map to the categorization of the certificates. A certificate in the
certificates CDF will be marked with category “token user”. A certificate in the
trustedCertificates CDF or in the usefulCertificates CDF will be marked with category
“authority” or “other entity” depending on the CommonCertificateAttribute.authority
attribute and the CKA_TRUSTED attribute indicates if it belongs to the
trustedCertificates or usefulCertificates CDF.
CKA_CHECK_VALUE: The value of this attribute is derived from the certificate by
taking the first three bytes of the SHA-1 hash of the certificate object’s CKA_VALUE
attribute.
The CKA_START_DATE and CKA_END_DATE attributes are for reference only;
Cryptoki does not attach any special meaning to them. When present, the application is
responsible to set them to values that match the certificate’s encoded “not before” and
“not after” fields (if any).
X509 Certificate specific attributes: - CKA_SUBJECT - DER-encoding of the certificate subject name
- CKA_ID - Key identifier for public/private key pair (default empty)
- CKA_ISSUER - DER-encoding of the certificate issuer name (default empty)
- CKA_SERIAL_NUMBER - DER-encoding of the certificate serial number (default empty)
- CKA_VALUE - BER-encoding of the certificate
- CKA_URL - If not empty this attribute gives the URL where the complete certificate can be obtained (default empty)
- CKA_HASH_OF_SUBJECT_PUBLIC_KEY - SHA-1 hash of the subject public key (default empty)
- CKA_HASH_OF_ISSUER_PUBLIC_KEY - SHA-1 hash of the issuer public key (default empty)
- CKA_JAVA_MIDP_SECURITY_DOMAIN - Java MIDP security domain: 0 = unspecified (default value), 1 = manufacturer, 2 = operator, 3 = third party
Only the CKA_ID, CKA_ISSUER, and CKA_SERIAL_NUMBER attributes may be
modified after the object is created.
The CKA_ID attribute is intended as a means of distinguishing multiple publickey/
private-key pairs held by the same subject (whether stored in the same token or not).
(Since the keys are distinguished by subject name as well as identifier, it is possible that
keys for different subjects may have the same CKA_ID value without introducing any
ambiguity.)
It is intended in the interests of interoperability that the subject name and key identifier
for a certificate will be the same as those for the corresponding public and private keys
(though it is not required that all be stored in the same token). However, Cryptoki does
not enforce this association, or even the uniqueness of the key identifier for a given
subject; in particular, an application may leave the key identifier empty.
The CKA_ISSUER and CKA_SERIAL_NUMBER attributes are for compatibility with
PKCS #7 and Privacy Enhanced Mail (RFC1421). Note that with the version 3
extensions to X.509 certificates, the key identifier may be carried in the certificate. It is
intended that the CKA_ID value be identical to the key identifier in such a certificate
extension, although this will not be enforced by Cryptoki.
The CKA_URL attribute enables the support for storage of the URL where the certificate
can be found instead of the certificate itself. Storage of a URL instead of the complete
certificate is often used in mobile environments.
The CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY attributes are used to store the hashes of
the public keys of the subject and the issuer. They are particularly important when only
the URL is available to be able to correlate a certificate with a private key and when
searching for the certificate of the issuer.
The CKA_JAVA_MIDP_SECURITY_DOMAIN attribute associates a certificate with
a Java MIDP security domain.