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 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

Format

(Optional) The certificate format:

  • 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.

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

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 Platform 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

      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
  • 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 4MyGeneratedBearerTknz== 
{
   "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 4MyGeneratedBearerTknz==   
{
   "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
}