Skip to main content

Request certificates with server-side keypair generation

Learn how to use the DigiCert​​®​​ IoT Trust Manager REST API to request certificates using server-side keypair generation

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:

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

enrollment_profile_id

required

string

ID of the enrollment profile. For server-side keypair generation, use an enrollment profile that:

  • Supports the API enrollment method.

  • Allows server-side keypair generation.

certificate_profile_attributes

conditional

array of objects

List of objects with the id and value for each user-provided certificate attribute. The certificate_profile_attributes array has this format:

"certificate_profile_attributes": [
  {
    "id": "<id>",
    "value": "<value>"
  },
  ...
]

The enrollment profile configuration determines which certificate attributes are required in the certificate request. If you aren't sure which attributes to use, you can get an example JSON payload from DigiCert​​®​​ IoT Trust Manager.

Note: For a list of allowed certificate_profile[].id values, see the Request certificate schema in the Swagger UI API reference.

device_attributes

conditional

array of objects

List of objects with the id and value for each user-provided device attribute. The device_attributes array has this format:

"device_attributes": [
  {
    "id": "<id>",
    "value": "<value>"
  },
  ...
]

The enrollment profile configuration determines which device attributes are required in the certificate request. If you aren't sure which attributes to use, you can get an example JSON payload from DigiCert​​®​​ IoT Trust Manager.

server_side_key_gen

conditional

bool

To use server-side keypair generation, this parameter must be present in your request with a true value.

If true, DigiCert​​®​​ IoT Trust Manager generates the private key for you. If false (default), the certificate request must include a CSR.

key_type

optional

string

Determines the key type for keypair generation. This parameter is ignored if the key type for server-side keypair generation is fixed in the enrollment profile (key_generation_allow_to_change is false).

You must choose a key type your enrollment profile supports. If not provided, DigiCert​​®​​ IoT Trust Manager generates the private key using the default key type set for the enrollment profile.

Allowed key types are limited by the certificate profile associated with the enrollment profile in the request. Allowed key types may include:

  • rsa_2048

  • rsa_3072

  • rsa_4096

  • p_256

  • p_384

  • p_521

  • ed_25519

private_key_format

conditional

string

Determines the format of the private key (private_key) in the JSON response. Required if the request uses server-side keypair generation; otherwise, ignored. Supported formats include:

private_key_syntax

optional

string

Determines the private key syntax. Allowed values:

  • pkcs8: PKCS8 (default)

  • sec1_or_pkcs1: SEC1 (for ECC keys) or PKCS1 (for RSA keys).

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.

  • pem: Content type is application/x-pem-file.

  • pkcs_12: Content type is application/x-pkcs12

  • cert_encrypted: Content type is application/pkcs7-mime

  • der or cert_encrypted_key_only: Only JSON responses are supported. When using these private key formats, response_with_certificate_only must be true.

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.

In the default JSON response, DigiCert​​®​​ IoT Trust Manager returns the private key as a PEM-formatted string.

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.

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

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.

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.

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.

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.

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:

  1. Decode the base64 private_key value to a P7M file.

  2. Decrypt the P7M file with your encryption certificate and the corresponding private key.

  3. Decompress the resulting ZIP bundle.

Example JSON request for certificate-encrypted 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.

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:

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.

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.

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:

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 DigiCert​​®​​ 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:

  1. In DigiCert ONE, in the Manager menu (top right), select DigiCert​​®​​ IoT Trust Manager.

  2. In the DigiCert​​®​​ IoT Trust Manager menu, select Enrollment configurations > Enrollment profiles.

  3. On the Enrollment profiles page, locate the enrollment profile you are using to request certificates via API.

  4. On the Enrollment profile details page, scroll to the API section.

  5. Select the operation you want to perform (Enroll certificate or Renew certificate).

  6. Under Individual certificate requests, expand the example for server-side keypair generation: DigiCert ONE generates keypairs.

  7. Under Sample body, copy the JSON example and paste it into the text editor or HTTP client of your choice.

In this section: