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.