Table of Contents

Introduction

CAPI2 Diagnostics is a feature first introduced in Microsoft® Windows® Vista. This feature provides administrators with an ability to troubleshoot PKI problems by collecting detailed information about certificate chain validation, certificate store operations and signature verification. With CAPI2 Diagnostics, it is easier to identify the root cause of most PKI problems. CAPI2 Diagnostics can reduce the time required to diagnose problems and improve the troubleshooting experience.

For quick instructions on how to enable this feature, see below. To learn more about CAPI2 Diagnostics, check out the whitepaper on Troubleshooting PKI problems on Windows Vista at http://www.microsoft.com/downloads/details.aspx?FamilyID=FE8EB7EA-68DA-4331-9D38-BDBF9FA2C266

 

If you have questions or feedback, you can send it to capidiag@microsoft.com

How to enable CAPI2 Diagnostics?

You can enable this feature from the event viewer UI or use command line scripts.

A. From the Event Viewer UI

  1. Open the Event Viewer.
    • To do this, Click on Windows Start Symbol, then right-click on Computer and select “Manage”
    • Event Viewer is one of the nodes under System Tools under Computer Management.
    • Note that Event Viewer is a MMC snap-in and you need administrative privileges to access the Event Viewer.
  2. In the Event Viewer, go to Application and Services Logs -> Microsoft -> Windows -> CAPI 2 to get the CAPI 2 channel.
  3. Right-click on "Operational" and select “Enable Log”. This will enable CAPI2 Diagnostics logging.
  4. To save the log to a file, right click on "Operational" and select the “Save Events as” option.
    • You can save the log file in the .evtx format (which can be opened through the Event Viewer) or in the standard XML format.
  5. If there is data present in the logs before you reproduce the problem, it is recommended that you clear the logs before the repro. This allows only the data relevant to the problem scenario to be collected from the saved logs.
    • To clear the logs, right click on "Operational" and select the “Clear Log” option.
  6. 6. The default size for the event log is 1 MB. For CAPI2 Diagnostics, the logs tend to grow in size quickly and it is recommended to increase the log size to at least 4 MB to capture relevant events.
    • To increase the log size, Right-click on “Operational” and select the “Properties” option. In the log properties, increase the maximum log size.

B. Command line scripts

You can also enable logging and save the logs using the wevtutil.exe tool.

Launch a command line with administrative privileges. Run the following commands

  1. To enable logging,

    wevtutil.exe sl Microsoft-Windows-CAPI2/Operational /e:true

  2. To save the log to a file,

    wevtutil.exe epl Microsoft-Windows-CAPI2/Operational filename.evtx

  3. To disable logging,

    wevtutil.exe sl Microsoft-Windows-CAPI2/Operational /e:false

  4.  To clear logs,

    wevtutil.exe cl Microsoft-Windows-CAPI2/Operational

  5.  To increase the log size

    wevtutil sl Microsoft-Windows-CAPI2/Operational /ms:<log-size-in-bytes>

Logging Modes

CAPI2 Diagnostics utilizes Event Viewer features, such as use of error level and keywords, for filtering the data in the log. For example, if you want to look at path validation related errors, you can filter by an event level of "Error" (level 2) and the keywords "chain building," "chain validation," and "revocation." Events are marked level 2 when the API returns an error and level 4 if the API returns a success.

In the default logging mode, only events with levels 2 and 4 are logged. This includes success and error events for the top-level events along with any child error events. For more detailed logging with additional information corresponding to the child events, enable the verbose logging mode. With the verbose mode, events with verbose level 5 are available in the log. For example, with verbose mode, the links to the binary X.509 objects are available in the log. X.509 objects are cached in file system at %USERPROFILE%/AppData/LocalLow/Microsoft/X509Objects.

This is logged as:

<X509Objects>

  <Base path="F:\Users\abby\AppData\LocalLow\Microsoft\X509Objects”/>

 Verbose mode is useful for operations that rarely fail, such are store and cache operations, but are sometimes useful to give context to other events. If the operation fails, an error event with a level of 2 will be logged and will be available in the default logging mode.

To enable verbose mode

  1. Click the Start button, click Start Search, type Run, and then press Enter.
  2. In Run, type regedit, and then click OK.
  3. If the User Account Control dialog box appears, confirm that the action it displays is what you want, and then click Continue.
  4. Navigate to the following registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\crypt32.
  5. Add a DWORD (32-bit) value DiagLevel with value 0x00000005.
  6. Add a QWORD (64-bit) value DiagMatchAnyMask with value 0x00ffffff.
  7. Additionally, If you want to log events only for a particular process, add a multi-string value:
    • "DiagProcessName" and enter the process name such as iexplore.exe
  8. If you want to log events only for specific keywords, you can set the appropriate mask in DiagMatchAnyMask.

 

See Also

Other Resources

Security Developer Center

Cryptography Topics on MSDN

Follow us on Twitter