Digital Certificates Cleanup Script

 

Versions of Microsoft® Outlook® that support Secure/Multipurpose Internet Mail Extensions (S/MIME) allow individual users to publish digital certificates that they receive into the global address list (GAL). When a user publishes a digital certificate, Outlook adds the certificate to the Microsoft Active Directory® directory service userSMIMECertificate multivalue attribute. Because the certificates might not have been issued by the organization's certification authority (CA), the certificate could inadvertently or maliciously be used to create messages that the organization would be unable to decrypt. For this reason, when implementing a Microsoft Windows Server™ 2003 certification authority to support Exchange 2003 S/MIME, it is usually necessary to remove the user-added certificates from the GAL.

The userSMIMECertificate attribute was added in Request for Comments (RFC) 2798. For more information, see "Definition of the inetOrgPerson LDAP Object Class" (https://www.ietf.org/rfc/rfc2798.txt).

You can use the ListSMIMECerts script to help you find and remove certificates from the userSMIMECertificate attributes. The script searches the Active Directory users container to find any users who have values inside the attribute. In the default mode, the script lists those users who have stored certificates. When you select verbose mode, the script also displays the certificate issuer and subject. The script can optionally remove the certificates. The script does not remove the attribute; it only removes values from the attribute.

Warning

When using ListSMIMECerts to remove certificates, the certificates are not saved, and there is no opportunity to confirm the deletion. It is assumed that by specifying the command-line option to remove the certificates, the user wants them removed.

Requirements

The ListSMIMECerts script requires that the following software be installed on the computer where it is run:

  • Windows Script Host version 5.6 or later

  • CAPICOM (used for only the verbose option)

  • Windows® 98 or later (Windows 2000 or later is recommended)

For more information about downloading CAPICOM, see Platform SDK Redistributable: CAPICOM.

Refer to the documentation that comes with CAPICOM for installation instructions. CAPICOM is only needed to retrieve the certificate issuer and subject when the user specifies /verbose on the command line. If the user includes the /verbose option and the CAPICOM library is not present, the script will output an error message, but will continue running.

In addition, the following conditions must also be met:

  • An Active Directory domain controller for the desired domain must be available from the computer where you run ListSMIMECerts.

  • The user running the script must have appropriate privileges to read the properties in Active Directory. To remove the certificates, the user running the script must also have appropriate domain administrator privileges to write to the attributes.

  • Active Directory replication must occur. Because the userSMIMECertificate attribute is, by default, not cached in the Active Directory global cache, the deleted certificates may remain available to users until Active Directory replication has completed.

  • Exchange 2000 or Exchange 2003 must be used. This script can be used with Exchange 2000 or Exchange 2003, but does not access Exchange. The RFC 2798 definition of the inetOrgPerson Lightweight Directory Access Protocol (LDAP) object class includes the userSMIMECertificate attribute.

Locating the ListSMIMECerts Script

When you extracted this book, the ListSMIMECerts.vbs file was placed in the same directory as this document. The default location is C:\Program Files\Microsoft WSS Books\Exchange Server.

Running the ListSMIMECerts Script

Run the ListSMIMECerts script from a Command Prompt window, using the command-line scripting environment. To view the command-line syntax and Help, type the following:

cscript ListSMIMECerts.vbs /help

Note

It is not recommended that you run ListSMIMECerts under the Windows scripting environment (wscript). Each line of text output into the Command Prompt window will be displayed as a pop-up message box, requiring you to click OK for each line. Always use the command-line scripting environment (cscript). To set the command-line scripting environment as your default, type the following: wscript -f //H:cscript

You can run ListSMIMECerts from any computer that has access to the domain controller for the domain that you want to examine. Remember that the user running the script must have sufficient privileges to read and write the Active Directory properties.

In its most basic form, call the script with no options:

cscript ListSMIMECerts.vbs

The command with no options uses the default naming context for the computer, and lists those users who have values in the userSMIMECertificate attribute. It does not delete any attribute values. For information about the options, see the "ListSMIMECerts Options" later in this topic.

ListSMIMECerts Options

You control the ListSMIMECerts script using command-line options. When using ListSMIMECerts options:

  • Command line options are not case sensitive: /help, /Help, /HELP, and /HeLp are all interpreted the same.

  • The order of the command-line options is not important; if an option is specified more than once, the last valid option will be used.

  • The /dom option requires a fully qualified domain name (FQDN), separated from the /dom option with an equal sign (=) or a colon (:). For example, /dom=server.subdomain.example.com. There can be no spaces in the option.

The ListSMIMECerts script has the following command line options.

/dom=<Domain-Name>

The /dom option specifies the domain that the script searches. If the /dom option is not provided, the script looks up the default naming context for the computer on which it is running, and uses that domain name. If you are not sure what the default naming context is for the computer, you can obtain it by using the /help switch. The default naming context is shown at the end of the help information.

Do not include spaces in the domain name or surrounding the equal sign (or colon). For example, the following will return an error message and is the wrong syntax for this option:

cscript ListSMIMECerts.vbs /dom = server.subdomain.example.com

The correct syntax is:

cscript ListSMIMECerts.vbs /dom=server.subdomain.example.com

/remove

By default, ListSMIMECerts does not remove any values from the users; it only lists the users who have values. When you specify the /remove option on the command line, all values found in the userSMIMECertificate attributes for the domain users are removed.

Warning

When you specify the /remove option, the script does not ask for any confirmation before deleting the certificates.

For example, the following command scans the default domain and removes any userSMIMECertificate values it finds:

cscript ListSMIMECerts.vbs /remove

/verbose

The /verbose switch causes the script to output additional information about:

  • The command-line options specified.

  • The certificate issuer and subject for each certificate found.

The following example command lists the users who have certificates and information about those certificates, but does not remove them. You can use this command to find users with certificates, and possibly notify them that the certificates will be deleted or that they should not be publishing certificates to the GAL.

cscript ListSMIMECerts.vbs /verbose

The following example command lists the users who have certificates and information about those certificates, deletes the certificates, and stores the information in a log file.

cscript ListSMIMECerts.vbs /verbose /remove > ListSMIMECerts-2003-11-03.log

Important

If you need to retain the detailed certificate information provided in the previous example, be careful to ensure that CAPICOM is available on the computer running the script. The script deletes the certificates without CAPICOM, but does not display the detailed certificate information for your records.

/help

This option displays the command-line syntax Help. The script ignores any other options and exits after displaying the help information. The script displays the default naming context at the end of the help information.

Example Output

The following example command searches a specific domain and produces an output that lists information about each certificate:

cscript ListSMIMECerts.vbs /verbose /dom=server.subdomain.example.com

This command produces the following sample output:

Microsoft (R) Windows Script Host Version 5.6

Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

 

==========================================

ListSMIMECerts: (c) 2003, Microsoft

For additional options, use /help option

Started at: 10/29/2003 3:57:16 PM

==========================================

Domain      : server.subdomain.example.com

Remove Mode : False

Verbose     : True

==========================================

Users with userSMIMECertificate values:

  username1

    ExampleDomain SARoot CA v1.0 (subject: ExampleDomain SARoot CA v1.0)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username1)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username1)

  username2

    ExampleDomain SARoot CA v1.0 (subject: ExampleDomain SARoot CA v1.0)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username2)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username2)

  username42

    ExampleDomain SARoot CA v1.0 (subject: ExampleDomain SARoot CA v1.0)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username42)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username42)

  username77

    ExampleDomain SARoot CA v1.0 (subject: ExampleDomain SARoot CA v1.0)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username77)

    ExampleDomain EntSub Issuing CA v1.0 (subject: username77)

==========================================

Processed 100 users.

Found     4 userSMIMECertificate attributes with values.

Finished at: 10/29/2003 3:57:38 PM

========================================== 

Troubleshooting

The ListSMIMECerts script can report various error conditions. Because the actual error may come from an underlying subsystem, be sure to read all the error information to determine the problem. Because the list of users can be quite long, and because the script does not stop on all errors, the following is displayed at the end of the script when errors occur:

Note: See above for error information. 

The ListSMIMECerts script can display the following errors.

ERROR Retrieving the default RootDSE. The domain controller appears to be unavailable.

The script was unable to contact Active Directory and obtain the DSA-specific Entry (DSE) at the root of the directory information tree (DIT). The script stops when this error occurs. This error can indicate that the Active Directory domain controller for the computer is currently unavailable. You may need to manually specify the domain using the /dom option.

ERROR Retrieving default naming context.

The script was unable to retrieve the default naming context from the root DSE. The script continues after this error. This error can indicate the Active Directory domain controller for the computer is currently unavailable. You may need to manually specify the domain using the /dom option.

ERROR Verbose mode requested, but CAPICOM library appears to not be loaded and registered on this computer.

The script was unable to create a CAPICOM CertificateStore object. The script continues after this error. This error indicates the CAPICOM library is not properly installed on the computer running the script. Obtain the CAPICOM library and install it. For more information about downloading the CAPICOM library, see Platform SDK Redistributable: CAPICOM.

ERROR Retrieving domain users container.

The script was unable to retrieve the users container from Active Directory. The script stops when this error occurs. This error can result when the domain specified in the /dom option is incorrect, or when the user running the script does not have permission to access the users container. Verify that the domain name is correct, and that you have the proper privileges needed to access the users container and the items inside it.

ERROR Retrieving user distinguished name.

The script was unable to determine the user's distinguished name from Active Directory. The script continues after this error. This error can result when the user running the script does not have permission to access the users container. Verify that you have the proper privileges needed to access the users container and the items inside it.

ERROR Retrieving user name.

The script was unable to determine the user's display name from Active Directory. The script continues after this error. This error can result when the user running the script does not have permission to access the users container. Verify that you have the proper privileges needed to access the users container and the items inside it.

ERROR Retrieving Active Directory user.

The script was unable to retrieve the user object from Active Directory. The script continues after this error. This error can result when the user running the script does not have permission to access the users container. Verify that you have the proper privileges needed to access the users container and the items inside it.

ERROR Unable to clear the attribute values.

The script was unable to delete a value from the userSMIMECertificate attribute of the user currently being processed. The script continues after this error. This error can result when the user running the script does not have permission to access the users container. Verify that you have the proper privileges needed to access the users container and the items inside it.

ERROR Unable to set the user information.

The script was unable to save the userSMIMECertificate attribute to Active Directory. The script continues after this error. This error can result when the user running the script does not have permission to access the users container. Verify that you have the proper privileges needed to access the users container and the items inside it.

ERROR on command line: No domain was specified.

The script was unable to find a domain name in the /dom option. The script stops when this error occurs. This error is usually caused because there is a space between the /dom option, the equal sign, and the domain name. Spaces are not allowed in the /dom option.

ERROR on command line: <unrecognized option>.

The script did not recognize the command-line option. The script stops when this error occurs. Check the command-line options and, if necessary, use the /help option to determine the correct syntax.

How the ListSMIMECerts Script Works

The ListSMIMECerts script locates, reads, and writes Active Directory objects and attribute values. When the user specifies the /verbose option, the script imports the userSMIMECertificate attribute values into a CAPICOM Certificate Store, and extracts information about the certificates.

The script source code performs the following major operations. For complete information, refer to the comments in the source code.

  1. Define and initialize the necessary constants and variables.

  2. Define a utility subroutine that displays information to the user.

  3. Define a utility subroutine that displays error information when it occurs.

  4. Define a utility subroutine that locates the default domain name for the computer.

  5. Process the command-line options.

  6. When needed, display the help information and exit.

  7. If the /verbose option was given, verify that the CAPICOM library is available. That library is only used to extract information from the certificate values. If CAPICOM is not available, the script continues.

  8. Convert the FQDN to an LDAP path, and get the users container from Active Directory.

  9. Select the first Active Directory user.

  10. Retrieve the userSMIMECertificate attribute from Active Directory. Because userSMIMECertificate is not cached in the global cache, Active Directory returns an error. That specific error can be ignored because the data is returned. However, the data may be out-of-date if changes have not yet been replicated to the domain controller that the script is accessing.

  11. If the user supplied the /verbose option, and CAPICOM is available, the script loads each attribute value into a CAPICOM CertificateStore object, reads the individual certificates, and displays the issuer and subject.

  12. If the user supplied the /remove option, the script deletes the attribute values.

  13. Move to the next Active Directory user, and repeat steps 10 through 13 until there are no more users.

  14. Clean up the objects used in the script, and display the summary information.

Customizing the ListSMIMECerts Script 

The script code is provided for your information. You can also use the code to extend the script to fit your needs. The following list describes some features that you might want to include:

  • Specify individual users from which to remove the attribute values.

  • Read the list of users to process from a comma-separated value (.csv) file or database.

  • Display the full LDAP path to the user containers.

  • Save the certificate data for later restoring or for more complete records.

  • Write an entry into the Auditing Event Log for security monitoring and auditing.

  • Send e-mail messages to users who have certificates, informing them of the organization's policies for using S/MIME certificates.

  • Provide an interactive mode that asks for confirmation for each deletion.