Customizing email notifications sent to users

You can optionally notify a user by sending an email message when:

A certificate request is rejected
A certificate is ready for retrieval
A certificate is about to expire (unless it is already renewed or revoked).
A certificate is 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 email message listing the possible certificates to be recovered.

On the days that are 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 is already revoked). Regardless of whether sending the expiration warning message is successful, PKI Services makes only one attempt to send a notification message. If the email address is incorrect or the user renews the certificate and retrieves it before the expiration message is sent, no expiration messages are sent.

You can set the AdminNotifyNewn keyword in the CertPolicy section of the configuration file to specify one or more email 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 email 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 email must be specified on both the AdminNotifyNew and AdminNotifyReminder keywords.

If you are not sending email notifications, see Step 6.b for directions.

If you are sending email 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 email notification forms.)
For notifications that a request is rejected, that a certificate is ready for retrieval, that a certificate is about to expire, and that a certificate is 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 email 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: 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 pendingmsg2.form

From:dime-o-cert PKI
Subject:Certificate Requests are modified, reapproval is needed

Dear %%cadomain%% administrator,

The following requests, waiting for your approval, are modified
by the specified administrators. Previous approvals are invalidated.

Request Requestor Approvals Modified by
                  Required
%%modreqlist%%

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

Notes:

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 that you can use in the forms when you customize them. At run time, 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.)
`%%modreqlist%%`	A list of pending approval requests (or a single request) that are modified by an administrator. (This variable is valid only in the pending modified message form, `pendingmsg2.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 pickup. 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, which is 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 email address for the certificate matches the email 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	pendingmsg2	renewcertmsg	recoverymsg
`%%cadomain%%`	(ignored)	(ignored)	(ignored)	X	(ignored)	(ignored)	(ignored)
`%%dn%%`	X	X	X	(ignored)	(ignored)	X	(ignored)
`%%printcert%%`	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	X	(ignored)
`%%modreqlist%%`	(ignored)	(ignored)	(ignored)	(ignored)	X	(ignored)	(ignored)
`%%notafter%%`	(ignored)	(ignored)	X	(ignored)	(ignored)	(ignored)	(ignored)
`%%pendreqlist%%`	(ignored)	(ignored)	(ignored)	X	(ignored)	(ignored)	(ignored)
`%%quicklink%%`	X	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)
`%%recoverylink%%`	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	X
`%%recoverylist%%`	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)	X
`%%rejectreason%%`	(ignored)	X	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)
`%%requestor%%`	X	X	X	(ignored)	(ignored)	X	X
`%%transactionid%%`	X	X	(ignored)	(ignored)	(ignored)	(ignored)	(ignored)