Writing Event Plugin Handlers for the Certificate Management System (CMS)

The Certificate Management System (CMS), formerly known as the Certificate Reporting Tool (CRT), as referenced below, provides reporting and notification capabilities to an existing Public Key Infrastructure (PKI). The reports and notifications are highly customizable for content, timing, and audience. In addition, custom ‘event plugin handlers’ can be created and registered to perform any desired functionality when predefined events occur. Two types of CRT events are exposed:

• Notice Generated: fired when a certificate meets the predefined criteria according to the associated certificate template and lifecycle milestone.
• Pending Certificate Alert Generated: fired when a certificate request has been marked as pending by the certificate authority.

Examples of functionality that could be implemented via CRT event handlers include:

• Determining an email contact programmatically: suppose that any webserver certificates issued containing “OU=finance” somewhere in the subject name should have notices delivered to [email protected]. The handler could look for this string – perhaps even a specific recipient – and change it.
• Looking up a contact email from another source: suppose email contact information is stored in another database. The handler could use (for example) the cert serial number as the search key to look up the associated email contact.
• Perform a certificate renewal: allow the email notification to be sent, but invoke a function that takes action and renews the certificate. This could be especially useful on non-Windows platforms or in situations where auto-enrollment doesn’t occur automatically.
• Approve a pending certificate request automatically: a custom workflow could be triggered to analyze the request and approve or reject it according to business rules.

If a plugin handler is defined, and associated with a Notice or Pending Certificate Request, it will be called when an alert is generated for a certificate or request. Handlers can be registered with CRT through the CRT Configuration Utility. The architecture allows for multiple handlers to be registered and associated with one or more Notices or Pending Certificate Alerts. If an email is to be sent, the plugin will be called immediately before the actual email is relayed to the server.

A conceptual layout of CRT is outlined in Figure 1 below. Note the ‘Custom Plugin’ component, highlighted in red. Although the diagram refers to a corporate database, this is only for display purposes. Active Directory (AD), a workflow engine or other entity could be substituted.

Figure 1 – CRT Conceptual Layout

Example Code

The CRT engine is a managed dynamic link library (dll), and this example is written in C#.NET, but any managed language can easily be used. The basic steps to setting up a Visual Studio project are:

1. If developing on a remote development machine running a serveroperating system
   1. Install the CRT product on the development machine
   2. If developing on a remote development machine running a clientoperation system
      1. Copy the ‘CSS.CRT.Core.dll’ to the development machine
      2. Create a new Visual Studio project, using the ‘Class Library’ template
         1. Rename ‘Class1’ to ‘SampleNoticeHandler’
         2. Add a reference to the project
            1. Navigate to the location containing the CRT dlls
            2. Select the ‘CSS.CRT.Core.dll’
            3. Implement the ‘ICRTNoticeHandler’ interface

public class SampleNoticeHandler : CSS.CRT.Core.ICRTNoticeHandler

1. Implement the ‘ICRTNoticeHandler’ interface methods
   1. NoticeCallback_Email – This method is called when a Notice is generated and the system is set to send an email. This method will be called for each recipient of the Notice email.

i. string Subject – Original subject of the email message

ii. string Message – Original text of the email message

iii. string Recipient – Notice email recipient

iv. out string newSubject – Subject of the email message after processing. This value must be set within the method, even if it is not modified. If it is not updated, it may be set to the original subject value.

v. out string newMessage – Text of the email message after processing. This value must be set within the method, even if it is not modified. If it is not updated, it may be set to the original text value.

vi. out string newRecipient – Email recipient after processing. This value must be set within the method, even if it is not modified. If it is not updated, it may be set to the original recipient value.

vii. bool [return value] – Set this value to ‘true’ if the message should still be sent by CRT, or false if it is not to be sent.

[sourcecode language=”csharp”]
public bool NoticeCallback_Email(string Subject, string Message, string Recipient,
out string newSubject, out string newMessage, out string newRecipient)
{
// for this example, copy over the message and recipient, but change the subject line.
newSubject = Subject + ” – Modifed by example code”;

// the message is not modified, so set it to the original value
newMessage = Message;

// the recipient is not modified, so set it to the original value
newRecipient = Recipient;

// return ‘true’ so the email will still be sent; if custom actions are to be taken INSTEAD of
// sending an email, we would return ‘false’.
return true;
}
[/sourcecode]

1. NoticeCallback_NoEmail – This method is only called by the CRT Commandline program, and only when the “/noemail” option is provided on the command line. This method will be called once with the complete list of recipients.

i. string Subject – Original subject of the email message

ii. string Message – Original text of the email message

iii. string RecipientList – List of notice email recipients

iv. out string newSubject – Subject of the email message after processing. This value must be set within the method, even if it is not modified. If it is not updated, it may be set to the original subject value.

v. out string newMessage – Text of the email message after processing. This value must be set within the method, even if it is not modified. If it is not updated, it may be set to the original text value.

vi. out string newRecipientList – List of email recipients after processing. This value must be set within the method, even if it is not modified. If it is not updated, it may be set to the original recipient value.

[sourcecode language=”csharp”]
public void NoticeCallback_NoEmail(string Subject, string Message, string RecipientList,
out string newSubject, out string newMessage, out string newRecipientList)
{
// for this example, copy over the message and recipient list, but change the subject // line.
newSubject = Subject + ” – Modifed by example code”;

// the message is not modified, so set it to the original value
newMessage = Message;

// the recipient list is not modified, so set it to the original value
newRecipientList = RecipientList;
}
[/sourcecode]

1. Compile the project
2. Copy the resulting .dll to a server running CRT
3. Update the crtcommandline.exe.config file to use the new handler
   1. Set the ‘EmailNoticePlugin’ value to the path of the handler
   2. Execute the CRT commandline program with settings that will generate an email
      1. Verify that the resulting email subject line contains the ‘Modified by example code’ text
      2. Execute the CRT commandline program with settings that will not generate an email, but will instead create a text file output
         1. Verify that the result subject line contains the ‘Modified by example code’ text

The example above is related to CRT Notices. The process for implementing Pending Certificate Alerts events is the same. Simply implement the PendingCertAlertCallback_Email and PendingCertAlertCallback_NoEmail methods.

The CRT Notice Handler plugin interface provides the flexibility to perform nearly any task during the creation of a certificate notice or pending request alert, and allows for robust interaction with other back-end systems.