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.
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.
{ "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.
{ "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
.
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.
{ "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.
{ "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:
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.
openssl pkcs12 -in <infile.pfx> -nocerts -out <outfile.key>
openssl pkcs12 -in <infile.pfx> -clcerts -nokeys -out <outfile.crt>
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.
{ "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.
{ "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.
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.
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>