Run the SEE jobs of the Authentication Suite Server SDK SEE machine

  • Published on Feb 12, 2026
  • 4 minute(s) read
Prev Next

Authentication Suite Server SDK for Entrust nShield HSM is based on two different modules, a host module (host API) and an Authentication Suite Server SDK HSM module (the Authentication Suite Server SDK SEE machine).

The Authentication Suite Server SDK SEE machine provides 3 SEE jobs that you need to use when integrating Authentication Suite Server SDK for Entrust nShield HSM:

  • see_VC_loadkey: Use this job to load an HSM key into the SEE machine.

  • see_VC_cmd: Use this job to execute an Authentication Suite Server SDK command transaction.

  • see_VC_removekeys: Use this job to unload all keys previously loaded with see_VC_loadkey.

These SEE jobs must be executed using the nCore command Cmd_SEEJob and the Transact routine of the nCore HSM host API (NFastApp_Transact() method in C, or transact() method of an NFConnection in Java). The 3 SEE jobs have different input and output parameters.

see_VC_loadkey

This SEE job is used to load a key ticket of an HSM key (HSM storage key, HSM transport key, or HSM issuer master key) into a started Authentication Suite Server SDK SEE machine.

Each time the SEE machine is started, all the HSM keys required later (to perform Authentication Suite Server SDK command transactions in the integrator application) need to be loaded first into the Authentication Suite Server SDK SEE machine using the see_VC_loadkey SEE job of SEE machine.

To load an HSM key into the Authentication Suite Server SDK SEE machine, the integrator application that will load the key needs to obtain the key ticket of an HSM key located on the host computer, and to load it with the see_VC_loadkey SEE job.

The see_VC_loadkey SEE job must contain the following input job bytes:

  • 1 byte containing the see_VC_loadkey command code (0x00)

  • 4 bytes containing the OneSpan key ID (32-bit integer little-endian encoded)

  • x bytes containing the HSM key ticket to load. The size is typically 64 bytes.

Figure: Input job bytes for see_VC_loadkey

The Authentication Suite Server SDK SEE machine can use up to 11 loaded keys at the same time. Once loaded into the SEE machine, the following correspondence will apply between the OneSpan key ID used to load a key, and the Key Name to be used with the Authentication Suite Server SDK host API functions:

OneSpan key ID 0 : "vascoStorageKey"

OneSpan key ID 1 to 9 : "vasco1" to "vasco9"

OneSpan key ID 0x7FFFFF : "vascoTransportKey"

The OneSpan key ID must be little-endian encoded in the input job bytes. It can be between 0 and 9, or 0x7FFFFF.

The see_VC_loadkey SEE job produces the following output reply bytes:

  • 4-bytes containing the return code (32 bit integer little-endian encoded)

Figure: Output reply bytes for see_VC_loadkey

Possible return code values are 0 in case of load key success, and -1 in case of failure. The return code is little-endian encoded in the output reply bytes.

see_VC_cmd

The Authentication Suite Server SDK for HSM functionalities are categorized as follows:

  • Functionalities that do not use the HSM

  • Functionalities that use the HSM and HSM keys

The functionalities related to the HSM are based on two Authentication Suite Server SDK functions. The first function generates a command for the Authentication Suite Server SDK SEE machine, the second function processes the HSM reply returned by the Authentication Suite Server SDK SEE machine.

With the see_VC_cmd job, a Authentication Suite Server SDK command message is sent to the SEE machine. The AS command message is a buffer generated by the AS host API function AAL2GenxxxxCmd of Authentication Suite Server SDK for HSM. As a result, the SEE job returns an AS reply message, which is a buffer generated by the SEE machine and needs to be processed by the AS host API function AAL2ProcxxxxRpl of Authentication Suite Server SDK for HSM.

The functionalities related to the HSM need one or more HSM keys to work. You need to ensure that the proper HSM key(s) have been loaded into the Authentication Suite Server SDK SEE machine (using the see_VC_loadkey).

HSM keys used by Authentication Suite Server SDK for HSM are either HSM storage keys and/or HSM transport keys in case of authenticator applications.

The see_VC_cmd SEE job must contain the following input job bytes:

  • 1 byte containing the see_VC_cmd command code (0x01)

  • x bytes containing the Authentication Suite Server SDK command

Figure: Input Job Bytes for see_VC_cmd

The see_VC_cmd SEE job produces the following output reply bytes:

  • x-bytes containing the Authentication Suite Server SDK reply

Figure: Output Reply Bytes for see_VC_cmd

see_VC_removekeys

With the see_VC_removekeys SEE job, all the HSM keys that were loaded with the see_VC_loadkey SEE job are unloaded from the started Authentication Suite Server SDK SEE machine.

If the SEE machine is restarted, the HSM keys are implicitly unloaded.

The see_VC_removekeys SEE job must contain the following input job bytes:

  • 1 byte containing the see_VC_removekeys command code (0x02)

Figure: Input Job Bytes for see_VC_removekeys

The see_VC_removekeys SEE job produces the following output reply bytes:

  • 4 bytes containing the return code (32 bit integer little-endian encoded)

Figure: Output Reply Bytes for see_VC_removekeys

Possible return code values are 0 in case of remove keys success, or -1 in case of failure. The return code is little-endian encoded in the output reply bytes.