Request certificate with server-side keypair generation

When you enroll or renew a certificate using the DigiCert® IoT Trust Manager REST API, you can request the certificate using server-side keypair generation. Certificate requests that use server-side keypair generation do not need to include a CSR. Instead, DigiCert ONE generates the private key for you and returns it with the end-entity certificate in the API response.

Prerequisites

To use server-side keypair generation, you must request the certificate using an enrollment profile that:

Supports the API enrollment method.
Allows server-side keypair generation.

Request parameters

The JSON request body for certificate requests using server-side keypair generation should include these request parameters:

server_side_key_gen (boolean): If true, DigiCert ONE generates the private key for you.
key_type (string): Sets the key type for keypair generation. The key type must be allowed by the certificate profile associated with the enrollment profile in the request. Allowed key types:
- rsa_2048
- rsa_3072
- rsa_4096
- p_256
- p_384
- p_521
- ed_25519
private_key_format (string): Sets the private key format. DigiCert® IoT Trust Manager supports these formats for server-side keypair generation:
- PEM (pem)
- PKCS12 (pkcs_12)
- Certificate encrypted (cert_encrypted)

By default, certificate requests using server-side keypair generation return the private key, the end-entity certificate, and the full certificate chain (ICA and root certificates). To get the end-entity certificate and private key only, set the value of the include_certificate_chain request parameter to false.

For information about all required and optional parameters for certificate requests, see the reference documentation for the Request certificate and Renew certificate operations.

Examples

The following examples demonstrate how to request a certificate using server-side keypair generation and retrieve the private key from the response for each private key format.

PEM private key

To have DigiCert ONE generate the private key in PEM format, set the value of the private_key_format parameter to pem in the JSON body of your request.

Example 1. JSON request for PEM private key

{
  "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1",
  "certificate_profile_attributes": [
    {
      "id": "subject.common_name",
      "value": "custom common name"
    }
  ],
  "device_attributes": [
    {
      "id": "party-no",
      "value": "PN8363454893"
    }
  ],
  "server_side_key_gen": true,
  "key_type": "rsa_2048",
  "private_key_format": "pem"
}

In the default JSON response, DigiCert ONE returns the private key as a PEM-formatted string.

Example 2. JSON response with PEM private key

{
  "certificate_request_id": "1a4e7b7b-03cf-40ff-a93c-41cc0edf220c",
  "status": "AUTO_APPROVED",
  "result": "SUCCESS",
  "certificate_id": "df832ffd-7d5c-4277-99dc-99a1e2b20fc9",
  "pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

If the request is configured to return the certificate only, DigiCert ONE returns the certificate and private key in a PEM file. In the response, the Content-type header is application/x-pem-file.

PKCS12 private key

To have DigiCert ONE generate the private key in PKCS12 format, set the value of the private_key_format parameter to pkcs_12 in the JSON body of your request. Use the pkcs12_password parameter to set a password for the PKCS12 file. The password must be between 6-20 characters long, and allowed characters are A-Z, a-z, and 0-9.

Example 3. JSON request for PKCS12 private key

{
  "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1",
  "certificate_profile_attributes": [
    {
      "id": "subject.common_name",
      "value": "custom common name"
    }
  ],
  "device_attributes": [
    {
      "id": "party-no",
      "value": "PN8363454893"
    }
  ],
  "server_side_key_gen": true,
  "key_type": "rsa_2048",
  "private_key_format": "pkcs_12",
  "pkcs12_password": "password"
}

In the default JSON response, the private_key parameter returns the private key as a base64-encoded PFX file.

Example 4. JSON response with PKCS12 private key

{
  "certificate_request_id": "1a4e7b7b-03cf-40ff-a93c-41cc0edf220c",
  "status": "AUTO_APPROVED",
  "result": "SUCCESS",
  "certificate_id": "df832ffd-7d5c-4277-99dc-99a1e2b20fc9",
  "pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "private_key": "<base64_encoded_PKCS12_file>"
}

If you use Mac or Linux, you can decode the private_key string to a PFX file using the base64 command:

Example 5. Decode base64-encoded PKCS12 private key to PFX

echo "<base64_encoded_PKCS12_file>" | base64 --decode > <decoded.pfx>

If the request is configured to return the certificate only, DigiCert ONE returns the certificate and private key in a PFX file. In the response, the Content-type header is application/x-pkcs12.

Extract private key and certificates from PFX file

If your operating system includes OpenSSL, you can extract the private key and certificates from the PFX file with the pkcs12 command. When prompted, enter the password you provided in the certificate request.

Example 6. Extract private key

openssl pkcs12 -in <infile.pfx> -nocerts -out <outfile.key>

Example 7. Extract certificates

openssl pkcs12 -in <infile.pfx> -clcerts -nokeys -out <outfile.crt>

Certificate-encrypted private key

To have DigiCert ONE encrypt the private key with your own end-entity certificate, set the value of the private_key_format parameter to cert_encrypted in the JSON body of your request. Use the encryption_certificate parameter to provide the PEM-formatted end-entity certificate that DigiCert ONE should use to encrypt the private key.

Example 8. JSON request for certificate-encrypted private key

{
  "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1",
  "certificate_profile_attributes": [
    {
      "id": "subject.common_name",
      "value": "custom common name"
    }
  ],
  "device_attributes": [
    {
      "id": "party-no",
      "value": "PN8363454893"
    }
  ],
  "server_side_key_gen": true,
  "key_type": "rsa_2048",
  "private_key_format": "cert_encrypted",
  "encryption_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
}

In the default JSON response, the private key is returned as an encrypted, base64-encoded ZIP archive.

Example 9. JSON response with certificate-encrypted private key

{
  "certificate_request_id": "1a4e7b7b-03cf-40ff-a93c-41cc0edf220c",
  "status": "AUTO_APPROVED",
  "result": "SUCCESS",
  "certificate_id": "df832ffd-7d5c-4277-99dc-99a1e2b20fc9",
  "pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "private_key": "<encrypted_base64_private_key>"
}

If you use Mac or Linux, you can decode the contents of the private_key string to an encrypted ZIP file using the base64 command.

Example 10. Decode base64-encoded encrypted private key to ZIP

echo "<encrypted_base64_private_key>" | base64 --decode > <decoded.zip>

If the request is configured to return the certificate only, DigiCert ONE returns the certificate and private key in an encrypted P7M file. In the response, the Content-type header is application/pkcs7-mime.

Decrypt a certificate-encrypted P7M/ZIP archive

If your operating system includes OpenSSL, you can decrypt the ZIP file with the smime command.

For the -in argument, provide the encrypted P7M or ZIP archive containing your private key.
For the -inkey argument, provide the certificate used for encryption and its private key.

Example 11. Decrypt P7M/ZIP archive

openssl smime -binary -decrypt -aes256 -inform DER -in <encrypted-file.p7m | decoded-file.zip> -out <output-file.zip> -inkey <private-key-of-certificate-used-for-encryption.key> <certificate-used-for-encryption.pem>

In this section: