POST Certificates/Renew

Requests immediate renewal for an existing certificate. A renewable certificate cannot be currently processing, in error, or contain a 'Monitoring' Management Type. Optionally, this API call can renew a previously disabled certificate. The caller must have Write permission to the Certificate object that requires renewal.

Requirements

  • Permissions: 
    • The caller must have Write permission to the Certificate object that requires renewal.
    • Private Key Read permission 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:

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.

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.

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.

IncludeChain

(Optional) When the Format is Base64, 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.

FriendlyName

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

RootFirstOrder

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.

KeystorePassword

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

CertificateDN

The Distinguished Name (DN) of the certificate to renew.

PKCS10

(Optional) The PKCS#10 Certificate Signing Request (CSR) to use for the renewal. Omit escape characters such as \n or \r\n.

Reenable

(Optional) The action to control a previously disabled certificate:

  • false: Default. Do not renew a previously disabled certificate.
  • true: Clear the Disabled attribute, reenable, and then renew the certificate (in this request). Reuse the same CertificateDN, that is also known as a Certificate object.

WorkToDoTimeout

(Optional) The maximum wait time for the CA to renew a certificate.

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

For valid requests, Certificates/Renew returns a HTTP 200 and a message body that varies depending on WorkToDoTimeout:

  • CertificateData: Available for WorkToDoTimeout.
    • If certificate creation completes before a timeout is reached (either specified or global), the response includes the certificate.
  • CertificateDN: The Trust Protection Foundation DN of the newly created certificate object, if it was successfully created.
  • Filename: Available for WorkToDoTimeout. The suggested filename for the certificate data (in case the caller wants to save the certificate data in a file).
  • Format: Available for WorkToDoTimeout. A reminder of the intended Format that is imbedded in the CertificateData.
    • Base64or Base64 (PKCS #8) : application/x-pem-file

      The CertificateData response value is the certificate data in the requested format, encoded as a Base64 string for JSON transport. To get a usable certificate file, decode the Base64 data and save it with the appropriate file extension for the format you requested (for example, .pem for Base64, .pfx for PKCS #12, .p7b for PKCS #7). 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. Replace the output file extension to match the format you requested.

    • DER: application/x-x509-ca-cert
    • JKS: application/octet-stream
    • PKCS #7: application/x-pkcs7-certificates
    • PKCS #12: application/x-pkcs12
  • Success: The result of this API call:
    • true:Renewal was successful.

HTTP 202

The certificate request was valid however, processing has yet to complete. Upon completion, call POST Certificates/Retrieve to get the certificate.

  • Error: When the certificate renewal is pending.
  • Success: The result of this API call:
    • false: Renewal is still pending due to an Error.

HTTP 400
  • Error: When the certificate renewal is unsuccessful:
    • CSR errors:
      • Failed to store csr; Error: " + [SecretStore.Result].
      • Failed to write key bit strength; Error: " + [config.Result].
      • Failed to write manual csr; Error: [config.Result].
      • Failed to write elliptic curve; Error: " + [config.Result].
      • This CSR appears to reuse a private key. Private key reuse has not been allowed.
    • Compliance or compatibility issues with policy settings:
      • City error. City value [L] violates policy city settings.
      • Common name error. Certificate common name [CN] violates whitelist domain policy settings.
      • Common name error. Certificate common name contains a wildcard symbol that violates policy settings.
      • Country error. Country value [Country] violates policy country settings.
      • DNS SAN error. Subject alternative name DNS [DNS SAN] contains a wildcard symbol that violates policy settings.
      • DNS SAN error. Subject alternative name DNS violates policy settings.
      • Elliptic curve error. Elliptic curve value violates policy settings.
      • Email SAN error. Subject alternative name Email violates policy settings.
      • IP Address SAN error. Subject alternative name IP violates policy settings.
      • Key algorithm error. Key algorithm violates policy settings.
      • Key size error. Key size violates policy settings.
      • Organization error. Organization value [O] violates policy organization settings.
      • Organization unit error. Organization unit value [OU] is missing from the organization unit list.
      • Organization unit error. Organization unit value [Wrong OU] violates policy organization unit settings.
      • State error. State value [S] violates policy state settings.
      • UPN SAN error. Subject alternative name UPN violates policy settings.
      • URI SAN error. Subject alternative name URI violates policy settings.

      • SANs error. Subject alternative names [SAN names] violate policy settings.

    • Renew errors:
      • Certificate [cert_dn] does not exist.
      • Certificate [ CertificateDN] is already being processed.
      • Certificate [cert_dn] is in an error state and cannot be renewed.
      • Certificate [ CertificateDN] is only enrolled for monitoring.
      • Certificate renew error. Certificate is disabled.
      • Certificate renew error. Failed to write Manual CSR; Error: [Error].
      • Certificate renew mismatch. Certificate [ CertificateDN], which originated from a User Provided CSR, requires a PKSC#10.
      • Certificate renewal failed. Certificate [ CertificateDN] has an invalid Management type: [Management type].
      • Could not store renewal request on certificate [ CertificateDN] + [Error].
      • Failed to re-enable the certificate. Error: [Error].
      • Failed to store csr; Error: InvalidParms.
      • Missing CertificateDN.
      • PKCS#10 data not in base64 format; + [Message].
      • PKCS#10 data required. Policy [ PolicyDN]\ is locked to a User Provided CSR.
      • Queued for renewal.
      • Waiting for new CSR.
  • Success: False

Example 1: Renew certificate for a DN

Request for Example 1

POST https://tpp.venafi.example/vedsdk/Certificates/Renew
Authorization:Bearer xxxxxx== 
{
   "CertificateDN":"\\VED\\Policy\\Marketing\\Zoey",
   "WorkToDoTimeout": 60

}

Response for Example 1

HTTP/1.1 200 OK
{
   "CertificateData":"LS0tLS1CR...0F",
   "Filename":"test56.domaine.fr.cer",
   "Format":"Base64",
   "Success":true
}

Response when system is busy 

HTTP/1.1 202 Accepted
{
    "Error": "Certificate processing took longer than WorkToDoTimeout. Call certificates/retrieve...",
    "Success": false
}

Example 2: Renew with certificate

Request for Example 2

POST https://tpp.venafi.example/vedsdk/Certificates/Renew
Authorization:Bearer xxxxxx==   
{
   "CertificateDN": "\\VED\\Policy\\Certificates\\test56.domaine.fr",
   "WorkToDoTimeout": 120,
   "CertificateData": "LS0tLS1CRU...NCg=="
}

Response for Example 2

HTTP/1.1 200 OK
{
   "CertificateData": "LS0tLS1CRU...NCg=="
   "Filename": "test56.domaine.fr.cer",
   "Format": "Base64",
   "Success": true
}