POST Certificates/Retrieve

Returns the available certificate data and optional private key information for an enrolled certificate. After this call completes, you can use another utility to convert it to the necessary Format. If you want to download the certificate, call GET Certificates/Retrieve instead.

Requirements

  • Permissions:  The caller must have Read permission and Private Key Read permission to the Certificate object.
  • Token scope:  Certificate:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

CertificateDN

The Trust Protection Platform Distinguished Name (DN) of the certificate.

Format

The format that you will use to manually convert the CertificateData result. Specify one of the following case sensitive values and use the exact spacing:

  • Base64: Show the certificate in the traditional PEM format. The mime-type is application/x-pem-file.
  • Base64 (PKCS #8): Show the certificate in the PEM format and include the PKCS#8 encoded private key. The mime-type is application/x-pem-file.
  • DER: Show the raw certificate. Use IncludePrivateKey and set the password. The mime-type is application/x-x509-ca-cert.
  • JKS: Show the certificate in the Java Keystore (JKS) format. The mime-type is application/octet-stream.
  • PKCS #7: Show the certificate with optional chain in the PKCS#12 format. The mime-type is application/x-pkcs7-certificates.
  • PKCS #12: Show the certificate in the PKCS#12 format. Use IncludePrivateKey and set the password. The mime-type is application/x-pkcs12.

FriendlyName

The label or alias to use for Base64, JKS, or PKCS #12 formats. Required for the JKS format.

IncludeChain (Optional)

When the Format is Base64, Base64 (PKCS #8), PKCS #7, PKCS #12, or JKS, you can include the parent or root chain in the return data.

  • true: Include the root chain. Use RootFirstOrder to set the order. The data appears after any private key information.
  • false: Omit the root chain.

IncludePrivateKey (Optional)

When the Format is Base64 (PKCS #8), PKCS #12, or JKS, you can specify whether to return the private key:

  • false: No private key.
  • true: Default. Create a private key based on KeystorePassword.

KeystorePassword

 If the Format is JKS, you must set this value. Use the same requirements as required for Password.

Password

If the IncludePrivateKey value is true, this value must be set.

Create a strong password by using a

  • minimum of 12 characters
  • combination of at least three of the following:
    • one or more lowercase letters
    • one or more uppercase letters
    • one or more numbers
    • one or more special characters

RootFirstOrder

(Optional)

In the REST response, the order of the certificate chain of trust. Use when IncludeChain is true.

  • true: Set the root certificate first, followed by intermediate certificates, and finally the end entity certificate.
  • false: Default. Set the end entity first, followed by intermediate certificates, and finally the root certificate.

WorkToDoTimeout

(Optional) The maximum wait time for certificate retrieval.

Overrides the Platforms tree setting for the Certificate API ToDo Timeout setting. The maximum number of seconds to wait for the ToDo operation to complete. The default is zero seconds with a maximum value of 120 seconds. For example:WorkToDoTimeout: 60. For more information, see Certificates API configuration.

Returns

Response description

Name

Description

HTTP 200

If the certificate is currently in enrollment, provisioning, or in error, the response contains only the current Status and processing Stage of the Certificate object.

  • CertificateData: The certificate in the Base64 with the capability for you to convert it to the specified Format. The certificate data is only available after certificate enrollment completes. If the caller supplied private key parameters and a private key is present in the Secret Store, Trust Protection Platform includes the private key data.
  • Filename: The suggested filename for the certificate data (in case the caller wants to save the certificate data in a file).
  • Format: A reminder of the intended Format that is imbedded in the CertificateData.
    • Base64or Base64 (PKCS #8) : application/x-pem-file

      To decode, print, or cast Base64 data, use a library method or utility. Examples:

      Bash

      echo Q2VydGlmaWNhdGVEYXRh | base64 --decode -o bash.pfx

      OpenSSL

      echo Q2VydGlmaWNhdGVEYXRh | openssl enc -base64 -d -out OpenSSL.pfx

      Perl

      use MIME::Base64;

      print decode_base64("Q2VydGlmaWNhdGVEYXRh");

      PowerShell

      [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("Q2VydGlmaWNhdGVEYXRh")) >> C:\myfolder.RS-SAMPLE\Desktop\PowerShell.pfx

      Python

      import base64

      base64.b64decode("Q2VydGlmaWNhdGVEYXRh")

      where Q2VydGlmaWNhdGVEYXRh is the CertificateData response value.

    • DER: application/x-x509-ca-cert
    • JKS: application/octet-stream
    • PKCS #7: application/x-pkcs7-certificates
    • PKCS #12: application/x-pkcs12

HTTP 202

When the certificate is not ready, this API call returns:

  • Stage -1 Status: Queued for renewal.
  • Stage: 0, Status: Not yet available.

HTTP 400

Returns an Error message for bad parameters, data, or syntax:

  • Certificate does not exist.

  • Failed to read certificate [CertificateDN] user permissions.

  • Permissions error. You do not have sufficient rights to retrieve the certificate [CertificateDN].

  • Permissions error. You do not have sufficient rights to retrieve the certificate [CertificateDN] private key.

  • Failed to look up private key. Error: Failed to look up private key vault ID. This is the API result you will receive when attempting to download a certificate and private key if the certificate was generated from a user-provided CSR and the private key is not stored in Venafi.

Example: Get the certificate

Request

POST https://tpp.venafi.example/vedsdk/certificates/Retrieve
Authorization:Bearer 4MyGeneratedBearerTknz==
{  
   "CertificateDN":"\\VED\\Policy\\retrieve-me.venafi.example",
   "Format":"Base64",
   "IncludeChain":true,
   "RootFirstOrder":true
}

Response

HTTP/1.1 200 OK
{  
   "CertificateData":"c3ViamVjdD1DTj1WZW5hZmkgRXhhbXBsZSBSb290I...",
   "Filename":"retrieve-me.venafi.example.pem",
   "Format":"Base64"
}