Skip to main content
Version: 4.6.x.x LTS

Appendix F - Nevis PKCS11 Cryptoki Wrapper

PSTOK5 WRAPPER SOFTTOKEN ENVIRONMENT VARIABLES
The pstok5 wrapper softtoken, a cryptoki reinit wrapper, has
been developed to overcome some of the PKCS#11 constraints.
It supports threadsafeness, reinitialization after fork,
cryptoki session reuse after forking and signal safeness.
You enable the cryptoki reinit wrapper library
(libctreinitwrap) by specifying it as option 'library' in
the PKCS#11 object specification string. The actual cryptoki
library you want to use should then be specified in the
environment variable PKCS11_LIBRARY.

The following environment variables are supported by the
pstok5 wrapper softtoken:

PKCS11_BLOCKSIGNALS
Specifies whether to block most signals while in PKCS#11
calls.

Sample: PKCS11_BLOCKSIGNALS=true

PKCS11_LIBRARY
Specifies the PKCS#11 library (libcryptoki) to be
proxed.

Sample: PKCS11_LIBRARY=.../libcryptoki.so

PKCS11_REINIT
Specifies whether to try to re-init PKCS#11 library on
fork.

Sample: PKCS11_REINIT=true

PKCS11_SAVESESSION
Specifies whether to save (shield) cryptoki sessions.

Sample: PKCS11_SAVESESSION=true

PKCS11_SERIALIZETHREADS
Specifies whether to serialize threads.

Sample: PKCS11_SERIALIZETHREADS=true

PKCS11_FORCE_INITIALISATION
Calls the C_Finalize/C_Initialize methods if the
C_Initialize function call returns
CKR_CRYPTOKI_ALREADY_INITIALIZED ensuring that the
library get reinitialized.

Sample: PKCS11_FORCE_INITIALISATION=true

PKCS11_RETRY_AUTO_RECOVERY
Library tries to recover from device errors if the
C_Sign function call returns a "device error" by doing
a reinitialization.

Sample: PKCS11_RETRY_AUTO_RECOVERY=true

You may configure these variables within the nevisProxy instance's env.conf file. The following example defines the vendor's PKCS 11 library as well as several options to enable fault tolerance:

PKCS11_LIBRARY=/usr/lunasa/lib/libCryptoki2_64.so
export PKCS11_LIBRARY
PKCS11_SAVESESSION=true
export PKCS11_SAVESESSION
PKCS11_REINIT=true
export PKCS11_REINIT
PKCS11_FORCE_INITIALISATION=true
export PKCS11_FORCE_INITIALISATION
PKCS11_RETRY_AUTO_RECOVERY=true
export PKCS11_RETRY_AUTO_RECOVERY

Tracing:
to enable tracing, you have to set the following tracegroups:

if used on the frontend (navajo.xml):
BC.Tracer.DebugProfile.NavajoSSL=4

if used on the backend (HttpsConnectorServlet, BackendConnectorServlet):
bcx.net.debug.host=all
bcx.net.debug=handshake,record,ssl
BC.Tracer.DebugProfile.OpenSSLHandshk=4
BC.Tracer.DebugProfile.OpenSSLRecord=4
BC.Tracer.DebugProfile.OpenSSLStream=4

The PKCS#11 Cryptoki Trace Wrapper
The library navajo_pkcs11_wrapper_so can be configured to trace
all HSM-function calls. It can be useful to see what happens if some
problem occurs.
The library navajo_pkcs11_wrapper_so can be used like this:
For bc-applications (like navajo):

replace the library configured in the pkcs11-urls with
navajo_pkcs11_wrapper_so, configure the tracegroup NavajoPkcs11 to 4 and
add the bc-property ch.nevis.navajo.pkcs11.library setting it to the
library which was configured originally.

For ex:
SSLCertificateKeyFile="pkcs11:library=/usr/safenet/lunaclient/lib/libCryptoki2
_64.so&dologin=true"

gets to:
SSLCertificateKeyFile="pkcs11:library=/opt/nevisproxy/lib/libnavajo_pkcs11_wrap
per_so.so.1&dologin=true"
and this property in bc.properties:
ch.nevis.navajo.pkcs11.library=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
BC.Tracer.DebugProfile.NavajoPkcs11=4

For not bc-applications (like openssl, only for OpenSSL 1.0.2):

replace the library configured in the pkcs11-urls with navajo_pkcs11_wrapper_so.
In the directory where you start the binary add a file called bc.properties. This
file should contain at least those entries:
ch.nevis.navajo.pkcs11.library=<the original library>
BC.Tracer.LogFile=<the logfile, where the output should be logged>

For ex:
/opt/nevisproxy/bin/openssl s_server -cert
'pkcs11:library=/usr/safenet/lunaclient/lib/libCryptoki2_64.so&dologin=true' -
www

gets to:
/opt/nevisproxy/bin/openssl s_server -cert
'pkcs11:library=/opt/nevisproxy/lib/libnavajo_pkcs11_wrapper_so.so.1&dologin=true'
-www
and in the bc.properties you have this:
ch.nevis.navajo.pkcs11.library=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
BC.Tracer.LogFile=pkcs11.log

Note: the navajo_pkcs11_wrapper_so and the libctreinitwrap can't be mixed. There is no need to mix them, because the libctreinitwrap does the same tracing as well.