Customizing e-mail notifications sent to users

You can optionally notify a user by sending an e-mail message when:

A certificate request is rejected
A certificate is ready for retrieval
A certificate is about to expire (unless it has already been renewed or revoked).
A certificate has been automatically renewed.
Requests are pending for the user's approval, when the user is the PKI administrator.

In addition, when a user requests that PKI Services recover one or more certificates for which PKI Services created the keys, PKI Services sends that user an e-mail message listing the possible certificates to be recovered.

On the days specified by the MaintRunDays parameter in the pkiserv.conf file, the PKI Services daily maintenance task checks the issued certificate list (ICL) for expiring certificates. (The ExpireWarningTime parameter (see the CertPolicy section in Table 1) determines at what point before the certificate expires that it is considered to be an expiring certificate.) When PKI Services finds an expiring certificate, it takes one of the following actions:

If automatic renewal of certificates is in effect, PKI Services renews the certificate and sends it to the client.
If automatic renewal of certificates is not in effect, PKI Services sends an expiration warning message to the client (unless the certificate has already been revoked). Regardless of whether sending the expiration warning message is successful, PKI Services makes only one attempt to send a notification message. If the e-mail address is incorrect or the user renews the certificate and retrieves it before the expiration message is sent, no expiration messages is sent.

You can set the AdminNotifyNewn keyword in the CertPolicy section of the configuration file to specify one or more e-mail addresses of PKI administrators to be notified immediately whenever there is a request pending for approval. The notification is sent only once, when the request is created. You can also set the AdminNotifyRemindern keyword to specify one or more e-mail addresses of PKI administrators to be reminded once a day of any requests pending for approval. An administrator receives a daily reminder of a pending request until the request is processed. To receive both the immediate notifications and the daily reminders, an administrator's e-mail must be specified on both the AdminNotifyNew and AdminNotifyReminder keywords.

If you are not sending e-mail notifications, see Step 6.b for directions.

If you are sending e-mail notifications, you need to do the following things:

Have copies of the forms in the runtime directory. (For information about copying the message forms to the runtime directory, see Step 3.
Customize the forms. (For details, see Steps for customizing e-mail notification forms.)
For notifications that a request has been rejected, that a certificate is ready for retrieval, that a certificate is about to expire, and that a certificate has been renewed automatically, include the NotifyEmail field on certificate requests. This field is already included in the pkiserv.tmpl certificate template file. If you are not sending e-mail notifications, you need to delete the NotifyEmail lines in the pkiserv.tmpl file; for details, see Step 6.b.)
For more information about the NotifyEmail field, see Table 1. For information about fields on request forms, see Table 1.

The following examples (of notices you can send to users) are in the sample directory:

Figure 1. Sample of readymsg.form

From:dime-o-cert PKI
Subject:Certificate Ready For Pick Up

Attention - Please do not reply to this message as it was automatically sent by a service machine.

Dear %%requestor%%,

Thank you for choosing dime-o-cert PKI. The certificate you requested
for subject %%dn%% is now ready for pickup.

Please visit:
(edit the following link if using the REXX CGI Web Application)
https://www.dimeocert.com/Customers/ssl-cgi-bin/caretrieve.rexx?%%quicklink%%
(edit the following link if using the JSP WebSphere Application)
https://www.dimeocert.com:9080/PKIServ_Web/Customers/certretrieve.jsp?%%quicklink%%
to retrieve your certificate.

If that link does not work, try to go to
(edit the following link if using the REXX CGI Web Application)
http://www.dimeocert.com/Customers/public-cgi/camain.rexx
(edit the following link if using the JSP WebSphere Application)
http://www.dimeocert.com:9080/PKIServ_Web/Customers/pkimain.jsp
And enter the transaction ID listed below: 
%%transactionid%%

You will need to input your passphrase that you entered when you submitted the request.

Figure 2. Sample of rejectmsg.form

From:dime-o-cert PKI
Subject:Certificate Request Rejected

Attention - Please do not reply to this message as it was automatically sent by a service machine.

Dear %%requestor%%,

Thank you for choosing dime-o-cert PKI. We are sorry to inform you that
your certificate request for subject %%dn%% has been rejected with the following explanation [if any]:
%%rejectreason%%.
Please contact the PKI Services administrator at 1-800-xxx-xxxx.
You will need the transaction ID listed below.

%%transactionid%%

Figure 3. Sample of expiringmsg.form

From:dime-o-cert PKI
Subject:Certificate Expiration

Attention - Please do not reply to this message as it was automatically sent by a service machine.

Dear %%requestor%%,

Thank you for choosing dime-o-cert PKI. The certificate your requested for
subject %%dn%% expires at %%notafter%% local time. If you wish to renew
your certificate, please visit:
(edit the following link if using the REXX CGI Web Application)
http://www.dimeocert.com/Customers/public-cgi/camain.rexx
(edit the following link if using the JSP WebSphere Application)
http://www.dimeocert.com:9080/PKIServ_Web/Customers/pkimain.jsp 
If this is a browser certificate, you must use the same workstation and browser that
you used when you requested the original certificate. If this is a server
certificate, you will have to submit a #10 certificate request.

Figure 4. Sample of renewcertmsg.form

From:dime-o-cert PKI
Subject:Certificate Renewed

Attention - Please do not reply to this message as it was automatically
sent by a service machine.

Dear %%requestor%%,

Your certificate with subject name %%dn%% has been automatically
renewed. Here is your new certificate in Base64 encoded format:
%%printcert%%

If your original certificate is installed in Internet Explorer,
click on this link to install the above new certificate:
(edit the following link if using the REXX CGI Web Application)
https://www.dimeocert.com/Customers/ssl-cgi-bin/installcert.rexx

(edit the following link if using the JSP WebSphere Application)
 https://www.dimeocert.com:9443/PKIServ_Web/Customers/installcert.jsp

Note: The port number 9443 should match your secure port address (_PKISERV_SECURED_PORT) in the web.xml file.

Figure 5. Sample of pendingmsg.form

From:dime-o-cert PKI
Subject:Request(s) pending for approval

Dear %%cadomain%% administrator,
The following request(s) is/are waiting for your approval:
%%pendreqlist%%

Figure 6. Sample of recoverymsg.form

From:dime-o-cert PKI
	Subject:Certificate Recovery
	
Attention - Please do not reply to this message as it was automatically sent by
 a service machine.
	
Dear %%requestor%%,
	
Here is a list of certificate(s) that satisfy your searching criteria for recovery:
%%recoverylist%%

Please choose the certificate you want and visit the corresponding link to 
retrieve it (you can identify the certificate by the serial number from the 
part of the link between ‘?’ and ‘&’)
 
(edit the following link if using the REXX CGI Web Application)
https://www.dimeocert.com/Customers/ssl-cgi-bin/caretrieve.rexx?%%recoverylink%%
(edit the following link if using the JSP WebSphere Application)
https://www.dimeocert.com:9080/PKIServ_Web/Customers/certrecover.jsp?%%recoverylink%%

You will need to input your pass phrase that you entered when you submitted the 
request.

Note:

PKI Services automatically provides the To: value in the forms. You can include From: or Subject: or both at the top of the file.
You must have a blank line between the Subject and the body of the form.

The following table summarizes the variables you can use in the forms when you customize them. At runtime, PKI Services replaces these with their actual values.

Table 1. Descriptions of variables for forms
Variable	Description
`%%cadomain%%`	The CA domain that this message comes from. It is truncated if longer than 8 characters. (This variable is valid only in the pending requests form, `pendingmsg.form`. It is ignored in the other forms.)
`%%dn%%`	The subject's distinguished name. (This variable is valid in all the forms except the pending requests form, `pendingmsg.form`.)
`%%printcert%%`	A renewed certificate in Base64-encoded format. (This variable is valid only in the renewed certificate form, `renewcertmsg.form`. It is ignored in the other forms.)
`%%notafter%%`	The certificate expiration date and time in local time in the format `YYYY/MM/DD HH:MM:SS`. (This variable is valid only in the `expiring.form`. It is ignored in the other forms.)
`%%pendreqlist%%`	A list of pending approval requests (or a single request). Each request contains the transaction ID followed by the corresponding requestor. Each request should be on a line of its own. (This variable is valid only in the pending message form, `pendingmsg.form`. It is ignored in the other forms.)
`%%quicklink%%`	A link to a certificate that is ready for pick up. It contains the transaction ID, the "&" character, and the string of the template name or alias, with escaped characters. The following string (broken into two lines so that it fits in the column) is an example: `TransactionId=1j86b0wokkoQ2SHV%2B%2B%2B%2B %2B%2B%2B%2B&Template=PKI+Browser+Certificate` The template name or alias is located from the appldata field of the certificate from the issued certificate list (ICL). The appldata field corresponds to the value of the NICKNAME directive in the template. If PKI Services cannot determine the template name or alias, the `%%quicklink%%` variable is an empty string, and a warning level message IKYC056I is logged.
`%%recoverylink%%`	Part of the link to a certificate that can be recovered. It contains the serial number, the "&" character, and the KeyId of the recovery certificate. This part of the link is at the end of the line, appended to the URL link. The entire line is repeated for each entry in the list of certificates that can be recovered.
`%%recoverylist%%`	The list of certificates that meet the criteria for recovery; that is, the e-mail address for the certificate matches the e-mail address of the user requesting the recovery of the certificate, the password used for the original certificate request matches the password provided by the user, and PKI Services created the keys for the certificate. The URL for each recovered certificate is on a line by itself.
`%%rejectreason%%`	The reason for the rejection of a certificate request. (This variable is valid for the reject form only.)
`%%requestor%%`	The requestor of the certificate.
`%%transactionid%%`	The transaction ID (CertId) returned. (This variable is valid for the ready and reject forms only. It is ignored in the other forms.)

Table 2 summarizes which substitution variables are supported by which forms:

Table 2. Summary of substitution variables in forms
Substitution variable	readymsg	rejectmsg	expiringmsg	pendingmsg	renewcertmsg	recoverymsg
`%%cadomain%%`	(ignored)	(ignored)	(ignored)	X	(ignored)	(ignored)
`%%dn%%`	X	X	X	(ignored)	X	(ignored)
`%%printcert%%`	(ignored)	(ignored)	(ignored)	(ignored)	X	(ignored)
`%%notafter%%`	(ignored)	(ignored)	X	(ignored)	(ignored)	(ignored)
`%%pendreqlist%%`	(ignored)	(ignored)	(ignored)	X	(ignored)	(ignored)
`%%quicklink%%`	X	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)
`%%recoverylink%%`	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	X
`%%recoverylist%%`	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	X
`%%rejectreason%%`	(ignored)	X	(ignored)	(ignored)	(ignored)	(ignored)
`%%requestor%%`	X	X	X	(ignored)	X	X
`%%transactionid%%`	X	X	(ignored)	(ignored)	(ignored)	(ignored)