--- title: "Request certificate with server-side keypair generation" source_url: https://dev.digicert.com/iot-trust-manager-api/tutorials/request-certificate-with-server-side-keypair-generation.html --- 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: **Request certificate** ```console POST {base_url}/iot/api/v1/certificate ``` **Renew certificate by ID** ```console POST {base_url}/iot/api/v1/certificate/{certificate_id}/renew ``` **Renew certificate by serial number** ```console POST {base_url}/iot/api/v1/certificate/{certificate_serial_number}/renew ``` In your JSON payload, use the request parameters [described below](#N1691434613920). 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](#section-idm4556635192560032993958160279). > **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: > > - [Request certificate](https://one.digicert.com/iot/api-docs/index.html#/Certificates/requestCertificate) > - [Renew certificate](https://one.digicert.com/iot/api-docs/index.html#/Certificates/renewCertificate) | 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. | {.params-table} ## 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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```bash echo "" | base64 --decode > ``` To run this example, replace the placeholder values: - ``: Value of `private_key` parameter in API response. - ``: 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 ```json { "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 ```json { "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": "" } ``` ## 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 ```bash echo "" | base64 --decode > ``` To run this example, replace the placeholder values: - ``: Value of `private_key` parameter in API response. - ``: 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. **Extract private key** ```bash openssl pkcs12 -in -nocerts -out To run this example, replace the placeholder values: - ``: PFX file with your private key. - ``: Name of KEY output file to which your private key is written. ``` **Extract certificates** ```bash openssl pkcs12 -in -clcerts -nokeys -out To run this example, replace the placeholder values: - ``: PFX file with your certificates. - ``: 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: 1. [Decode the base64 private_key value to a P7M file.](#section-idm33382864544524) 2. [Decrypt the P7M](#section-idm33382864623126) file with your encryption certificate and the corresponding private key. 3. Decompress the resulting ZIP bundle. Example JSON request for certificate-encrypted bundle: ## Certificate encrypted bundle ```json { "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 ```bash { "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": "" } ``` ## 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 ```bash echo "" | base64 --decode > ``` To run this example, replace the placeholder values: - ``: Value of `private_key` parameter in API response. - ``: 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 ```bash openssl smime -binary -decrypt -aes256 -inform DER -in -out -inkey ``` To run this example, replace the placeholder values: - ``: P7M file with private key you want to decrypt. - ``: Name of ZIP output file to which the decrypted certificate bundle is written. - ``: Path to private key for your encryption certificate. - ``: 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. > **Info** > > 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) ```json { "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 ```json { "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": "" } ``` ## 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 ```bash echo "" | base64 --decode > ``` To run this example, replace the placeholder values: - ``: Value of `private_key` parameter in API response. - ``: 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 ```bash openssl smime -binary -decrypt -aes256 -inform DER -in -out -inkey ``` To run this example, replace the placeholder values: - ``: P7M file with private key you want to decrypt. - ``: Name of PEM or KEY output file to which the decrypted private key is written. - ``: Path to private key for your encryption certificate. - ``: 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: 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.