Using OpenSC

Using OpenSC

opensc-pkcs11.so and many tools need the opensc config file to work properly.
On Linux and Mac OS X the location of the config file is set when calling
configure and then compiled in. However you can use the OPENSC_CONF environment
variable to specify a different config file. See also the EnvironmentVariables page.

On windows the opensc config file is found using the registry key
HKML\Software\OpenSC Project\OpenSC\ConfigFile. If you compile and install OpenSC from
source you need to set this registry key to point to the install file.
Users can set HKMU\Software\OpenSC Project\OpenSC\ConfigFile to override the system
wide settings. Also users can use the OPENSC_CONF environment variable
to override both registry settings.

Debug level

The OpenSC configuration (in general /etc/opensc.conf) has a debug level variable: debug. It is possible to overwrite this value using the OPENSC_DEBUG environment variable. For example you can use:

$ OPENSC_DEBUG=9 pkcs11-tool --list-slots

PKCS #11 Spy

PKCS#11 Spy is a special PKCS#11 Module that sits between your application
and your real PKCS#11 Module, and creates a log file with all functions calls
by the application and return values by the real PKCS#11 Module. It does not
change the communication in any way. Be aware such log files are security
sensitive, as all information is logged, including PIN, PUK, signatures
and so on. So you should only use it for debugging, and preferable only with
test keys.

On Linux and Mac OS X you can use PKCS#11 Spy with environment variables:
by default stderr will be used for logging, but you can set PKCS11SPY_OUTPUT
to a filename, and that file will be appended. You need to set PKCS11SPY
to your readl PKCS#11 Module such as opensc-pkcs11.so (but use an absolute
path) to use PKCS#11 Module.

On windows the read PKCS#11 Module is found using HKLM\Software\OpenSC Project\PKCS11-Spy\Module
and the output is written to the file specified in HKLM\Software\OpenSC Project\PKCS11-Spy\Output (Default: TEMP\pkcs11-spy.log).
Again users can override these system wide settings using HKLU, and again user
can use environment variables to override the registry settings.

Note that PKCS#11 Spy no longer reads the OpenSC config file and the settings
in that config file (up to OpenSC version 0.9.*) are no longer valid. Now it
is absolutely necessary to set at least the module via environment variables
(or registry on windows).

Example, with Gnome evolution mail reader:

PKCS11SPY=/usr/lib/pkcs11/opensc-pkcs11.so \
PKCS11SPY_OUTPUT=logfile \
evolution

Inside evolution, select pkcs11-spy.so instead of opensc-pkcs11.so .

To debug `ssh-agent`, these environment variables needs to be set for the `ssh-agent` process:

export PKCS11SPY=/usr/lib/pkcs11/opensc-pkcs11.so \
export PKCS11SPY_OUTPUT=logfile `eval ssh-agent`;
ssh-add -s /usr/lib/pkcs11-spy.so