POST Certificates/Retrieve/{vaultid}

Returns a certificate based on the Vault ID. The requested certificate returns the appropriate mime-type and content disposition to allow HTTP clients to properly save the file.

Requirements

  • Permissions:  The caller must have Read permission. If the private key is included in the download, the caller must also have 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 xxxxxx==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

Format

(Optional) The certificate format for the return data. Specify one of the following case sensitive values and use the exact spacing:

Format values are case-insensitive. Spaces and special characters in format names (such as #) can be omitted. For example, PKCS #12 and pkcs#12 are both accepted.

Format value File extension Description
Base64 .pem or .cer Certificate in PEM format. The file extension is .pem when the chain or private key is included, .cer otherwise. Mime-type: application/x-pem-file.
Base64 (PKCS #8) .pem Certificate in PEM format with the PKCS#8 encoded private key. Mime-type: application/x-pem-file.
DER .cer Raw binary certificate. Mime-type: application/x-x509-ca-cert.
JKS .jks Java Keystore format. Requires KeystorePassword. Mime-type: application/octet-stream.
PKCS #7 .p7b Certificate with optional chain in PKCS#7 format. Mime-type: application/x-pkcs7-certificates.
PKCS #12 .pfx Certificate in PKCS#12 format. Use with IncludePrivateKey and Password to include the private key. Mime-type: 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, 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.

The password must meet the Private Key Export rule for the certificate. This is the rule set on the certificate's policy folder. If the folder doesn't set a rule, the default Private Key Export rule is used. .

IMPORTANT  Spaces at the start or end are kept as part of the password.. To open the private key file later, you must type exactly the same password.

For more information, see Global password rules.

RootFirstOrder

(Optional)

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

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

VaultId

Required. The Secret Store location of the certificate. To get the VaultId for the current certificate version, call POST Config/Read. For a previous version of the certificate, call GET Certificates/{guid}/PreviousVersions. The Vault ID may be expressed with or without curly braces{}. For example, {376}.

Returns

Response description

Name

Description

HTTP 200

  • CertificateData: The certificate in the requested 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 Foundation includes the private key data.

    bash

    echo Q2VydGlmaWNhdGVEYXRh | base64 --decode

    OpenSSL

    echo Q2VydGlmaWNhdGVEYXRh | openssl enc -base64 -d

    Perl

    use MIME::Base64;

    print decode_base64("Q2VydGlmaWNhdGVEYXRh");

    PowerShell

    [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("Q2VydGlmaWNhdGVEYXRh"))

    Python

    import base64

    base64.b64decode("Q2VydGlmaWNhdGVEYXRh")

    where Q2VydGlmaWNhdGVEYXRh represents the CertificateData response value.

  • Filename: The suggested filename for the certificate data (in case the caller wants to save the certificate data in a file).

  • Format: The format for the certificate data that also matches the request Format.

    • Base64 or Base64 (PKCS #8) : application/x-pem-file
    • DER: application/x-x509-ca-cert
    • JKS: application/octet-stream
    • PKCS #7: application/x-pkcs7-certificates
    • PKCS #12: application/x-pkcs12

HTTP 400

For invalid requests, the method fails to return the certificate data and optional private key information. POST Certificates/Retrieve/{vaultid} returns a HTTP 400 BadRequest for missing parameters or one of the following errors:

  • Certificate Vault Id [vaultId] is not in the correct format.
  • Certificate with Vault Id [vaultId] does not exist or you do not have permissions to read it.
  • Failed to search for certificates with Vault Id [vaultId]; error: [SecretStore.Error]
  • Missing FriendlyName.
  • Missing Keystore Password.
  • Missing Password.
  • The data format is not provided.
  • The object with Vault Id [vaultId] is not certificate.

Example: Get the certificate and private key in the Base64 format

Request

POST https://tpp.venafi.example/vedsdk/certificates/retrieve/198
{
   "IncludePrivateKey":true,
   "Format":"Base64",
   "Password":"xxxxxx"
}

Response

HTTP/1.1 200 OK
{
   "CertificateData":"LS0tLS1CRU...==",
   "Filename":"test.example.com.pem",
   "Format":"Base64"
}