Request certificate with server-side keypair generation

9 minute read

When you request certificates with DigiCert® IoT Trust Manager, you can use server-side keypair generation as an alternative to providing a certificate signing request (CSR) in the enrollment request. Certificate requests that use server-side keypair generation do not include a CSR. Instead, DigiCert® IoT Trust Manager generates the private key and returns it with the end-entity certificate in the API response.

Prerequisites

To request certificates using server-side keypair generation, you need:

API authentication credentials, such as an API token, service user API token, or client authentication certificate, for a user or service user with permission to manage certificates.
Enrollment profile with the following attributes:
- Supports the API enrollment method (enrollment_methods includes API).
- Allows server-side keypair generation (key_generation_option is either server_side or client_or_server_side).
Ability to send API requests.

Request parameters

To request or renew a certificate using server-side keypair generation, submit a POST request to the appropriate API endpoint:

POST {base_url}/iot/api/v1/certificate

POST {base_url}/iot/api/v1/certificate/{certificate_id}/renew

POST {base_url}/iot/api/v1/certificate/{certificate_serial_number}/renew

In your JSON payload, use the request parameters described below. The structure and required parameters vary depending on your chosen private key format (private_key_format). For example payloads for each private key format, see Examples.

Tip

This guide focuses on the parameters used to create a certificate request using server-side keypair generation. To see all options available when submitting a certificate request, see the Swagger UI API reference:

Name	Req/Opt	Type	Description
`private_key_syntax`	optional	string	Determines the private key syntax. Allowed values:
`pkcs12_password`	conditional	string	Password that protects the PKCS12 file containing the private key. Required if the value of the `private_key_format` parameter is `pkcs_12`; otherwise, ignored. Must be between 6-20 characters long. Allowed characters: `A-Z`, `a-z`, `0-9`.
`response_with_certificate_only`	optional	bool	If `false` (default), the API returns a JSON object containing the certificate and private key data. If `true`, the API returns a file with the end-entity certificate, instead of returning a JSON object. If using server-side keypair generation, the returned file also contains the private key. By default, the returned file also includes the issuing intermediate and root CAs. To omit the certificate chain from the returned file, use `"include_certificate_chain": false` in your request. Passing in a `true` value changes the content type of the response header. The content type depends on the `private_key_format` used in the request.
`include_certificate_chain`	optional	bool	If `true` (default), the `pem` response parameter includes the end-entity certificate and the issuing intermediate and root CA certificates. If `false`, the response includes data for the end-entity certificate only. Additionally, if using server-side keypair generation with a `private_key_format` of either `pkcs_12` or `cert_encrypted`, this parameter determines whether the returned `private_key` file includes the complete certificate chain.

Examples

The following examples demonstrate how to request certificates using server-side keypair generation for each private key format. Each usage example includes:

Example JSON request and response bodies.
Example commands for decoding and, if applicable, decrypting the returned private key.

PEM private key

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

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® IoT Trust Manager returns the private key as a PEM-formatted string.

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"
}

DER private key

To get the private key in DER format, set the value of the private_key_format parameter to der in the JSON body of your request.

JSON request for DER 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": "der"
}

In the default JSON response, DigiCert® IoT Trust Manager returns the private key as base64-encoded DER binary.

JSON response with DER 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": "MIIEvQIBADANBgk..."
}

Decode DER file

After obtaining the base64 private_key value, you can decode it to DER file. For example, on Mac or Linux systems, use the base64 command.

Decode private key

echo "<base64_encoded_DER_binary>" | base64 --decode > <output.der>

To run this example, replace the placeholder values:

<base64_encoded_DER_binary>: Value of private_key parameter in API response.
<output.der>: Name of DER output file.

PKCS12 private key

To get the private key in PKCS12 format, format your request payload as follows:

Set the value of the private_key_format parameter to pkcs_12.
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.

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"
}

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>"
}

Decode PFX file

After obtaining the base64 private_key value, you can decode it to PFX file. For example, on Mac or Linux systems, use the base64 command.

Decode private key

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

To run this example, replace the placeholder values:

<base64_encoded_PKCS12_file>: Value of private_key parameter in API response.
<output.pfx>: Name of PFX output file.

Extract private key and certificates from PFX file

After decoding your PFX file, you can extract the private key and certificates.

For example, if your operating system includes OpenSSL, use the pkcs12 command. When prompted, enter the password you provided in the certificate request.

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

To run this example, replace the placeholder values:

- `<infile.pfx>`: PFX file with your private key.
- `<outfile.key>`: Name of KEY output file to which your private key is written.

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

To run this example, replace the placeholder values:

- `<infile.pfx>`: PFX file with your certificates.
- `<outfile.crt>`: Name of CRT output file to which your certificates are written.

Certificate-encrypted bundle

To return a private_key value containing the encrypted private key, end-entity certificate, and (if requested) complete certificate chain, format your request payload as follows:

Set the value of the private_key_format request parameter to cert_encrypted .
Use the encryption_certificate request parameter to provide a PEM-formatted end-entity certificate that DigiCert® IoT Trust Manager can use to encrypt the private key.

This option returns a certificate bundle (ZIP file) containing your issued certificate and private key. DigiCert® IoT Trust Manager encrypts the certificate bundle and returns it as a P7M file. In the default JSON response, the private_key parameter returns the base64-encoded P7M file.

To access your certificate bundle:

Decode the base64 private_key value to a P7M file.
Decrypt the P7M file with your encryption certificate and the corresponding private key.
Decompress the resulting ZIP bundle.

Example JSON request for certificate-encrypted bundle:

Certificate encrypted bundle

{
  "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"
}

JSON response with certificate-encrypted bundle

{
  "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_certificate_bundle>"
}

Decode certificate bundle

After obtaining the base64 private_key value, you can decode it to an encrypted P7M file. For example, on Mac or Linux systems, use the base64 command.

Decode private key

echo "<base64_private_key>" | base64 --decode > <output.p7m>

To run this example, replace the placeholder values:

<base64_private_key>: Value of private_key parameter in API response.
<output.p7m>: Name of P7M output file.

Decrypt certificate bundle

After decoding your certificate bundle, you can decrypt it to a ZIP file by using the encryption certificate that was included in the enrollment request.

For example, if your operating system includes OpenSSL, use the smime command:

Decrypt private key

openssl smime -binary -decrypt -aes256 -inform DER -in <input.p7m> -out <output.zip> -inkey <encryption_key.key> <encryption_certificate.pem>

To run this example, replace the placeholder values:

<input.p7m>: P7M file with private key you want to decrypt.
<output.zip>: Name of ZIP output file to which the decrypted certificate bundle is written.
<encryption_key.key>: Path to private key for your encryption certificate.
<encryption_certificate.pem>: Path to your encryption certificate.

Certificate-encrypted private key only

To get a private_key response parameter that only contains the encrypted private key, format your request payload as follows:

Set the value of the private_key_format request parameter to cert_encrypted_key_only.
Use the encryption_certificate request parameter to provide the PEM-formatted end-entity certificate that DigiCert® IoT Trust Manager uses to encrypt the private key.

Use this option as an alternative to encrypting the entire certificate bundle.

Note

When using cert_encrypted_key_only, the API still returns the issued certificate (and, if requested, the complete certificate chain) in the pem field.

Certificate encrypted (private key only)

{
  "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_key_only",
  "encryption_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
}

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>"
}

Decode private key

After obtaining the base64 private_key value, you can decode it to an encrypted P7M file. For example, on Mac or Linux systems, use the base64 command.

Decode private key

echo "<base64_private_key>" | base64 --decode > <output.p7m>

To run this example, replace the placeholder values:

<base64_private_key>: Value of private_key parameter in API response.
<output.p7m>: Name of P7M output file.

Decrypt private key

After decoding your private key, you can decrypt it to a PEM or KEY file by using the encryption certificate that was included in the enrollment request.

For example, if your operating system includes OpenSSL, use the smime command:

Decrypt private key

openssl smime -binary -decrypt -aes256 -inform DER -in <input.p7m> -out <output.key/pem> -inkey <encryption_key.key> <encryption_certificate.pem>

To run this example, replace the placeholder values:

<input.p7m>: P7M file with private key you want to decrypt.
<output.pem/key>: Name of PEM or KEY output file to which the decrypted private key is written.
<encryption_key.key>: Path to private key for your encryption certificate.
<encryption_certificate.pem>: Path to your encryption certificate.

Get example JSON payloads from IoT Trust Manager

DigiCert® IoT Trust Manager provides example JSON payloads that you can copy and modify to construct valid certificate requests for each enrollment profile in your account. Each of these examples includes the required certificate and device attributes that are associated with the given enrollment profile. To get example JSON payloads for API enrollment requests:

In DigiCert ONE, in the Manager menu (top right), select DigiCert® IoT Trust Manager.
In the DigiCert® IoT Trust Manager menu, select Enrollment configurations > Enrollment profiles.
On the Enrollment profiles page, locate the enrollment profile you are using to request certificates via API.
On the Enrollment profile details page, scroll to the API section.
Select the operation you want to perform (Enroll certificate or Renew certificate).
Under Individual certificate requests, expand the example for server-side keypair generation: DigiCert ONE generates keypairs.
Under Sample body, copy the JSON example and paste it into the text editor or HTTP client of your choice.

Was this page helpful?

Provide feedback

Account and platform

Certificates and PKI

Signing

Devices and IoT

Other resources

Request certificate with server-side keypair generation

Prerequisites

Request parameters

Tip

Examples

PEM private key

JSON request for PEM private key

JSON response with PEM private key

DER private key

JSON request for DER private key

JSON response with DER private key

Decode DER file

Decode private key

PKCS12 private key

JSON request for PKCS12 private key

JSON response with PKCS12 private key

Decode PFX file

Decode private key

Extract private key and certificates from PFX file

Certificate-encrypted bundle

Certificate encrypted bundle

JSON response with certificate-encrypted bundle

Decode certificate bundle

Decode private key

Decrypt certificate bundle

Decrypt private key

Certificate-encrypted private key only

Note

Certificate encrypted (private key only)

JSON response with certificate-encrypted private key

Decode private key

Decode private key

Decrypt private key

Decrypt private key

Get example JSON payloads from IoT Trust Manager