Before using the Authentication Suite Server SDK SEE machine

Before you can use the Authentication Suite Server SDK SEE machine signed by OneSpan, you need to complete the steps outlined in this section.

Getting ready for using the Authentication Suite Server SDK SEE machine

Complete these steps to be able to upload the SEE machine to the HSMs.

To prepare for SEE machine upload

1. Generate your own SEE code signing key (e.g. seesigningkey) that will be used to sign the userdata.sar file required to start the SEE machine. You can use the KeySafe tool or the following command line to generate the SEE code signing key:

   generatekey --generate seeinteg type=rsa size=2048 pubexp= recovery=yes nvram=no plainname=seesigningkey

   The SEE code signing key used to sign the userdata.sar file should never be changed.

   Indeed, all the OneSpan keys (HSM storage keys, HSM transports keys) generated by the manager tool are protected by this SEE code signing key. (The manager tool uses on startup the userdata.sar file located in the nfast key management directory).

   In case you need to change this SEE code signing key and sign the userdata.sar with a new SEE code signing key, the OneSpan keys previously generated can no longer be used with the Authentication Suite Server SDK SEE machine that uses on startup the userdata.sar file signed with the new SEE code signing key. By extension, all the Digipass BLOB records or DPX files encrypted under the former OneSpan keys will also be unusable.

2. Copy the signed SEE machine seemach_ppc.sar provided by OneSpan to the client machine that will load the SEE machine in the nfast key management data directory.

   Windows:

   copy seemach_ppc.sar "%NFAST_KMDATA%"

   Unix:

   cp seemach_ppc.sar ${NFAST_HOME}/kmdata

   Copying and using the signed SEE machine seemach_ppc.sar located in the INSTALL_DIR/hsm/ppc directory of the Authentication Suite Server SDK for Entrust nShield HSM package applies only if you are using Entrust nShield HSMs based on the former PowerPCSXF architecture (Entrust nShield Connect/Connect+/Solo/Solo+).

   If you are using a new Entrust nShield XC HSM based on the new PowerPCELF architecture (Entrust nShield Connect XC/Solo XC), the signed SEE machine seemach_ppc-xc.sar located in the INSTALL_DIR/hsm/ppc-xc directory of the Authentication Suite Server SDK for Entrust nShield HSM package must be copied and used instead. Note that this SEE machine for the Entrust nShield XC HSMs is only shipped with the Windows 64-bit and Linux 64-bit versions of Authentication Suite Server SDK for Entrust nShield HSM.

3. Sign and package the user data.

   1. Generate a dummy userdata file userdata.dat (dummy content because the Authentication Suite Server SDK SEE machine does not use any initialization parameter on startup).

      echo 'Dummy data' > userdata.dat

   2. Generate the signature file userdata.sig of the userdata.dat file using its ‘seesigningkey’ and indicate the hash of the OneSpan signing key that OneSpan has used to sign the SEE machine. The value of the hash is enclosed in the seemach_hash.txt file shipped along with the SEE machine.

   3. tct2 sign key=seesigningkey machine key=c15cb991531e553d2b5abd536afb1638ad475b57 module=<moduleID> outfile=userdata.sig infile=userdata.dat

   3. Generate the signed user data file userdata.sar by packing together userdata.dat and userdata.sig, and copy it in the nfast key management data directory on the client machine that will start the SEE machine or that will generate OneSpan keys with the manager tool.

   4. Windows:

      tct2 pack module=<moduleID> outfile="%NFAST_KMDATA%\userdata.sar" infile=userdata.dat sigfile=userdata.sig

      Unix:

      tct2 pack module=<moduleID> outfile=${NFAST_HOME}/kmdata/userdata.sar infile=userdata.dat sigfile=userdata.sig

      The process of signing and packing the user data to obtain a userdata.sar file (step 2) does not have to be performed each time a new signed Authentication Suite Server SDK SEE machine is used. As long as the OneSpan signing key that OneSpan uses to sign the SEE machine does not change, the generated userdata.sar file will remain valid for future SEE machines signed by OneSpan with the same signing key.

4. In the case that HSMs have the SEE restricted activation (ROW) feature enabled, copy the ADDER certificate file seemach.cert provided by OneSpan to the client machine that will load the SEE machine, in the ${NFAST_HOME}/femcerts directory (in case of Unix) or %NFAST_CERTDIR% directory (in case of Windows), e.g.:

   Windows:

   copy seemach.cert "%NFAST_CERTDIR%"

   Unix:

   cp seemach.cert ${NFAST_HOME}/femcerts

   The copy of the ADDER certificate seemach.cert in the nfast feature certificates directory (step 4), is only necessary for HSMs that have the SEE restricted activation (ROW) feature enabled. Such HSMs with SEE restricted activation feature require to have in this directory the ADDER certificate of the signed Authentication Suite Server SDK SEE machine to upload the SEE machine from that client machine.

   For HSMs that have the SEE unrestricted activation (EU+10) feature, importing the ADDER certificate is not necessary as the HSMs accept loading any SEE machine without further certificates or authorization.

   Steps 2 to 4 are demonstrated in the build_userdata script provided in the Authentication Suite Server SDK for Entrust nShield HSM package.