PKCS#11 logger library
This section describes the PKCS#11 logger library, it's architecture and functionality, how to set it up, activate logging, and deactivate logging.
Overview
The logger library produces a log of all PKCS#11 function calls called by an application. It is a useful tool for debugging applications that are developed using the ProtectToolkit-C API.
This library can be used with ProtectToolkit-C in any of the three operating modes; hardware, client/server or software only.
Logger architecture and functionality
PKCS#11 logger architecture model
The logger is interposed between the application and the ProtectToolkit-C host library. There, it intercepts PKCS#11 function calls and responses. Details are logged to the log file before the messages are passed through to their intended destination.
For each PKCS#11 call, the logger creates an entry in the log file. By default, these entries contain the following details:
-
the calling process ID (PID)
-
the thread ID (TID)
-
the date and time of the call
-
all numeric data
-
buffer addresses
-
contents of buffer addresses at the input and output of functions (excluding PIN values)
Optionally, the logger can be configured to:
-
return the PIN values used to login to tokens that are provided to the C_Login function
-
remove any or all of the following from the output:
-
the calling process ID (PID)
-
the thread ID (TID)
-
the date and time of the call
-
contents of buffer addresses at the input and output of functions
Logger setup
As discussed above, the logger logs information passing between an application and the ProtectToolkit-C host library to a log file. The following configuration steps must be carried out before starting the application.
-
Activate logging by setting up redirection of ProtectToolkit-C host library calls sent from the application so that they are instead delivered to the logger.
-
Store the name and filepath of the ProtectToolkit-C host library file for the logger to use when forwarding the redirected calls it receives to their intended destination.
-
If required, complete the following two steps:
-
Change the name and location of the log file from the default values.
-
Change the amount of detail recorded by the logger from the default settings.
Each of these steps is covered in detail in the sections that follow. Once they have been carried out, the logger is active whenever the application is running. To deactivate the logger, see Deactivating logger operation.
Activating logging
Logging is activated by setting up redirection of ProtectToolkit-C host library calls sent from the application so that they are instead delivered to the logger. This procedure differs between Windows and UNIX systems. To activate logging, consult the section below applicable to your operating system.
To activate logging on a Windows-based system, you must redirect ProtectToolkit-C host library calls to the logger by replacing the path to the ProtectToolkit-C host library (Cryptoki provider) with the path to the logger in the system environment variables. The ProtectToolkit-C host library and the logger are both named cryptoki.dll so the application does not detect any difference and is unaffected by this change.
To enable the logger on Windows
-
Edit the Environment Variables in the Windows Control Panel.
-
Under the system variables, locate SFNT_CRYPT.
-
Change the value of SFNT_CRYPT to (using the default installation location):
C:\Program Files\Safenet\ProtectToolkit 7\C SDK\bin\logger
-
Now that logging is enabled, you must create a new system environment variable or Windows registry entry to specify HSM or Software Emulator mode, as described below.
Note
With logging enabled, you can no longer use the Windows installer to switch between HSM and Software Emulator modes. Changing the mode this way will disable logging.
To specify HSM or Software Emulator mode in the system environment variables after logging is enabled
-
Edit the Environment Variables in the Windows Control Panel.
-
Create new system environment variables for ET_PTKC_LOGGER_FILE and ET_PTKC_LOGGER_PKCS11LIB. For more information about configuring these environment variables, refer to Logger configuration items.
Caution
Applications that were running before the modification, including cmd windows, must be restarted before changes are reflected. Be especially cautious about this when switching from Software Emulation to HSM mode.
To specify HSM or Software Emulator mode in the Windows registry after logging is enabled
-
Open the Windows Registry Editor (regedit.exe).
-
Create a new key: HKEY_LOCAL_MACHINE\SOFTWARE\Safenet\PTKC\LOGGER
-
Under this key, create two string values for ET_PTKC_LOGGER_FILE and ET_PTKC_LOGGER_PKCS11LIB. For more information about the valid string values for these environment variables, refer to Logger Configuration Items.
Caution
Applications that were running before the modification, including cmd windows, must be restarted before changes are reflected. Be especially cautious about this when switching from Software Emulation to HSM mode.
To activate logging on a Unix-based system, ProtectToolkit-C host library calls are redirected to the logger by
-
Reassigning the libcryptoki.so (libcryptoki.a for AIX) symbolic link from the ProtectToolkit-C host library (Cryptoki provider) that was set up during installation to the logger shared library liblogger.so (liblogger.a for AIX).
-
Including the logger library in the LD_LIBRARY_PATH environment variable (LIBPATH on AIX).
The application does not detect any difference and is unaffected by this change.
For example, use the following commands to reassign the libcryptoki.so symbolic link:
# cd /opt/safenet/protecttoolkit7/ptk/lib # ln -sf liblogger.so libcryptoki.so
Changing the level of detail recorded by the logger
To change the level of detail recorded by the logger, override the default values of the following configuration items:
-
ET_PTKC_LOGGER_LOGPID
-
ET_PTKC_LOGGER_LOGTID
-
ET_PTKC_LOGGER_LOGTIME
-
ET_PTKC_LOGGER_LOGMEM
-
ET_PTKC_LOGGER_LOGPIN
For more information about these configuration items, refer to Logger configuration items.
The changes can be made at the temporary, user or system levels on both UNIX and Windows platforms. Refer to Configuration items for more information.
Deactivating logger operation
To deactivate the logger, the steps taken in Activating logging must be reversed. Consult the applicable section for your system.
To deactivate logging, you can select HSM or Software Emulator mode using the Windows installer (see Modifying the ProtectToolkit Windows installation), or change the SFNT_CRYPT system environment variable to select the mode as follows (assuming the default installation location):
-
ProtectServer HSM mode: C:\Program Files\Safenet\ProtectToolkit 7\Runtime\lib\
-
Software Emulator mode: C:\Program Files\Safenet\ProtectToolkit 7\C SDK\bin\sw\
The symbolic link libcryptoki.so (libcryptoki.a for AIX) must be re-assigned to the ProtectToolkit-C host library required.
For example, if ProtectToolkit-C is being used in hardware or client/server mode, the commands to use would be:
# cd /opt/safenet/protecttoolkit7/ptk/lib# ln -sf liblogger.so libcthsm.so
In software-only mode, use the following commands:
# cd /opt/safenet/protecttoolkit7/ptk/lib# ln -sf liblogger.so libctsw.so
