Importing a private key via API (PKCS #8)¶

The imports function allows you to programmatically import private keys with their corresponding certificates into the TLS Protect Cloud platform. This feature allows customers to import private keys and certificates that would enable them to use the Push Provisioning feature for non-ASK certificates and would also allow them to use TLS Protect Cloud as an enterprise vault for their machine identities.

Important

Before attempting this import, ensure you have added your corresponding certificate chain into a trusted CA certificate in TLS Protect Cloud. Learn more about Trusted CA Certificates.

Before you begin¶

Having knowledge of Data Encryption Key (DEK) encryption is a prerequisite for this API. To learn more about DEK encryption, see our docs.

Some things to note in the POST request:

If a value in passwordEncryptedPrivateKey is provided, a value in the dekEncryptedPassword field must also be provided. Refer to this Recipe to learn how to encrypt the password.
If a value in dekEncryptedPrivateKey is provided , a value in dekEncryptedPassword field is not needed.
passwordEncryptedPrivateKey refers to a PKCS #8 private key encrypted by a password.
dekEncryptedPrivateKey refers to a PKCS #8 private key encrypted by the DEK (not by the password).
The values for encryptionKeyId & edgeInstanceId must be provided for the imports function to work.

Note

Private keys must be in PKCS #8 format and encrypted. Both the keys and X.509 certificates must be PEM encoded. Also, there is a limit of 100 keys per API call. The API will respond with an error if you input more than 100 keys.

To import a list of certificates and their corresponding private keys

If you have not already done so, obtain an API key.

Use the imports function to import up to 100 private keys in a single API call. For example:

POST https://api.venafi.cloud/outagedetection/v1/certificates/imports
tppl-api-key: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

In the JSON body, insert the appropriate values. Note that importInformation is an array, and it can have multiple objects. Each object represents a key and related information. For example:
Tip

You can run the GET /v1/edgeinstances call to retrieve the edgeInstanceId and encryptionKeyId values that you will need below. Note in the GET /v1/edgeinstances response you will use id in the edgeinstances object for the edgeInstanceId.
```
 GET /v1/edgeinstances/ HTTP/1.1 
 Host: api.venafi.cloud
 tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
Example request
```
{
  "edgeInstanceId": "<your edgeInstanceId>",
  "encryptionKeyId": "<your encryptionKeyId>",
  "importInformation": [
    {
      "certificate": "<pem>",
      "passwordEncryptedPrivateKey": "<pem>",
      "dekEncryptedPrivateKey": "<base64 encoded string>",
      "dekEncryptedPassword": "BNSr0IAm9uFrCPbz78AbB/XeNBwT4h6raWX6EEuEtzuoaKRYtV3QGShQP0islB1Gnrt34XeQa5Is"
    }
  ]
}
```
Example response
```
HTTP 201 Created
{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "creationDate": "2022-11-11T16:34:41.666Z"
}
```
The response will return the job id, which you will use to check the import status below. There is a limit of 100 keys per API call. The API will respond with an error if you input more than 100 keys.

Check the status of the import and retrieve import details

Use the imports api to get detailed information for each certificate and private key imported related to the import id. For example:

GET https://api.venafi.cloud/outagedetection/v1/certificates/imports/3fa85f64-5717-4562-b3fc-2c963f66afa6
tppl-api-key: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Example response

HTTP 200 Created
{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "PROCESSING",
    "results": [
       {
          "certificateBytes": [
          "string"
          ],
          "fingerprint": "string",
          "status": "IMPORTED",
          "reason": "string"
       }
    ]
}

What's next?¶

Learn more about Data Encryption Key (DEK).
Learn more about downloading a keystore.