Certificate, CSR, and CertificateChain macros

The following macros outline how the Certificate, CSR, and CertificateChain macros may be used to retrieve certificates and CSRs.

Certificate and CSR Macros
Macro	Description
$CSR[$Event.Component$, "Csr Vault Id", 76]$	The $CSR$ macro returns the PEM representation of the CSR for the Certificate object designated by the $Event.Component$ macro. In practical application, you can use this macro to email a CSR for submission to an offline or external CA. To email a CSR for submission to an offline or external CA Create an SMTP Channel object for CSR retrieval notifications. Configure the channel recipient as the person responsible for manually submitting CSRs to the offline or external CA. You can specify a macro in the Recipient field. For example, to send the notification to the Certificate contact, type: $ContactEMail[$Event.Component$]$ Include the following macro in the Message Body field: $CSR[$Event.Component$, "Csr Vault Id", 76]$ Whenever a notification is routed through this channel, CyberArk Trust Protection Foundation executes the listed macro. If the $Event.Component$ is a Certificate object, CyberArk Trust Protection Foundation retrieves the designated Certificate’s CSR and pastes it in the message body in PEM format. using a 76-character width. IMPORTANT The Certificate object’s CSR must be stored in the CyberArk Trust Protection Foundation database in order for the CSR macro to retrieve it. If you are running CyberArk Trust Protection Foundation in Provisioning or Enrollment mode, Trust Protection Foundation 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 in the CyberArk Trust Protection Foundation Certificate Management Guide.
	Create a Notification Rule that triggers on event "X509Certificate - Create CSR Success." This event triggers whenever CyberArk Trust Protection Foundation successfully creates a CSR for a renewing certificate. The Notification Rule configuration appears as follows: Configure the Notification’s Target Channel as the SMTP Channel object you created in To email a CSR for submission to an offline or external CA.
$Certificate[$Event.Component$, "Certificate Vault Id", 65]$	The $Certificate$ macro returns the PEM representation of the certificate designated by the $Event.Component$ macro. If you are running CyberArk Trust Protection Foundation in Enrollment mode, this macro can be used to obtain a certificate that Trust Protection Foundation retrieved from the CA so it can be manually installed on the target device. NOTE At the Enrollment level of certificate management, CyberArk Trust Protection Foundation can automatically generate and submit CSRs to Certificate Authorities using the parameters defined in designated CA Template objects. After the CA signs the certificate, CyberArk Trust Protection Foundation can also retrieve the certificate from the CA. However, at the Enrollment level, Trust Protection Foundation does not install the certificate. The administrator must download the certificate from Trust Protection Foundation and install it on the target systems. To automatically download a renewed certificate and email it to the administrator responsible for installing it on the target system: Create an SMTP Channel object for certificate retrieval notifications. Configure the channel recipient as the person responsible for manually installing the certificate on the application. You can specify a macro in the Recipient field. For example, to send the notification to the owner of the Applications that the certificate is installed, type: $ContactEMail[$Config[$Event.Component$,"Consumers",",\"]$]$ Include the following macro in the Message Body field: $Certificate[$Event.Component$, "Certificate Vault Id", 65]$ Whenever a notification is routed through this channel, CyberArk Trust Protection Foundation executes the listed macro. If the $Event.Component$ is a Certificate object, CyberArk Trust Protection Foundation retrieves the certificate and pastes it in the message body in PEM format. IMPORTANT The certificate must be stored in the CyberArk Trust Protection Foundation database in order for the Certificate macro to retrieve it. If you are running CyberArk Trust Protection Foundation in Enrollment or Provisioning mode, Trust Protection Foundation automatically retrieves the certificate from the CA when it renews the certificate. Create a Notification Rule that triggers on event "Certificate Manager - Self-Hosted - Certificate Renewal Complete." This event triggers whenever CyberArk Trust Protection Foundation successfully retrieves a renewed certificate from a CA. The Notification Rule configuration appears as follows: Configure the Notification’s Target Channel as the SMTP Channel object you created in To email a CSR for submission to an offline or external CA.
$CertificateChain[$Event.Component$, PEM, 100]$	The $CertificateChain$ macro returns the PEM representation of the root chain for the certificate designated by the $Event.Component$ macro. If you are running CyberArk Trust Protection Foundation in Enrollment mode, this macro can be used to obtain the root chain for a certificate that Trust Protection Foundation retrieved from the CA so it can be manually installed on the target device. NOTE At the Enrollment level of certificate management, CyberArk Trust Protection Foundation does not install the certificate or root chain. The administrator must download the certificate and root chain from Trust Protection Foundation and install it on the target systems. To automatically download a renewed certificate’s root chain and email it to the administrator responsible for installing it on the target system: Create an SMTP Channel object for certificate renewal notifications. Configure the channel recipient as the person responsible for manually installing the certificate on the application. You can specify a macro in the Recipient field. For example, to send the notification to the owner of the Applications that the certificate is installed, type: $ContactEMail[$Config[$Event.Component$,"Consumers",",\"]$]$ Include the following macro in the Message Body field: $CertificateChain[$Event.Component$, PEM, 100]$ NOTE You can also specify PKCS#7 instead of PEM, if you prefer. You can also indicate any line width. Whenever a notification is routed through this channel, CyberArk Trust Protection Foundation executes the listed macro. If the $Event.Component$ is a Certificate object, CyberArk Trust Protection Foundation retrieves the certificate’s root chain and pastes it in the message body in PEM format that is 100 characters wide. IMPORTANT The certificate’s root chain must be stored in the CyberArk Trust Protection Foundation 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 Foundation database, then the CAPI store on the local machine. Create a Notification Rule that triggers on one of the following events: "Certificate Manager - Self-Hosted - Local Enrollment Processing Finished" "Certificate Manager - Self-Hosted - Processing Local" "Certificate Manager - Self-Hosted - Remote Enrollment Processing Finished" "Certificate Manager - Self-Hosted - Processing Remote" The "Local" events trigger when the private key and CSR are locally generated on the Trust Protection Foundation server. The "Remote" events trigger when the private key and CSR are generated on the server where the certificate is installed (the certificate consumer application). The private key and CSR are generated on the certificate’s consumer application if the Generate Key/CSR on Application option is enabled in the Certificate object. For more information, see Managing certificate configuration.
	The Notification Rule configuration appears as follows: Configure the Notification’s Target Channel as the SMTP Channel object you created in step To email a CSR for submission to an offline or external CA.