CertEnroll Pkcs12

The PCKS12-based POST enrolls for a certificate with a server-generated private keyClosed 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.. It generates a PKCS#12Closed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. file that is protected by the password specified in the request and returns a base-64-encoded PKCS#12 response if successful.

The basic workflowClosed 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 server-based key generation is:

  1. Third-party software client retrieves a list of available certificate templates using the Keyfactor Command APIClosed 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. Third-party software client sends the selected templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. name and a password to the API. The Keyfactor Command component will:
    1. Generate the RSA key pairClosed 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..
    2. Submit the request to the CAClosed 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. configured for the API application and retrieve the issued certificate.
    3. Create a PKCS12 blob with the private key, the issued certificate, and the certificate trust chain using the supplied password.
    4. Return the PKCS12 blob to the API client.

Figure 432: Pkcs#12-Based Enrollment Request

As with the Pkcs10 methods, versions 1 and 2 use the flow shown in Figure 432: Pkcs#12-Based Enrollment Request, while version 3 does not require a token and uses a timestamp instead. For these methods, keys are generated on the server and returned to the client in the form of a P12Closed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. (PFXClosed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers.) file. This requires that the certificate’s private key is transmitted over the network and temporarily stored on the server, which can present a security risk. For this reason, Keyfactor recommends that clients which are capable of generating their own keypair and submitting a CSRClosed 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. use the Pkcs10 enrollment. When clients do not have the capability or the processing power to do this, the Pkcs12 offers an alternate method. Certificate templates are used on the Microsoft CA; however, the private key must be marked as exportable in the template.

To use this method, the following configuration needs to be present on the Keyfactor Command server:

  • Certificate template configured to:
    • Allow the requestor (Keyfactor Command) to supply the subject and subject alternate name details
    • Allow the private key to be exported
    • Grant enroll permission to the Keyfactor Command application pool user—no other user needs enroll permissions for this template and for best security, none should be granted to other users
  • IIS application pool user configured to be a non-administrative domain member account
  • The Load User Profile option configured to true under the advanced settings for the application pool

The format of a Pkcs12 request is given in Table 680: POST /1/Pkcs12 and /2/Pkcs12 Request Body and Table 681: POST /3/Pkcs12 Request Body, while the response format is given in Table 682: POST /*/Pkcs12 Response Body.

Table 680: POST /1/Pkcs12 and /2/Pkcs12 Request Body

Parameter Name

Parameter Value

Flags

Bit flags that determine the enrollment behavior. At this time, there are no available bit flags so this value should be set to "0" (zero).

TemplateName

Name of the certificate template used for enrollment. This name must match- one of the allowed template names.

Pkcs12Password

PKCS12 password. Must be 8 or more characters.

SubjectNameAttributes

Token values that are substituted into the API subject format string. When needed values are not provided, Keyfactor Command will attempt to use the corresponding field from the requester’s AD account. If no attributes are needed in the request, you must still include this attribute and set the value to null. Also, note that, although the terms are similar, SubjectNameAttributes are NOT the same as Subject Alternative Names, which are supplied separately in the SubjectAltNameElements field.

Values can be supplied either as an array of key/value pairs or as a dictionary in the form {"Field1" : "Value1", "Field2" : "Value2"}.

SubjectAltNameElements

Contains an array of key/value pairs that represent the elements for Keyfactor Command to use when generating the certificate’s subject alternative nameClosed 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.. This parameterClosed A parameter or argument is a value that is passed into a function in an application. is optional. The key will be the numeric subject alternative name flag (in string form), associated with the value. The valid subject alternative name flags are as follows:

Value

Definition

0

None

1

UPN

2

RFC822

3

DNSClosed The Domain Name System is a service that translates names into IP addresses.

4

IP Address

5

URI

6

Email

7

GUID

8

Registered Id

9

Directory name
MetadataList A list of key value pairs for each metadataClosed 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 is optional.

 

Table 681: POST /3/Pkcs12 Request Body

Parameter Name

Parameter Value

Timestamp

ISO 8601 Timestamp, e.g. "2018-11-22T20:41:08.440000"

Request

JSON object in the same format as a version 1/2 Pkcs10 enrollment request (see Table 680: POST /1/Pkcs12 and /2/Pkcs12 Request Body).

 

Table 682: POST /*/Pkcs12 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.

Pkcs12Blob

Base-64-encoded representation of the Pkcs#12 certificate that was issued, if any.

RequestDisposition

Value returned by the CA in response to this certificate request.

DispositionMessage

Message accompanying the disposition value returned by the CA.

This method allows additional attributes to be included in the certificate’s subject name. A common use for this is the inclusion of a device class identifier, such as "iPhone 4S". On the Keyfactor Command server there is a configuration property to define the format of the subject name. An example is:

"CN={cn},OU=Device Model {deviceType}"

For each of the tokens given in {brackets}, Keyfactor Command will replace the value with the corresponding value in the SubjectNameAttributes field of the request, if present. If no value is provided, it will attempt to look up the value in the requester’s AD account. In this example, Keyfactor Command might replace the string "{deviceType}" with attribute value "deviceType" supplied in the SubjectNameAttributes key-value-pair structure inside of the JSON request from the API client, and (if "cnClosed A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com)." is not specified in the request) the "{cn}" string would be replaced with the value of the "cn" property from the user’s Active Directory properties. If a matching token cannot be found either in the request or in AD, no value is substituted.

Example Request

Versions 1 and 2

POST http://<host>/CMSApi/CertEnroll/2/Pkcs12 HTTP/1.1 

{
	"Flags":0,
	"Pkcs12Password": "12341234",
	"TemplateName": "User",
	"SubjectNameAttributes": {"deviceid":"iPad"}]
}

Example Request

Version 3

POST http://<host>/CMSApi/CertEnroll/3/Pkcs12 HTTP/1.1 

{
	"Timestamp" : "2017-12-18T19:56:12.365Z",
	"Request": {
		"Flags":0,
		"Pkcs12Password": "12341234",
		"TemplateName": "User",
		"SubjectNameAttributes": [{"key":"deviceid","value":"iPad"}],
		"MetadataList":{"<metadata type name>":"<value>","<metadata type name>":<value>"}
	}
}

Example Response

Status Code: 200

{
	"SerialNumber": "690003CC096AC71023934747AA00000003CC09",
	"IssuerDN": "CN=jdk-CA1, DC=jdk, DC=com",
	"Thumbprint": "04259811B3BC522093532FBA5F4C1FA3C0969A87",
	"CMSID": 8,
	"CMSRequestId": 6,
	"Pkcs12Blob": <base64-encoded PKCS#12>,
	"RequestDisposition": "Issued",
	"DispositionMessage": ""
}