CertEnroll Pkcs10

The PKCS10 method provides enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). with on-device key generation. The basic workflow A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. with on-device key generation is:

1. Client application retrieves list of available certificate templates using the Keyfactor Command API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command..
2. Client generates a public/private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. pair based on the key size The key size or key length is the number of bits in a key used by a cryptographic algorithm. requirements from the selected template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received..
3. Client creates a PKCS10 Certificate Signing Request A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. (CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA.) using the keypair and template attributes.
4. Client sends the PKCS10 request and selected template name to the API which submits the request to the enterprise CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. and returns the certificates received from the CA to the software client.

If successful, the response from the CA will be a PKCS#7 message containing the issued certificate and (optionally) the certificate chain. Once the response is received, a software client can construct a PKCS12 package with the previously generated key pair In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. and the issued certificates, import the keys and certificates into an application-specific store, such as Apple’s KeyChain Services or a Java Keystore A Java KeyStore (JKS) is a file containing security certificates with matching private keys. They are often used by Java-based applications for authentication and encryption., or perform any other processing required. The flow (for versions 1 and 2) is shown in Figure 431: Pkcs#10-Based Enrollment Request. The version 3 flow is identical except that a token is not required for enrollment, so the initial exchange with the token endpoint An endpoint is a URL that enables the API to gain access to resources on a server. is not needed. The difference in version 3 is explained in Table 674: CertEnroll Security Headers.

Figure 431: Pkcs#10-Based Enrollment Request

The PKCS10-based method is the most secure way to enroll for certificates with Keyfactor Command. The PKCS10 method utilizes on-device key generation instead of the server-based key generation used for the PKCS12 method. The PKCS10 method also requires the use of a certificate template that populates the subject and/or subject alternate name from Active Directory. This reliance on certificate templates allows Keyfactor Command to utilize the security mechanisms built into the Microsoft CA Services.

To use this method, the following configuration should be present on the Keyfactor Command server and in its domain:

• IIS application pool configured with a non-administrator domain member account
• API Application with valid key, secret, template, and CA
• Certificate template configured to:
  • Populate subject and/or subject alternate name (SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common.) fields from AD as needed. While the PKCS#10 request may contain data for these fields, the selected certificate template may replace those values with information from Active Directory.
  • Not allow private key exportation
  • Grant enroll permission to all users who may enroll for a certificate

The request parameters that should be sent for version 1 and 2 of the enrollment are listed in Table 677: POST /1/Pkcs10 and /2/Pkcs10 Request Body and for version 3 in Table 678: POST /3/Pkcs10 Request Body, while the response format (for all versions) is given in Table 679: POST /*/Pkcs10 Response Body:

Table 677: POST /1/Pkcs10 and /2/Pkcs10 Request Body

Parameter Name	Parameter Value
Flags	Bit flags that determine the enrollment behavior. At this time, the only available bit flag is: 0x01 = Include certificate only (default is to return certificate + trust chain)
TemplateName	Name of the certificate template to use for enrollment. This name must match one of the template names configured for this application key in the API Applications page.
Pkcs10Request	Contains a base-64-encoded PKCS#10 request generated on the device. The key sizes used to generate the PKCS#10 request must match the key size specified in the certificate template.
MetadataList	A list of key value pairs for each metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. item that is to be set on the issued certificate in Keyfactor Command. This parameter A parameter or argument is a value that is passed into a function in an application. is optional.

In version 3 of the API, the fields used by versions 1 and 2 are wrapped in an outer envelope and sent along with a timestamp. By including this timestamp in the request body and using this as part of the HMAC signature computation, the need for a current API access token is eliminated without reducing security. The request structure for version 3 of this endpoint is shown in Table 678: POST /3/Pkcs10 Request Body:

Table 678: POST /3/Pkcs10 Request Body

Parameter Name	Parameter Value
Timestamp	ISO 8601 Timestamp in UTC timezone, e.g. "2018-11-22T20:41:08.440Z"
Request	JSON object in the same format as a version 1/2 Pkcs10 enrollment request (see Table 677: POST /1/Pkcs10 and /2/Pkcs10 Request Body).

 

Table 679: POST /*/Pkcs10 Response Body

Parameter Name	Parameter Value
SerialNumber	String containing the hexadecimal serial number of the issued certificate.
IssuerDN	Distinguished Name of the certificate's issuer.
Thumbprint	Thumbprint of the issued certificate.
CMSID	Identifier for this certificate in Keyfactor Command. Can be used to identify the cert in future API requests.
CMSRequestId	Identifier for the certificate request in Keyfactor Command. Can be used if certificate is pending issuance.
Certificates	If the CERT_ONLY flag (0x01) is set in the request, then the response is a base-64 encoding of the DER A DER format certificate file is a DER-encoded binary certificate. It contains a single certificate and does not support storage of private keys. It sometimes has an extension of .der but is often seen with .cer or .crt.-encoded cert. If the CERT_ONLY flag is not set, the response is a base-64 encoding of a PKCS7 containing the cert and its chain.
RequestDisposition	Value returned by the CA in response to this certificate request
DispositionMessage	Message accompanying the disposition value returned by the CA

Example Request

Versions 1 and 2

POST http://<host>/CMSApi/CertEnroll/1/Pkcs10 HTTP/1.1

{
	"Flags":0,
	"TemplateName": "User",
	"Pkcs10Request":"-----BEGIN CERTIFICATE REQUEST-----
		<base64-encoded-certificate-request>
		-----END CERTIFICATE REQUEST-----\n"
}

Example Request

Version 3

{
	"Timestamp" : "2017-12-18T19:56:12.365Z",
	"Request": {
		"Flags":0, 
		"TemplateName": "User",
		"Pkcs10Request":"-----BEGIN CERTIFICATE REQUEST-----
		<base64-encoded-certificate-request>
		-----END CERTIFICATE REQUEST-----",
		"MetadataList":{"<metadata type name>":"<metadata value>","<metadata type name>":"<metadata value">}
	}
}

Example Response

{
	"SerialNumber": "2684C97728678A944A67C03E7192785B",
	"IssuerDN": "CN=CorpCA1, DC=keyexample, DC=com",
	"Thumbprint": "FDB3A0F4ADCF9C39A2BB639898EE1670DFDBF5BB",
	"CMSID": 5,
	"CMSRequestId": 3,
	"Certificates": <PEM-encoded certificates>
	"RequestDisposition": "Issued",
	"DispositionMessage": ""
}