Importing private keys via API (PKCS8)

The imports function lets you programmatically import private keys with their corresponding certificates into Next-Gen Trust Security (NGTS). This lets you import private keys and certificates so you can use the Push Provisioning feature for non-ASK certificates, and use NGTS as an enterprise vault for your machine identities.

note

Before attempting this import, ensure you have added your corresponding certificate chain to a trusted CA certificate. See Trusted CA Certificates in the NGTS product docs.

Before you begin

Knowledge of Data Encryption Key (DEK) encryption is a prerequisite for this API.

• Authenticate to the NGTS API. NGTS uses OAuth 2.0 machine accounts, not user API keys — see Getting started with the NGTS API to obtain a Bearer token.
• Note the following about the POST request body:
  • If a value in passwordEncryptedPrivateKey is provided, a value in dekEncryptedPassword must also be provided.
  • If a value in dekEncryptedPrivateKey is provided, a value in dekEncryptedPassword 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 and 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. There is a limit of 100 keys per API call; the API returns an error if you input more than 100 keys.

Import certificates and their private keys

1. Retrieve the edgeInstanceId and encryptionKeyId values you'll need. Run the edgeinstances call and use the id from the edgeinstances object as the edgeInstanceId:

   GET https://api.strata.paloaltonetworks.com/ngts/v1/edgeinstances
   Authorization: Bearer <access_token>

2. Use the imports endpoint to import up to 100 private keys in a single API call:

   POST https://api.strata.paloaltonetworks.com/ngts/v1/certificates/imports
   Authorization: Bearer <access_token>

   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 returns the job id, which you use to check the import status below.

Check the status of the import

Use the imports API to get detailed information for each certificate and private key imported, using the import id:

GET https://api.strata.paloaltonetworks.com/ngts/v1/certificates/imports/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Bearer <access_token>

Example response

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