Certificate Macros

Certificate macros retrieve CSRs or certificates in PEM format from Certificate objects in the Policy tree.

Certificate Macro Examples and Descriptions

The following sections provide descriptions and examples of certificate macros. For more detailed examples and practical application of these macros, see Certificate, CSR, and CertificateChain macros.

The CSR macro command retrieves the PEM representation of a CSR that is associated with a Certificate object.

The Certificate object’s CSR must be stored in the Venafi Trust Protection Platform™ database in order for the CSR macro to retrieve it. If you are running Trust Protection Platform in Provisioning or Enrollment mode, Trust Protection Platform automatically generates the CSR during certificate lifecycle operations. You also have the option of manually uploading the CSR to the Certificate object. For more information, see Manually uploading the CSR.

The CSR macro has three arguments:

  • The Certificate object that holds the vault ID for the CSR.

  • (Optional) The attribute name under which the vault ID is stored.

    The default is "Csr Vault Id".

  • (Optional) This argument requires the second argument. It specifies the line width in characters for the PEM file. The default is 65 characters.

In practical application, you can use this macro to retrieve a CSR so it can be submitted to an offline or external CA. For details on this configuration, see Certificate, CSR, and CertificateChain macros.

Example Syntax

$CSR[$Event.Component$]$

$CSR[$Event.Component$, "Csr Vault Id", 76]$

The Certificate macro command retrieves the PEM representation of a certificate that is associated with a certificate object.

The certificate must be stored in Trust Protection Platform's database in order for the certificate macro to retrieve it. If the certificate has been discovered, or is under management, the certificate is stored in the database. If you are running Trust Protection Platform in Provisioning or Enrollment mode, Trust Protection Platform automatically retrieves the certificate from the CA when it renews the certificate.

The Certificate macro has three arguments:

  • The Certificate object that holds the vault ID for the certificate.

  • (Optional) The attribute name under which the vault ID is stored.

    The default is "Certificate Vault Id".

  • (Optional) This argument requires the second argument. It specifies the line width in characters for the PEM file. The default is 65 characters.

If you are running Venafi Trust Protection Platform in Enrollment mode, you can use this macro to retrieve a renewed certificate so it can be manually installed on the target system. For details on this configuration, see Certificate, CSR, and CertificateChain macros.

Example Syntax

$Certificate[$Event.Component$]$

$Certificate[$Event.Component$, "Certificate Vault Id", 65]$

The CertificateChain macro command retrieves the certificate’s root chain.

The certificate’s root chain must be stored in the Venafi Trust Protection Platform database or the local machine’s certificate store (CAPI) in order for the Certificate macro to retrieve it. The CertificateChain macro first checks the Trust Protection Platform database, then the CAPI store on the local machine.

If you are running Venafi Trust Protection Platform in Enrollment or Provisioning mode, Trust Protection Platform automatically retrieves the root chain from the CA when it renews the certificate (if the CA supports retrieving the chain). Trust Protection Platform also retrieves root chains when discovering local certificates via Agent discovery.

For more information on Agent certificate discovery, see Discovering Local Certificates Using Trust Protection Platform Agent in the Venafi Trust Protection Platform Certificate Management Guide.

If the root chain is not available in the Trust Protection Platform database or the local CAPI store, you may manually import the root chain into Trust Protection Platform. For more information, see Manually adding Root and Intermediate Root certificates of the Venafi Trust Protection Platform Certificate Management Guide.

The basic macro syntax is as follows:

$CertificateChain[$object_identification$,PEM|PKCS#7, line_width]$

The CertificateChain macro has three arguments:

  • The Certificate object that holds the vault ID for the root chain.

  • (Optional) The format for the root chain certificates (Either: PEM or PKCS#7).

  • (Optional) The line width in characters for the root certificate file. The default is 64 characters.

In practical application, you can use this macro to email the root chain to the administrator(s) of the applications where the certificate is installed so the administrator(s) can install the root chain on the target application(s) when they install the renewed certificate. For details on this configuration, see Certificate, CSR, and CertificateChain macros.

Example Syntax

$Event.Component$]$

$CertificateChain[$Event.Component$, PEM]$

$CertificateChain[$Event.Component$, PEM, 100]$

$CertificateChain[$Event.Component$, PKCS#7]$

$CertificateChain[$Event.Component$, PKCS#7, 72]$

$CertificateChain[$Event.Component$, 100]$

The CertificateField macro command returns the value of a specified certificate field. The macro retrieves the certificate's vault ID attribute—the default attribute—from the Certificate DN and returns the value for the specified field.

The basic syntax is:

$CERTIFICATEFIELD[ObjectDN, Field <,Attribute <, Separator>>]

The CertificateField macro has four arguments:

  • The certificate object that holds the vaultid for the certificate.
  • The certificate field you are interested in looking up.

  • (Conditional) The name of the attribute holding the certificate vaultid.

    This is the default attribute name and is NOT optional if you want to specify a separator value.

  • (Optional) A separator.

    The attribute can be multivalued using the default separator, which is a comma (,).

    The following shows the supported field values:

    • NOTBEFORE: Prints the date and time when the certificate becomes valid. The date/time is in local time of the server evaluating the macro and uses the server's culture settings for formatting.
    • NOTAFTER: Prints the date and time the certificate expires. The date/time is in the local time of the server evaluating the macro and uses the server's culture settings for formatting.
    • VALIDFROM: Same as NOTBEFORE.
    • VALIDTO: Same as NOTAFTER.
    • SERIAL: Serial number of the certificate.
    • SUBJECT: Full subject of the certificate.
    • CN: CN of the certificate's subject.
    • O: O of the certificate's subject.
    • OU: OU of the certificate's subject.
    • L: L of the certificate's subject.
    • ST: ST of the of the certificate's subject.
    • C: C of the certificate's subject
    • THUMBPRINT: The certificate thumbprint.
    • ISSUER: Full issuer of the certificate.
    • ISSUER_CN: CN of the certificate's issuer.
    • ISSUER_O: O of the certificate's issuer.
    • ISSUER_OU: OU of the certificate's issuer.
    • ISSUER_L: L of the certificate's issuer.
    • ISSUER_ST: ST of the certificate's issuer.
    • ISSUER_C: C of the certificate's issuer.
    • ALGORITHM: Hash method and algorithm used for signing the certificate.
    • KEYSIZE: Size of the certificate's key (in bits).
    • SAN: List of all Subject Alt Name values on the certificate, separated by Separator.

Example Syntax

$CERTIFICATEFIELD[\VED\Policy\my cert,ValidTo]$

Only ObjectDN and Field are mandatory. Attribute and separator are optional. However, if Separator is to be set, Attribute must be provided, as well.