Operating a PKI: SMTP Exit Module

  • Article

I am back to discuss the SMTP Exit Module.  The SMTP Exit Module is a very useful monitoring tool, yet so many are unaware of the SMTP Exit Module.  In this blog posting I am going to answer the following questions and address the following topics related to the SMTP Exit Module:

  • What is an Exit Module?
  • What does the SMTP Exit Module do?
  • Why should I use the SMTP Exit Module?
  • How do I install the SMTP Exit Module?
  • Advanced Configuration of the SMTP Exit Module
  • What do the email alerts look like?

 

What is an Exit Module?

Essentially after a certificate or CRL is signed by the CA,, the CA notifies any Exit Modules that are available of this event.  Exit Modules then take some action when a certificate or CRL is signed.  These can include actions like logging the certificate or CRL to a SQL Database, or sending an email alert.  Additional actions that can trigger an exit module include a certificate request being submitted to the CA and awaiting approval, a certificate request being denied by the Certificate Manager, a On Hold revoked certificate being unrevoked, stopping of the Active Directory Certificate Services service, and starting of the Active Directory Certificate Services service.  Additional information on Exit Modules are available here: https://technet.microsoft.com/en-us/library/cc783853(v=WS.10).aspx and here: https://msdn.microsoft.com/en-us/library/windows/desktop/aa388214(v=vs.85).aspx.

What does the SMTP Exit Module do?

The SMTP Exit Module sends email alerts.  By default it sends email alerts when:

  • CRL is issued
  • Certificate request is denied by the Certificate Manager
  • Certificate is issued
  • Certificate request is put in a pending state
  • Approved pending request is retrieved
  • Certificate is revoked
  • Certificate revoked with the On Hold reason is unrevoked
  • CA Service is stopped
  • CA Service is started

 

Why should I use the SMTP Exit Module?

The first reason to use the SMTP Exit Module is for monitoring the actions taking place on the Certification Authority.  Even if you don’t monitor the emails in real time, you will have an audit log if you will, in a mailbox. 

The second reason is illustrated in the graphic below.  In this example the CA is backed up at Time 0.  After the backup the CA issues certificates.  At Time 1 the CA fails.  At Time 2 the CA is recovered from the backup taken at Time 0.  The problem here is that after the restore there is no record of certificates issued after the backup, but before the restore.  These are known as orphaned certificates. The problem with orphaned certificates is that they are valid, but you have no record of issuing them.  And if you have no record of issuing them, you have no way to revoke them if necessary.  However, if you have the SMTP module running, you have a list of certificates issued during this time.  And although going through a mailbox to determine what certificates you have issued is not the most convenient way to do determine this, at least you have a record.  You can also use the information in the email of issued certificates, specifically the Serial Number to revoke these certificates if necessary.  I will cover the process for revoking orphaned certificates in an upcoming blog post. 

Orphaned

How do I install the SMTP Exit Module?

The first step is to copy a batch file that will configure the SMTP Exit Module.  The SMTP Exit Module for Windows Server 2003 can be copied from  here: https://technet.microsoft.com/en-us/library/cc773129(v=WS.10).aspx.  For Windows Server 2008, 2008R2, and 2012 the SMTP Exit Module can be copied from here: https://social.technet.microsoft.com/wiki/contents/articles/2004.active-directory-certificate-services-smtp-exit-module-for-windows-server-2008-r2-example.aspx.  I am using the SMTP Module for Windows Server 2008 R2 as an example.

As mentioned on the web page for the Windows Server 2008 R2 Exit Module, you will need to make some modifications to the script before running it.:

Before using the batch file below, ensure that you make appropriate replacements:

  • <ExchangeServerNameOrIP> with the actual name or IP address of the Exchange Server you want to use.
  • <EmailAddress> with the administrative email address you want to use for sent from and send to.
  • <SMTPAccount> with the user account that you want to use for SMTP authentication
  • <Password> with the actual password of the SMTP account you want to use for authentication
  • Do not remove any of the quotes you see in the batch file. If you don't require a line, then use REM or : to comment that line out.
  • Always test the script on a non-production replica of your network environment before trying on a production system.
  • The following line certutil -setsmtpinfo -p "<smtpaccount>" <password> has been remarked out. Clear the REM and replace with the appropriate account name and password, if you need that authentication.

https://social.technet.microsoft.com/wiki/contents/articles/2004.active-directory-certificate-services-smtp-exit-module-for-windows-server-2008-r2-example.aspx

Also, if there are some alerts you do not want receive, you can REM them out in EventFilter section of the script.

Once you have configured the script, you can execute it with elevated permissions on the CA to install the SMTP Exit Module.

Once the SMTP Exit Module is installed you can view the settings in the registry.  The settings are located at HKLM\System\CurrentControlSet\Services\CertSvc\Configuration\<CAName>\ExitModules\CertificateAuthority_MicrosoftDefault.Exit\SMTP

image

Advanced Configuration of the SMTP Exit Module

SMTP

Advanced Configuration of the SMTP Exit Module can be performed by editing the registry.

If you go to the following location in the registry you can edit the SMTP Server, SMTP Authentication Method, and EventFilter: HKLM\System\CurrentControlSet\Services\CertSvc\Configuration\<CAName>\ExitModules\CertificateAuthority_MicrosoftDefault.Exit\SMTP

SMTPServer
For the SMTPServer you would enter the name or IP of your SMTP Server
SMTPAuthenticate

As mentioned in the script the settings for SMTPAuthenticate are:

  • 1 means to use NTLM
  • 2 means to user Kerberos
  • 0 is for Basic authentication
EventFilter

EventFilter is a bit more complicated.  The EventFilter setting is normally configured by the script in this section of the script:

:Setup_CA_For_Exit_Module // Section for turning events on or off. In this case, on.
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CRLISSUED
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTDENIED
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTISSUED
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTPENDING
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTUNREVOKED
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTRETRIEVEPENDING
certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTREVOKED
certutil -setreg exit\smtp\eventfilter +EXITEVENT_SHUTDOWN
certutil -setreg exit\smtp\eventfilter +EXITEVENT_STARTUP

Each EventFilter setting has a value associated with it.  For example the command certutil -setreg exit\smtp\eventfilter +EXITEVENT_CRLISSUED will set the EventFilter Decimal value to 32, assuming all of the other lines in this section of the script are REM’d out.  The command certutil -setreg exit\smtp\eventfilter +EXITEVENT_CERTDENIED will set the EventFilter Decimal Value to 4 assuming all of the other lines in this section of the script are REM’d out.  So, if the Decimal value of the EventFilter setting is 36, this would mean both CRLISSUED and CERTDENIED eventfilter is enabled.  If all eventfilters are enabled the Decimal value will be set to 511, which the sum of the Decimal values for all of the settings.  The table below gives the values for each setting:

 

image 

Denied, Issued, Pending, Retrieve Pending, Revoked, and Unrevoked

The settings for Denied, Issued, Pending, Retrieve Pending, Revoked, and Unrevoked are configured at their corresponding registry key located at:

HKLM\System\CurrentControlSet\Services\CertSvc\Configuration\<CAName>\ExitModules\CertificateAuthority_MicrosoftDefault.Exit\SMTP\Templates\Default\

BodyArg

Is used to assign variables to the column rows that are desired to be included in the BodyFormat.  A list of database columns is available in this article: https://technet.microsoft.com/library/Cc783853.aspx, under the section titled Schema of the Certificates Database.   For example if I wanted to include information from the columns Request.RequestID and SubjectKeyIdentifier I would set the value of this registry setting to:

Request.RequestID SubjectKeyIdentifier

When I configure the BodyFormat setting Request.RequestID would be referenced by a %1 and SubjectKeyIdentifier by a %2.  The number increments for each row added in the list.

BodyFormat

Includes a list of information that will be included in the email.  The variables used here come from the list of database columns listed in the BodyArg registry setting.

From

This is the SMTP address you wish to have listed in the From field of the email.

TitleArg

Much like BodyArg this setting configures variables that will be used in the TitleFormat setting.  The default is SanitizedCAName.  Ironically, SanitizedCAName is not a column in the database as far as I am aware.

TitleFormat

Includes the text that will be included in the Title of the email.  TitleFormat uses variables that are defined in TitleArg setting.

To

This is the SMTP address you wish to send the email to.  If you would like to send the email to multiple recipients you will need to configure a distribution group that includes those recipients.  You would then set the To setting to send emails to that distribution group.

What do the email alerts look like?

CRL issued

image

 

Denied Certificate Request

image

 

Certificate Issued

image

 

Pending Request

image

 

Retrieved Certificate

image

 

Revoked Certificate

image

 

Unrevoked Certificate

image

 

Service Shutdown

image

 

Service Startup

image

Conclusion

This blog posting covered installing and configuring the SMTP Exit Module.  In my next blog posting I will cover the steps necessary to revoked an orphaned certificate.  Below is a video that covers the same material covered in this blog posting.

-Chris

SMTP Exit Module