12.3. Customizing Notification Messages
The email notifications are constructed using a template for each type of message. This allows messages to be informative, easily reproducible, and easily customizable. The CA uses templates for its notification messages. Separate templates exist for HTML and plain text messages.
12.3.1. Customizing CA Notification Messages
Each type of CA notification message has an HTML template and a plain text template associated with it. Messages are constructed from text, tokens, and, for the HTML templates, HTML markup. Tokens are variables, identified by a dollar sign (
$), in the message that are replaced by the current value when the message is constructed. See Table 12.3, “Notification Variables” for a list of available tokens.
The contents of any message type can be modified by changing the text and tokens in the message template. The appearance of the HTML messages can be changed by modifying the HTML commands in the HTML message template.
The default text version of the certificate-issuance-notification message is as follows:
Your certificate request has been processed successfully. SubjectDN= $SubjectDN IssuerDN= $IssuerDN notAfter= $NotAfter notBefore= $NotBefore Serial Number= 0x$HexSerialNumber To get your certificate, please follow this URL: https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial& serialNumber=$SerialNumber Please contact your admin if there is any problem. And, of course, this is just a \$SAMPLE\$ email notification form.
This template can be customized as desired, by rearranging, adding, or removing tokens and text, as shown:
THE EXAMPLE COMPANY CERTIFICATE ISSUANCE CENTER Your certificate has been issued! You can pick up your new certificate at the following website: https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial& serialNumber=$SerialNumber This certificate has been issued with the following information: Serial Number= 0x$HexSerialNumber Name of Certificate Holder = $SubjectDN Name of Issuer = $IssuerDN Certificate Expiration Date = $NotAfter Certificate Validity Date = $NotBefore Contact IT by calling X1234, or going to the IT website http://IT if you have any problems.
Notification message templates are located in the
/var/lib/pki/instance_name/ca/emails directory.
The name and location of these messages can be changed; make the appropriate changes when configuring the notification. All template names can be changed except for the certificate rejected templates; these names must remain the same. The templates associated with certificate issuance and certificate rejection must be located in the same directory and must use the same extension.
Table 12.1, “Notification Templates” lists the default template files provided for creating notification messages. Table 12.2, “Job Notification Email Templates” lists the default template files provided for creating job summary messages.
| Filename | Description |
|---|---|
| certIssued_CA | Template for plain text notification emails to end entities when certificates are issued. |
| certIssued_CA.html | Template for HTML-based notification emails to end entities when certificates are issued. |
| certRequestRejected.html | Template for HTML-based notification emails to end entities when certificate requests are rejected. |
| certRequestRevoked_CA | Template for plain text notification emails to end entities when a certificate is revoked. |
| certRequestRevoked_CA.html | Template for HTML-based notification emails to end entities when a certificate is revoked. |
| reqInQueue_CA | Template for plain text notification emails to agents when a request enters the queue. |
| reqInQueue_CA.html | Template for HTML-based notification emails to agents when a request enters the queue. |
| Filename | Description |
|---|---|
| rnJob1.txt | Template for formulating the message content sent to end entities to inform them that their certificates are about to expire and that the certificates should be renewed or replaced before they expire. |
| rnJob1Summary.txt |
Template for constructing the summary report to be sent to agents and administrators. Uses the
rnJob1Item.txt template to format items in the message.
|
| rnJob1Item.txt | Template for formatting the items included in the summary report. |
| riq1Item.html | Template for formatting the items included in the summary table, which is constructed using the riq1Summary.html template. |
| riq1Summary.html |
Template for formulating the report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager.
|
| publishCerts |
Template for the report or table that summarizes the certificates to be published to the directory. Uses the
publishCertsItem.html template to format the items in the table.
|
| publishCertsItem.html |
Template for formatting the items included in the summary table.
|
| ExpiredUnpublishJob |
Template for the report or table that summarizes removal of expired certificates from the directory. Uses the
ExpiredUnpublishJobItem template to format the items in the table.
|
| ExpiredUnpublishJobItem |
Template for formatting the items included in the summary table.
|
Table 12.3, “Notification Variables” lists and defines the variables that can be used in the notification message templates.
| Token | Description |
|---|---|
| $CertType |
Specifies the type of certificate; these can be any of the following:
|
| $ExecutionTime | Gives the time the job was run. |
| $HexSerialNumber | Gives the serial number of the certificate that was issued in hexadecimal format. |
| $HttpHost | Gives the fully qualified host name of the Certificate Manager to which end entities should connect to retrieve their certificates. |
| $HttpPort | Gives the Certificate Manager's end-entities (non-TLS) port number. |
| $InstanceID |
Gives the ID of the subsystem that sent the notification.
|
| $IssuerDN | Gives the DN of the CA that issued the certificate. |
| $NotAfter | Gives the end date of the validity period. |
| $NotBefore | Gives the beginning date of the validity period. |
| $RecipientEmail | Gives the email address of the recipient. |
| $RequestId | Gives the request ID. |
| $RequestorEmail | Gives the email address of the requester. |
| $RequestType | Gives the type of request that was made. |
| $RevocationDate | Gives the date the certificate was revoked. |
| $SenderEmail | Gives the email address of the sender; this is the same as the one specified in the Sender's E-mail Address field in the notification configuration. |
| $SerialNumber | Gives the serial number of the certificate that has been issued; the serial number is displayed as a hexadecimal value in the resulting message. |
| $Status | Gives the request status. |
| $SubjectDN | Gives the DN of the certificate subject. |
| $SummaryItemList | Lists the items in the summary notification. Each item corresponds to a certificate the job detects for renewal or removal from the publishing directory. |
| $SummaryTotalFailure | Gives the total number of items in the summary report that failed. |
| $SummaryTotalNum | Gives the total number of certificate requests that are pending in the queue or the total number of certificates to be renewed or removed from the directory in the summary report. |
| $SummaryTotalSuccess | Shows how many of the total number of items in the summary report succeeded. |
