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.