nCore API commands

This chapter describes the complete nShield command set. It is divided into the following sections:

Basic commands

These commands are available on all nShield modules. They do not offer any key-management functionality
Key-management commands

These commands are only available on nForce and nShield modules.
Commands used only by the generic stub

These commands are included for information only. You should not need to call them directly. Commands are listed alphabetically within each section. For each command, the following information is listed:
the command name
the states in which the command can be issued
the required inputs
the expected output

If the module is unable to complete a requested command due to a non-fatal condition, such as lack of memory or an unknown command, the module sends a response with no reply data. The reply’s cmd value is sent to Cmd_ErrorReturn with the condition indicated by the status word that was returned in the header.

Unless specified otherwise, there is a limit of 8K on the total message that can be sent to the nShield server for each command, or in reply. This means that the maximum length of any byteblock sent for processing must be somewhat less that 8K.

Basic commands

The following basic commands, described in this section, are available on all nShield modules:

ClearUnit
ClearUnitEx
ModExp
ModExpCrt

These commands perform cryptographic acceleration without key management.

These commands are intended for use by applications that manage their own keys.

ClearUnit

All non-error states

"Privileged" users only

This command resets a module, returning it to the same mode that it was previously in. The module and server negotiate to enable the module to be reset without disturbing the host’s PCI subsystem. When the module is cleared:

all object handles (ID_KA, ID_KT, etc.) are invalidated
any share reassembly process that is currently active is aborted
the module enters the self-test state.

ClearUnit does not destroy:

module keys K_M
module signing key K_ML
long-term fixed signing key K_LF
nShield Security Officer’s key K_NSO.

Arguments

struct M_Cmd_ClearUnit_Args {
   M_ModuleID module;                                   ModuleID
};

Reply

The reply structure for this command is empty.

The status is Status_OK or, if the unit is already being reset, Status_UnitReset. The reply is sent immediately (that is, before the unit is actually cleared).

Notes

In versions of the server prior to 1.40, the ClearUnit command caused a hard reset. In release 1.40, the ClearUnit command was given a new command number, and the old command number was renamed OldClearUnit, which is included for backward compatibility only. From release 1.40, servers interpret ClearUnit and OldClearUnit as ClearUnit. The ClearUnit command fails with Status_UnknownCommand on servers older than release 1.40.

ClearUnitEx

All non-error states

"Privileged" users only

This command resets a module, and optionally enables you to change the mode as required. ClearUnitEx is implemented entirely by the hardserver, which:

Checks and sets the scratchpad registers
Sets a want clear state on the command target

Further behavior is identical to the ClearUnit command, including sending ClearUnit (not ClearUnixEx) to the module. See ClearUnit for more about the ClearUnit command.

Arguments

bitmap:                         flags
       harmless: 16-
ModuleID                        module       [<module to be reset>]
ModuleMode                      mode         [<desired module mode>]

Flags are not currently used.

Module mode settings

The following desired module mode settings are available:

ModuleMode Default =0
ModuleMode Maintenance =1
ModuleMode Operational =2
ModuleMode Initialisation =3

Reply

The ModuleMode value in the reply corresponds to the bit field in scratchpad 0.
If the module is already part way through a reset, then @ref Status_UnitReset is returned.
If the request cannot be completed because the main application of the module does not support software mode changes, then @ref Status_ModuleApplicationNotSupported is returned.
If the request cannot be completed because the module monitor does not support software mode changes, then @ref Status ModuleMonitorNotSupported is returned.

Firmware releases prior to v12 do not support changing the mode without use of the MOI switch. The mode argument must be 0. With the appropriate firmware, the mode argument can be used to change the mode.

ModExp

Operational state

initialization state

This command performs modular exponentiation on parameters passed by the client.

Arguments

struct M_Cmd_ModExp_Args {
  M_Bignum a;                          A base
  M_Bignum p;                          P power
  M_Bignum n;                          N modulus
};

Reply

struct M_Cmd_ModExp_Reply {
M_Bignum r;
};

where r = A^Pmod N

ModExpCrt

Operational state

initialization state

This command performs modular exponentiation on parameters passed by the client. ModExpCrt uses the Chinese Remainder Theorem to reduce the time it takes to perform the operation.

Arguments

struct M_Cmd_ModExpCrt_Args {
   M_Bignum a;                      A base
   M_Bignum p;                      P modulus larger factor
   M_Bignum q;                      Q modulus smaller factor
   M_Bignum dmp1;                   D mod (P-1)
   M_Bignum dmq1;                   D mod (Q-1)
   M_Bignum iqmp;                   Q-1 mod P
};

Reply

Uses M_Cmd_ModExp_Reply.

Notes

It is assumed that P >= Q.

Key-management commands

The commands described in this section, are only available on key-management modules.

If you send any of these commands to an acceleration-only module, it fails with the status value Status_InvalidState.

ChangeSharePIN

Operational state

initialization state

This command enables a PIN that protects a single share to be changed. The old PIN must be provided unless the share has no PIN. Likewise, the new PIN must be provided unless the PIN is being removed.

The module decrypts the share using the old PIN and the K_M associated with the token. If the share is decrypted correctly, the module encrypts it using the new PIN and the K_M. It then writes the newly encrypted share to the smart card or software token.

This operation can be performed regardless of whether or not the logical token associated with this share is "present". The only requirement is that both the smart card with the share and the K_M associated with the token be present within the module.

Arguments

struct M_Cmd_ChangeSharePIN_Args {
   M_Cmd_ChangeSharePIN_Args_flags flags;
   M_PhysToken token;
   M_KMHash hkm;
   M_ShortHash hkt;
   M_Word i;
   M_PIN *oldpin;
   M_PIN *newpin;
};

The following flags are defined:
- Cmd_ChangeSharePIN_Args_flags_oldpin_present
  
  Set this flag if the input contains the old PIN. The old PIN must be specified unless the share was previously encrypted without a PIN or if the share uses the protected PIN path.
- Cmd_ChangeSharePIN_Args_flags_newpin_present
  
  Set this flag if the input contains the new PIN. The new PIN must be specified unless the share is to be encrypted without a PIN or if the share uses the protected PIN path.
- Cmd_ChangeSharePIN_Args_flags__allflags
M_KMHash hkm is Module key hash H_KM
M_ShortHash hkt is a short, 10-byte token hash, such as returned by GetSlotInfo.
M_Word i is the share number
M_PIN *oldpin is the old PIN, or NULL
M_PIN *newpin is the new PIN, or NULL

Reply

The reply structure for this command is empty.

ChannelOpen

Operational state, initialization state

Requires a ClientID

This command opens a communication channel that can be used for bulk encryption. Data can then be transferred over this channel by using the ChannelUpdate command.

Channel operations are only available for symmetric algorithms.

Arguments

typedef struct {
   M_ModuleID module;
   M_ChannelType type;
   M_Cmd_ChannelOpen_Args_flags flags;
   M_ChannelMode mode;
   M_Mech mech;
   M_KeyID *key;
   M_IV *given_iv;
} M_Cmd_ChannelOpen_Args;

M_ChannelType type is the data transfer mechanism for the channel. At present, only ChannelType_Simple is supported. Alternatively, ChannelType_Any can be used to let the module pick the"best" channel type that it supports.
```
ChannelType_Any
ChannelType_Simple
```
M_Cmd_ChannelOpen_Args_flags flags The following flags are defined:
- Cmd_ChannelOpen_Args_flags_key_present
  
  Set this flag if the command contains a KeyID. The command must include a KeyID unless you are using a hashing mechanism.
- Cmd_ChannelOpen_Args_flags_given_iv_present
  
  Set this flag if the command designates which initialization vector to use. For encryption and signature mechanisms, if this flag is not set and the mechanism requires an initialization vector, the module will create a random iv and return it in the reply. For decryption and verification mechanisms, this flag must be set and the M_IV must be specified or Status_InvalidParameter will be returned.
M_ChannelMode mode determines the operation to perform on this channel. The following modes are defined:
- ChannelMode_Encrypt
- ChannelMode_Decrypt
- ChannelMode_Sign
- ChannelMode_Verify
M_Mech mech is the mechanism to use. See Mechanisms for information on supported mechanisms.
M_KeyID *key is the KeyID of the key to use on the channel. The key must have the appropriate Encrypt, Decrypt, Sign, or Verify permissions in its ACL. It must also be an appropriate type for the given mechanism. In order to use unkeyed hash mechanisms, this key field must be absent.
M_IV *given_iv is the initialization vector to use on the channel. This field is optional for the Encrypt and Sign modes, but it must be given for the Decrypt and Verify modes. Status_InvalidParameter is returned if this field is not present when it is required or if it has an incorrect mechanism.

Reply

typedef struct {
M_Cmd_ChannelOpen_Reply_flags flags;
M_KeyID idch;
M_IV *new_iv;
M_ChannelOpenInfo openinfo;
} M_Cmd_ChannelOpen_Reply;

M_Cmd_ChannelOpen_Reply_flags flags

The following flag is defined: Cmd_ChannelOpen_Reply_flags_new_iv_present. This flag is set if the new_iv field is present.
M_KeyID idch is the ID of the Channel. It is like a KeyID; it may be used to refer to the channel and can be destroyed with the Destroy command after use. However, it will be different to the KeyID.

The server will destroy the channel automatically when the last connection associated with the application that created it closes.
M_IV *new_iv is an initialization vector for the channel. It is returned only if the channel mode is Encrypt or Sign and no given_iv has been sent with the command.

M_ChannelOpenInfo openinfo is extra information about the channel:

struct M_ModuleChannelOpenInfo {
M_ChannelType type;
union M_ChannelType__ExtraMCOI info;
};

M_ChannelType type is the channel type used.
union M_ChannelType__ExtraMCOI info is extra information that is dependent on the channel type. It allows the client to access a device driver, if necessary, in order to perform data transfer.

ChannelUpdate

Operational state, initialization state

Requires a ClientID

This command transfers data over a communication channel for bulk encryption. Such a channel must be opened with the ChannelOpen command before the ChannelUpdate command can be used.

Channel operations are only available for symmetric algorithms.

Data is streamed into an open channel by giving one or more Update commands. The last data block to be processed should have the final flag set. This final block does not have to contain any input data (except in Verify mode; see below). Input data does not have to be multiples of the block size for block ciphers; the module will buffer the data internally as necessary. In general, the output block will contain all the data that can be encrypted/decrypted unambiguously given the input so far. However, PKCS #5 padding usually lags behind by a block when decrypting.

For decryption—and for encryption in non-padding modes—you must have supplied a whole number of input blocks. Otherwise, a status of Status_EncryptFailed or Status_DecryptFailed will be returned. Status_DecryptFailed is also used if unpadding fails during decryption.

For signing modes, no output will be generated until the final bit is set, in which case the signature or hash will be output as the byte block.

For verification modes, no output is generated. Instead, the plain text message must be input by ChannelUpdate commands with their final bit clear, then a ChannelUpdate with the final bit set is given, with the signature/hash bytes given as the input block. This will return a status of OK or VerifyFailed, as appropriate.

Arguments

struct M_Cmd_ChannelUpdate_Args {
   M_Cmd_ChannelUpdate_Args_flags flags;
   M_KeyID idch;
   M_ByteBlock input;
};

The following flag is defined: Cmd_ChannelUpdate_Args_flags_final. This flag indicates the last block of input data.
M_KeyID idch is the ChannelID returned by ChannelOpen.
M_ByteBlock input is a byte block of input data (it may be of zero length)

Reply

struct M_Cmd_ChannelUpdate_Reply {
    M_ByteBlock output;
};

M_ByteBlock output is a byte block containing output data from the channel. This block may be of zero length.

Decrypt

Operational state, initialization state

Requires a ClientID

This command takes a cipher text and decrypts it with a previously stored key.

The limit of 8K does not apply to data decrypted by this command. This is because the Generic Stub library splits the command into a ChannelOpen command followed by a number of ChannelUpdate commands. Only symmetric mechanisms use channels; asymmetric mechanisms cannot.

For information on formats, see Encrypt.

Arguments

struct M_Cmd_Decrypt_Args {
   M_Cmd_Decrypt_Args_flags flags;
   M_KeyID key;
   M_Mech mech;
   M_CipherText cipher;
   M_PlainTextType reply_type;
};

No Flags are defined.
M_KeyID key is ID_KA.
M_Mech mech: See Mechanisms for information on supported mechanisms. If mech is not Mech_Any, then it must match the mechanism of the ciphertext, cipher.mech. If it does not match, then a MechanismNotExpected error is returned.

Reply

struct M_Cmd_Decrypt_Reply {
   M_PlainText plain;
}

DeriveKey

Operational state, initialization state

Requires a ClientID

This command creates a new key object from a number of other keys that have been stored already on the module. Then, DeriveKey returns a KeyID for the new key.

There are two special key types used by DeriveKey:

a template key — the template is used to provide the ACL and application data for the output key
a wrapped key — a key type for holding encrypted keys.

Arguments

struct M_Cmd_DeriveKey_Args {
   M_Cmd_DeriveKey_Args_flags flags;
   M_DeriveMech mech;
   int n_keys;
   M_vec_KeyID keys;
   union M_DeriveMech__DKParams params;
} M_Cmd_DeriveKey_Args;

The following flag is defined: Cmd_DeriveKey_Args_flags_WorldHashMech Indicates that the hash mechanism for Security World keys will be used for identifying keys. By enabling the Cmd_DeriveKey_Args_flags_WorldHashMech flag, keys shall be identified by the selected world hash mechanism. See DeriveKey and DeriveKeyEx.
M_DeriveMech mech

See Derive Key Mechanisms for information on supported mechanisms.
int n_keys

This value is the number of keys that have been supplied in the key table.
M_vec_KeyID keys

This is a table containing the KeyIDs of the keys that are to be used. You must enter the KeyIDs of these keys in the following order:
1. template key
2. base key
3. wrapping key(s)
Each key must be of the correct type for the mechanism.

Each of these keys must have an ACL that permits them to be used for DeriveKey operations in this role.

Any of the keys may have an ACL that requires a certificate. If more than one of the keys requires a certificate, then all the certificates must have the same signing key.
union M_DeriveMech__DKParams params

Parameters for the specific wrapping mechanism. See Derive Key Mechanisms.

union M_DeriveMech__DKParams {
 M_DeriveMech_ConcatenationKDF_DKParams concatenationkdf;
M_DeriveMech_PKCS8Encrypt_DKParams pkcs8encrypt;
M_DeriveMech_PKCS8Decrypt_DKParams pkcs8decrypt;
M_DeriveMech_RawDecrypt_DKParams rawdecrypt;
M_DeriveMech_AESKeyWrap_DKParams aeskeywrap;
M_DeriveMech_AESKeyUnwrap_DKParams aeskeyunwrap;
M_DeriveMech_RawDecryptZeroPad_DKParams rawdecryptzeropad;
M_DeriveMech_ECCMQV_DKParams eccmqv;
M_DeriveMech_ECDHKA_DKParams ecdhka;
M_DeriveMech_ECIESKeyUnwrap_DKParams ecieskeyunwrap;
M_DeriveMech_ECIESKeyWrap_DKParams ecieskeywrap;
M_DeriveMech_ConcatenateBytes_DKParams concatenatebytes;
M_DeriveMech_RawEncrypt_DKParams rawencrypt;
M_DeriveMech_NISTKDFmCTRpRijndaelCMACr32_DKParams nistkdfmctrprijndaelcmacr32;
M_DeriveMech_RawEncryptZeroPad_DKParams rawencryptzeropad;
};

Reply

struct M_Cmd_DeriveKey_Reply {
   M_KeyID key;
};

The M_KeyID points to the derived key. The ACL and application data for this key are the ACL and application data that have been stored as the key data of the template key. The key type is defined by the mechanism used. The key data is determined by the base key, the wrapping key (or wrapping keys), and the mechanism.

Notes

The key derivation mechanisms provide a means of converting keys of many different types into KeyType_Wrapped and then back again. The type of the original key is usually not preserved in the Wrapped data format (the EncryptMarshalled mechanism does preserve type).

Therefore, one key may be converted to another of a different type by unwrapping it with a different mechanism. Indeed, the key data itself may be modified by unwrapping it with a different key.

This feature is provided to increase flexibility and interoperability, which is a major goal of the DeriveKey command. However, it can be a potential weak point in security. Therefore, Entrust recommends that whenever a base key is turned into a Wrapped key type, if the new key is to be used within the nShield environment, the ACL for the new key be set only to allow decoding back to the original key. This is done by setting the DeriveKey ACL entry in the wrapped key so that:

the mech field identifies the correct decoding mechanism
the otherkeys table identifies the correct unwrapping key in the right role.

Destroy

Operational state, initialization state

Requires a ClientID

This removes a key object from memory and zeroes any storage associated with it.

This command can be used to destroy:

a key object by specifying an ID_KA
a logical token by specifying an ID_KT
a ModuleSEEWorld by specifying a KeyID
an impath by specifying an ImpathID
an FTSessionID or FileTransferID
a channel
a foreign token lock
multiple objects that were previously merged by means of MergeKeyIDs. Only the merged KeyID is removed; the underlying keys remain loaded.

When an object has multiple KeyIDs, Destroy only removes the KeyID for the current ClientID or SEEWorld. The underlying object is removed when the last KeyID for the object is destroyed.

It is an error to Destroy an ID_KA that has not been issued previously by the nShield server or that has already been destroyed.

An ID_KA may be reused for a new object after the current object is destroyed.

A key that forms part of a merged set made with MergeKeyIDs (see MergeKeyIDs) cannot be destroyed. Attempts to do so will return an ObjectInUse error. Destroy the merged KeyID first.

Arguments

struct M_Cmd_Destroy_Args {
M_KeyID key;
};

M_KeyID key can be any object with an M_KeyID, such as an ID_KA, an ID_KT, or the SEE World’s KeyID.

Reply

The reply structure for this command is empty.

Duplicate

Operational state, initialization state

Requires a ClientID

This command duplicates a key object within module memory and returns a new handle to it. The new key object can then be manipulated independently of the original key object.

The new key inherits its ACL from the original key.

Arguments

struct M_Cmd_Duplicate_Args {
   M_KeyID key;
};

M_KeyID key is ID_KA.

Reply

struct M_Cmd_Duplicate_Reply {
   M_KeyID newkey;
};

M_KeyID newkey is ID_KA2.

Encrypt

Operational state, initialization state

Requires a ClientID

This command encrypts data by using a previously loaded key. It returns the cipher text.

The limit of 8K does not apply to data encrypted by this command. This is because the Generic Stub library splits the command into a ChannelOpen command followed by a number of ChannelUpdate commands. Only symmetric mechanisms use channels; asymmetric mechanisms cannot.

Arguments

struct M_Cmd_Encrypt_Args {
   M_Cmd_Encrypt_Args_flags flags;
   M_KeyID key;
   M_Mech mech;
   M_PlainText plain;
   M_IV *given_iv;
};

The following flag is defined:

Cmd_Encrypt_Args_flags_given_iv_present

This flag must be set if the command includes the initialization vector. If this flag is not set, the module will generate a random initialization vector if one is required by this mechanism.
M_KeyID key is ID_KA.
M_Mech mech

See Mechanisms for information on supported mechanisms. If Mech_Any is specified and an IV is given, the mechanism is taken from that IV. Otherwise, if Mech_Any is not specified, the given mechanism is used. Moreover, if an IV is given, its mechanism must match the given mechanism, otherwise Status_MechanismNotExpected will be returned.
M_IV *given_iv

This can be either the IV to use or otherwise NULL if no IV is defined or if you prefer that the module choose an IV on its own.

Reply

struct M_Cmd_Encrypt_Reply {
   M_CipherText cipher;
};

Export

Operational state, initialization state

Requires a ClientID

This command is used to extract key material in plain text.

Most private key objects should have an ACL (or ACLs) that forbid the reading of this data in plain text.

Arguments

struct M_Cmd_Export_Args {
   M_KeyID key;
};

Reply

struct M_Cmd_Export_Reply {
   M_KeyData data;
};

FirmwareAuthenticate

Operational state, initialization state, maintenance state

This command is used to authenticate the firmware in a module by comparing it to a firmware image on the host. If performed in the maintenance state it can be used to authenticate the monitor.

Use the fwcheck command-line utility to perform this operation.

FormatToken

Operational state, initialization state

May require a KNSO certificate

This command initializes a smart card.

Arguments

struct M_Cmd_FormatToken_Args {
M_Cmd_FormatToken_Args_flags flags;
M_PhysToken token;
M_KMHash *auth_key;
};

The following flag is defined:

Cmd_FormatToken_Args_flags_auth_key_present

Set this flag if the input includes a module key hash to use for challenge-response authentication. This flag can only be used if the smart card supports authentication.
M_KMHash *auth_key is the H_KM of a module key or a NULL pointer. The module key is combined with the unique identity of the token to produce the key to be used for challenge-response authentication.

Reply

The reply structure for this command is empty.

GenerateKey and GenerateKeyPair

Operational state, initialization state

Requires a ClientID

May require a KNSO certificate

The GenerateKey command randomly generates a key object of the given type and with the specified ACL (or ACLs) and stores it in internal RAM.

The GenerateKeyPair command randomly generates a matching public and private key pair.

Use GenerateKey for symmetric algorithms.

For public-key algorithms, use GenerateKeyPair.

Arguments

struct M_Cmd_GenerateKey_Args {
   M_Cmd_GenerateKey_Args_flags flags;
   M_ModuleID module;
   M_KeyGenParams params;
   M_ACL acl;
   M_AppData *appdata;
};

struct M_Cmd_GenerateKeyPair_Args {
   M_Cmd_GenerateKeyPair_Args_flags flags;
   M_ModuleID module;
   M_KeyGenParams params;
   M_ACL aclpriv;
   M_ACL aclpub;
   M_AppData *appdatapriv;
   M_AppData *appdatapub;
} M_Cmd_GenerateKeyPair_Args;

The following flags are defined:
- Cmd_GenerateKey_Args_flags_Certify
  
  If this flag is set, the reply will contain a certificate of data type ModuleCert that describes the security policy for this key or key pair. This certificate enables an observer, such as an organization’s Security Officer or a certificate authority, to check that the key or key pair was generated in compliance with a stated security policy before they allow the key to be used. The certificate contains:
  
  H_KA for the key
  
  the application data field or fields
  
  the ACL (or ACLs)
  
  The certificate is signed by the module’s private key.
- Cmd_GenerateKey_Args_flags_appdata_present
  
  You must set this flag if the request contains application data for the symmetric key.
- Cmd_GenerateKey_Args_flags_PairwiseCheck
  
  If this flag is set, the module performs a consistency check on the key by creating a random message, then encrypting and decrypting this message. The test fails if the encrypted message is the same as the plain text or if the encrypted message fails to decrypt to the plain text.
- Cmd_GenerateKeyPair_Args_flags_Certify
- Cmd_GenerateKeyPair_Args_flags_appdatapriv_present
  
  You must set this flag if the request contains application data for the private key.
- Cmd_GenerateKeyPair_Args_flags_appdatapub_present
  
  You must set this flag if the request contains application data for the public key.
- Cmd_GenerateKeyPair_Args_flags_PairwiseCheck
M_ModuleID module

If the module ID is nonzero, the key is loaded onto the specified module. If the module ID is 0, the key is loaded onto the first available module. You can use the GetWhichModule command to determine which modules contain which keys).
M_KeyGenParams params

The key type and required parameters needed to generate this key or key pair are as follows:
```
struct M_KeyGenParams {
 M_KeyType type;
 union M_KeyType__GenParams params;
};
```
The following key types are defined:
- KeyType_ArcFour Use GenerateKey
- KeyType_Blowfish
- KeyType_CAST Use GenerateKey
- KeyType_CAST256
- KeyType_DES Use GenerateKey
- KeyType_DES2 Use GenerateKey
- KeyType_DES3 Use GenerateKey
- KeyType_DHPrivate Use GenerateKeyPair
- KeyType_DHPublic Do not use for key generation
- KeyType_DKTemplate
- KeyType_DSAComm Use GenerateKey
- KeyType_DSAPrivate Use GenerateKeyPair
- KeyType_DSAPublic Do not use for key generation
- KeyType_HMACMD2
- KeyType_HMACMD5
- KeyType_HMACRIPEMD160
- KeyType_HMACSHA1
- KeyType_HMACSHA256
- KeyType_HMACSHA384
- KeyType_HMACSHA512
- KeyType_HMACTiger
- KeyType_IDEA
- KeyType_KCDSAComm
- KeyType_KCDSAPrivate
- KeyType_KCDSAPublic
- KeyType_Random Use GenerateKey
- KeyType_RC2
- KeyType_RC5
- KeyType_Rijndael
- KeyType_RSAPrivate Use GenerateKeyPair
- KeyType_RSAPublic Do not use for key generation
- KeyType_SEED
- KeyType_Serpent
- KeyType_Skipjack
- KeyType_Twofish
- KeyType_Void KeyType_Wrapped Created by DeriveKey
- KeyType_Any Do not use for key generation
- KeyType_None Do not use for key generation
When generating a key pair, you must specify the key type for the private half of the key pair.

The following key types have key generation parameters:
```
union M_KeyType__GenParams {
M_KeyType_RSAPrivate_GenParams rsaprivate;
M_KeyType_DSAPrivate_GenParams dsaprivate;
M_KeyType_Random_GenParams random;
M_KeyType_DSAComm_GenParams dsacomm;
M_KeyType_DHPrivate_GenParams dhprivate;
M_KeyType_Wrapped_GenParams wrapped;
};
```
- M_KeyType_RSAPrivate_GenParams rsaprivate. See RSA.
- M_KeyType_DSAPrivate_GenParams dsaprivate. See DSA.
- M_KeyType_Random_GenParams random. See Random.
- M_KeyType_DSAComm_GenParams dsacomm. See DSA.
- M_KeyType_DHPrivate_GenParams dhprivate. See Diffie-Hellman and ElGamal.
- M_KeyType_Wrapped_GenParams wrapped. Generating a wrapped key creates a random key block — this may be useful in some key derivation schemes.
DES and Triple DES do not have any key generation parameters. ArcFour and CAST use the same parameters as the key type RANDOM. ElGamal uses key type Diffie-Hellman.
M_ACL acl

See ACLs.
M_AppData *appdata

This is application data. If the command contains application data, the appropriate flag must be set. If no appdata is provided, the appdata stored with the key is set to all-bits-zero.
M_ACL aclpriv

ACL for private half
M_ACL aclpub

ACL for public half
M_AppData *appdatapriv

appdata for private half.
M_AppData *appdatapub

appdata for public half.

Reply

struct M_Cmd_GenerateKey_Reply {
   M_Cmd_GenerateKey_Reply_flags flags;
   M_KeyID key;
   M_ModuleCert *cert;
};

struct M_Cmd_GenerateKeyPair_Reply {
   M_Cmd_GenerateKeyPair_Reply_flags flags;
   M_KeyID keypriv;
   M_KeyID keypub;
   M_ModuleCert *certpriv;
   M_ModuleCert *certpub;
};

The following flags are defined:
- Cmd_GenerateKey_Reply_flags_cert_present
- Cmd_GenerateKeyPair_Reply_flags_cert_present
  
  These flags are set if the reply contains a certificate or a certificate pair.
M_KeyID key is ID_KA.
M_ModuleCert *cert is a certificate that describes how the key was generated.
struct M_ModuleCert { M_CipherText signature; M_ByteBlock modcertmsg; };
struct M_ModCertMsg { M_ModCertType type; union M_ModCertType__ModCertData data; };
union M_ModCertType__ModCertData { M_ModCertType_KeyGen_ModCertData keygen; };
struct M_ModCertType_KeyGen_ModCertData { M_ModCertType_KeyGen_ModCertData_flags flags: M_KeyGenParams genparams; M_ACL acl; M_Hash hka; };
- M_ModCertType type From release 1.67.15 and later, this should be type KeyGen with code 2. The previous type, now called OldKeyGen, did not distinguish between public and private keys and should no longer be used
  
  The following flag is defined:
  
  ModCertType_KeyGen_ModCertData_flags_public
  
  Set this flag if this is the public half of a key pair.
- M_KeyGenParams genparams
  
  These are the key generation parameters to be used to generate this key.
- M_ACL acl
  
  This is the ACL that was applied to this key when it was created.
- M_Hash hka
  
  This is the SHA-1 hash of the key value.

Notes

If the Strict_FIPS140 flag was set in the SetKNSO command, GenerateKey or GenerateKeyPair will fail with status Status_StrictFIPS140 if you attempt to generate a secret key that can be exported as plain text. A secret key is any key that can have Sign or Decrypt permissions.

GenerateLogicalToken

Operational state, initialization state

Requires a ClientID

May require a KNSO certificate

This command generates a random token key K_T, associates it with the given properties and secret-sharing parameters (n and t), and encrypts it with the given module key that is identified by its hash, H_KM.

The result is stored internally, and an identifier ID_KT and a hash H_KT are returned. The token is referred to by its identifier in commands and by its hash in ACLs.

Arguments

struct M_Cmd_GenerateLogicalToken_Args {
   M_ModuleID module;
   M_KMHash hkm;
   M_TokenParams params;
};

M_ModuleID module

If the module ID is nonzero, the key is loaded onto the specified module. If the module ID is 0, the token is generated on the first available module.
M_KMHash hkm is the H_KM of the module key to use to protect this token. If you supply an all zero H_KM, the module will use the null module key.

Reply

struct M_Cmd_GenerateLogicalToken_Reply {
   M_KeyID idkt;
   M_TokenHash hkt;
};

M_KeyID idkt is ID_KT
M_TokenHash hkt is H_KT

GetChallenge

Operational state, initialization state

Requires a ClientID

The GetChallenge command returns a nonce that is used to build a fresh certificate. See Certificates. GetChallenge is also used during impath setup.

Arguments

struct M_Cmd_GetChallenge_Args {
   M_ModuleID module;
};

Reply

struct M_Cmd_GetChallenge_Reply {
   M_KMHash nonce;
};

GetKML

Operational state, initialization state

This command is used to retrieve a KeyID for the module’s long-term public key. This key is generated by InitialiseUnit and is held internally. K_ML has ACL permissions that allow it to be extracted as plain text, to be used to verify signatures, to view its own ACL, and to extend its ACL.

Arguments

struct M_Cmd_GetKML_Args {
   M_ModuleID module;
};

Reply

struct M_Cmd_GetKML_Reply {
   M_KeyID idka;
};

M_KeyID idka is ID_KA for K_ML

GetTicket

Operational state, initialization state

Requires a ClientID

This command gets a ticket for a specific KeyID. The ticket can then be passed to another client or to an SEE application, which can redeem the ticket for a KeyID in its name space.

Tickets can be single-use or permanent, and they can specify the destination.

The program should treat tickets as opaque objects. nShield reserves the right to change the structure of tickets at any time.

Arguments

struct M_Cmd_GetTicket_Args {
M_Cmd_GetTicket_Args_flags flags;
M_KeyID obj;
M_TicketDestination dest;
union M_TicketDestination__TicketDestSpec destspec;
};

The following flags are defined:
- Cmd_GetTicket_Args_flags_Reusable
  
  If this flag is set, the ticket can be used multiple times. Otherwise, the ticket can only be used once.
- Cmd_GetTicket_Args_flags_HarmlessInfoFlags
  
  Set if the nShield server understands new destinations, TicketDestination_AnyKernelClient and later. The nShield will set this flag automatically.
M_KeyID obj

The object for which a ticket is required. This may be any object with a KeyID, for example a key, token or SEEWorld.

M_TicketDestination dest are destinations at which this ticket can be redeemed:

typedef enum M_TicketDestination {
 TicketDestination_Any =
 TicketDestination_AnyClient =
 TicketDestination_NamedClient =
 TicketDestination_AnySEEWorld =
 TicketDestination_NamedSEEWorld =
 TicketDestination_AnyKernelClient
 TicketDestination__Max =
} M_TicketDestination;

TicketDestination_Any

This specifies any destination. If the nShield server has not set Cmd_GetTicket_Args_flags_HarmlessInfoFlags this will not include TicketDestination_AnyKernelClient or later destinations.
TicketDestination_AnyClient

This specifies any client connected to this server.
TicketDestination_NamedClient

This is the specific client that is named in the M_TicketDestination__TicketDestSpec.
TicketDestination_AnySEEWorld

This specifies any SEEWorld loaded on this module.
TicketDestination_NamedSEEWorld

This is the specific SEEWorld that is named in the M_TicketDestination__TicketDestSpec
TicketDestination_AnyKernelClient

This specifies any client operating in kernel space. This can only be used if the nShield server reports that the module offers the kernel interface.

union M_TicketDestination__TicketDestSpec destspec

This specifies a specific destination:

union M_TicketDestination__TicketDestSpec {
 M_TicketDestination_NamedSEEWorld_TicketDestSpec namedseeworld;
 M_TicketDestination_NamedClient_TicketDestSpec namedclient;
};

M_TicketDestination_NamedSEEWorld_TicketDestSpec namedseeworld

This is the KeyID of the SEEWorld:
```
struct M_TicketDestination_NamedSEEWorld_TicketDestSpec {
 M_KeyID world;
};
```
M_TicketDestination_NamedClient_TicketDestSpec namedclient

This is the SHA-1 hash of the ClientID:
```
struct M_TicketDestination_NamedClient_TicketDestSpec {
 M_Hash hclientid;
};
```

Reply

struct M_Cmd_GetTicket_Reply {
   M_nest_Ticket ticket;
};

M_nest_Ticket ticket is a ticket for this object to pass to the destination.

Hash

Operational state, initialization state

This command hashes a message.

There is no limit to the size of the plaintext. This is because the Generic Stub library splits the command into a ChannelOpen command followed by a number of ChannelUpdate commands. Only symmetric mechanisms use channels; asymmetric mechanisms cannot.

Arguments

struct M_Cmd_Hash_Args {
   M_Cmd_Hash_Args_flags flags;
   M_Mech mech;
   M_PlainText plain;
};

No flags are defined.
M_Mech mech - see Mechanisms.
M_PlainText plain This must be in the format M_PlainTextType_Bytes_Data.

Reply

struct M_Cmd_Hash_Reply {
   M_CipherText sig; Hash
};

ImpathKXBegin

Operational state, initialization state

Requires a ClientID

This command creates a new intermodule path (impath) and returns a key-exchange message that is to be sent to the peer module.

An impath is a cryptographically secure channel between two nShield nC-series hardware security modules. Data sent through such a channel is secure against both eavesdroppers and active adversaries. The channel can carry arbitrary user data as well as module-protected secrets, such as share data, to be passed directly between modules.

Modules are identified by means of M_RemoteModule structures. The elements of a M_RemoteModule describe a specific module or a set of modules—for example, those modules that know a particular module key—as well as information about how modules must prove their identity. The M_RemoteModule structures are the primary means for describing security policy decisions about impaths.

In many cases you do not need to define the impath yourself. If you use the nCore remote slot commands, the nShield server will create the required impaths automatically.

Arguments

struct M_Cmd_ImpathKXBegin_Args {
    M_Cmd_ImpathKXBegin_Args_flags flags;
    M_ModuleID module;
    M_RemoteModule me;
    M_RemoteModule him;
    M_ImpathKXGroupSelection hisgroups;
    M_Nonce n;
    int n_keys;
    M_vec_KeyID keys;
};

No flags are defined.
M_ModuleID module

The module ID of the module which is to be the local end of the impath.
M_RemoteModule me

This is an M_RemoteModule structure describing the local module. It must exactly match the him structure being used at the other end of the impath.
M_RemoteModule him

This is an M_RemoteModule structure describing the peer module. It must exactly match the me structure being used at the other end of the impath.
M_ImpathKXGroupSelection hisgroups

This is the peer module’s list of supported key-exchange groups. This list can be obtained, for example, by using the NewEnquiry command on the remote module. The list is used to select the key-exchange group that is to be used when setting up the impath.
M_Nonce n

This is a challenge obtained from the remote module by using the GetChallenge command.
int n_keys is the size of the keys table
M_vec_KeyID keys

This is a table of KeyIDs for the user keys whose hashes are listed in me.hks. The keys must have the SignModuleCert permission enabled. User keys may be either private or symmetric.

Reply

struct M_Cmd_ImpathKXBegin_Reply {
   M_ImpathID imp;
   M_ByteBlock kx;
};

M_ImpathID imp

This is the ID for this impath. After the impath is no longer required, it can be disposed of by using the Destroy command.
M_ByteBlock kx

This is a key-exchange message that is to be transmitted to the peer module. (See ImpathKXFinish.)

ImpathKXFinish

Operational state, initialization state

Requires a ClientID

This command completes an impath (intermodule path) key exchange. It leaves the impath ready for data transmission and receipt.

Arguments

struct M_Cmd_ImpathKXFinish_Args {
   M_Cmd_ImpathKXFinish_Args_flags flags;
   M_ImpathID imp;
   M_NetworkAddress *addr;
   int n_keys;
   M_vec_KeyID keys;
   M_ByteBlock kx;
};

The following flag is defined:
- Cmd_ImpathKXFinish_Args_flags_addr_present
  
  Indicates whether the M_NetworkAddress *addr is present.
M_ImpathID imp is the ID for the impath
M_NetworkAddress *addr

This is the network address of the peer host. If supplied, this is compared against the addr field in the him structure given to the ImpathKXBegin command.
int n_keys is the size of the keys table.
M_vec_KeyID keys

This is a table of KeyIDs for the user keys, public or symmetric, whose hashes were listed in the hks table in the him structure given to the ImpathKXBegin command.
M_ByteBlock kx

This is the key-exchange message returned by ImpathKXBegin on the peer module.

Reply

The reply structure for this command is empty.

ImpathReceive

Operational state, initialization state

Requires a ClientID

This command decrypts a user-data message that was encrypted using an impath.

Arguments

struct M_Cmd_ImpathReceive_Args {
   M_ImpathID imp;
   M_ByteBlock cipher;
};

M_ImpathID imp is the ID for the impath.
M_ByteBlock cipher is the cipher text emitted by an ImpathSend command issued to the peer module. Each cipher text message can be received once only, in order to prevent replay attacks.

Reply

struct M_Cmd_ImpathReceive_Reply {
   M_ByteBlock data;
};

M_ByteBlock data is a recovered plain text message.

ImpathSend

Operational state, initialization state

Requires a ClientID

This command encrypts a user message using an impath’s keys, ready for transmission to the peer host.

Arguments

struct M_Cmd_ImpathSend_Args {
   M_Cmd_ImpathSend_Args_flags flags;
   M_ImpathID imp;
   M_ByteBlock data;
};

No flags are defined.
M_ImpathID imp is the ID for the impath.
M_ByteBlock data is the message to be sent.

Reply

struct M_Cmd_ImpathSend_Reply {
   M_ByteBlock cipher;
};

M_ByteBlock cipher is the cipher text corresponding to the given plain text data. The plain text can be recovered by issuing an ImpathReceive command to the peer module.

InitialiseUnit

Pre-initialization state, initialization state

"Privileged" users only

This command causes a module in the pre-initialization state to enter the initialization state.

When the module enters the initialization state, it erases all module keys K_M, including K_M0. It also erases the module’s signing key, K_ML, and the hash of the Security Officer’s keys, H_KNSO. It does not erase the long-term K_LF key. It then generates a new K_ML and K_M0.

In order to use the module after it has been initialized, you must set a new Security Officer’s key.

When the module is in the pre-initialization state, you cannot obtain a ClientID. In order to use commands that require a ClientID, use the NewClient command after the module enters the Initialization state.

Arguments

struct M_Cmd_InitialiseUnit_Args {
   M_ModuleID module;
};

Reply

The reply structure for this command is empty.

LoadBlob

Operational state, initialization state

Requires a ClientID

This command allows a key blob to be loaded into the module. If this process is successful, a new ID_KA handle will be generated and returned.

For K_M blobs, the required K_M value must be present in the module’s internal storage.

For K_T blobs, the logical token containing K_T must be "present". This is not possible if the K_M associated with that K_T is not present in the module. See GenerateLogicalToken and LoadLogicalToken.

For the archival key blobs K_i or K_AR, the appropriate key object must be loaded.

Arguments

struct M_Cmd_LoadBlob_Args {
   M_Cmd_LoadBlob_Args_flags flags;
   M_ModuleID module;
   M_ByteBlock blob;
   M_KeyID *idkb;
} M_Cmd_LoadBlob_Args;

The following flag is defined:

Cmd_LoadBlob_Args_flags_idkb_present

See *idkb below.
M_ModuleID module is the module id.
M_ByteBlock blob is a key blob.
M_KeyID *idkb

In order to load a blob encrypted under a token or recovery key, set the idkb_present flag and include the identifier of either the token or the recovery key (ID_KT for tokens, ID_KAR for recovery keys) in the data as idkb. Otherwise, do not set idkb_present, and set idkb to NULL.

Reply

struct M_Cmd_LoadBlob_Reply {
    M_KeyID idka;
};

M_KeyID idka is ID_KA.

LoadLogicalToken

Operational state, initialization state

Requires a ClientID

May require a KNSO certificate

This command is used to initiate loading a token from shares.

The command returns an ID_KT. The token and any loaded shares can be removed by issuing the Destroy command with this identifier.

When this command is issued, the module allocates space for a share-reassembly process. In order to assemble the token, the application must issue one or more ReadShare commands (see ReadShare).

Arguments

struct M_Cmd_LoadLogicalToken_Args {
   M_ModuleID module;
   M_TokenHash hkt;
   M_KMHash hkm;
   M_TokenParams params;
};

M_ModuleID module is the module ID of the module. If you enter a module ID of 0, the command returns with status InvalidParameter.
M_TokenHash hkt is H_KT
M_KMHash hkm is the H_KM of the module key that is to be used to protect this token. If you supply an all-zero HKM, the module will use the null module key.
M_TokenParams params

The shares information must match that which was given when the token was generated. The flags and time limit are read from the token, and values set in the command are ignored.

Reply

struct M_Cmd_LoadLogicalToken_Reply {
   M_KeyID idkt;
};

M_KeyID idkt is the ID_KT.

MakeBlob

Operational state, initialization state

Requires a ClientID

This command requests that the module generate a key blob using a key whose identifier is given. The ACL for the key must allow the key to be exported as a blob, otherwise the command will fail.

The ACL for the key ID_KA must have a MakeBlob entry (for Module and Token blobs) or MakeArchiveBlob entry (for Direct or Indirect blobs) which permits making a blob with the requested parameters.

For a K_M key, the relevant key must be stored internally within the module.

For a K_T key, the logical token containing this key must be "present". Otherwise, the handle of another key object can be given to encrypt the blob. To succeed, the key object needs a UseAsBlobKey permission.

Arguments

struct M_Cmd_MakeBlob_Args {
   M_Cmd_MakeBlob_Args_flags flags;
   M_BlobFormat format;
   M_KeyID idka;
   union M_BlobFormat__MkBlobParams blobkey;
   M_ACL *acl;
   M_MakeBlobFile *file;
};

The following flags are defined:
- Cmd_MakeBlob_Args_flags_acl_present
  
  Set this flag if the command contains a new ACL.
- Cmd_MakeBlob_Args_flags_file_present
  
  Set this flag to store the blob in an NVRAM or smart card file, defined by the M_MakeBlobFile.
M_BlobFormat format

The following formats are defined:
- BlobFormat_Module
  
  Blob encrypted by a module key.
- BlobFormat_Token
  
  Blob encrypted by a Logical Token.
- BlobFormat_Direct
  
  Blob encrypted by a symmetric archiving key. Currently only Triple DES keys may be used.
- BlobFormat_Indirect
  
  Blob encrypted by an public archiving key, this requires the private key to decrypt. Currently only RSA keys may be used.
- BlobFormat_UserKey
  
  Not yet supported.

union M_BlobFormat__MkBlobParams blobkey

The following MKBlobParams are defined for the four different blob types:

struct M_BlobFormat_Direct_MkBlobParams \{
 M_KeyID idki;
};

struct M_BlobFormat_Indirect_MkBlobParams \{
 M_KeyID idkr;
 M_Mech mech;
};

struct M_BlobFormat_Module_MkBlobParams {
 M_KMHash hkm;
};

struct M_BlobFormat_Token_MkBlobParams {
 M_KeyID idkt;
};

struct M_BlobFormat_UserKey_MkBlobParams {
 M_KeyID idkr;
 M_Mech mech;
};

union M_BlobFormat__MkBlobParams {
 M_BlobFormat_Module_MkBlobParams module;
 M_BlobFormat_Token_MkBlobParams token;
 M_BlobFormat_Direct_MkBlobParams direct;
 M_BlobFormat_Indirect_MkBlobParams indirect;
 M_BlobFormat_UserKey_MkBlobParams userkey;
};

M_KeyID idki

This is the KeyID of a Triple DES key that is to be used to encrypt the blob.
M_KeyID idkr

This is the KeyID of the public key that is to be used to encrypt the blob.
M_Mech mec

This is the public key mechanism that is to be used to encrypt the blob.
M_KMHash hkm

This is the hash of the module key that is to be used to encrypt the blob.
M_KeyID idkt

This is the KeyID of the token that is to be used to encrypt the blob.
M_ACL *acl

This is either an ACL to be used for the key blob or NULL. If no ACL is specified, the loaded key’s existing ACL is recorded in the blob. See ACLs.

The ACL created for the blob does not include permission groups that have global limits (as opposed to per-authorization limits).

The permissions of the new ACL must be a subset of those specified by the existing ACL. For more information, see SetACL.

M_MakeBlobFile *file

A structure defining the file in which to store the blob.

struct M_MakeBlobFile {
 M_MakeBlobFile_flags flags;
 M_KeyID kacl;
 M_PhysToken file;
};

No flags are defined.
M_KeyID kacl

The KeyID of a template key defining the ACL for this file. This ACL must contain the LoadBlob permission.
M_PhysToken file

A FileSpec specifying the location of the file.

Reply

struct M_Cmd_MakeBlob_Reply {
   M_ByteBlock blob;
};

M_ByteBlock blob is a KeyBlob.

MergeKeyIDs

All non-error states

Requires a ClientID

In situations where one key has been loaded onto several modules, this key will have a different KeyID on each module. The MergeKeyIDs command takes a list of KeyIDs, which are assumed to refer to the same key, and creates a new KeyID that can be used to refer to the key on any module. This facilitates load sharing and fail-over strategies.

Arguments

struct M_Cmd_MergeKeyIDs_Args {
   int n_keys;
   M_vec_KeyID keys;
};

int n_keys is the number of keys.
M_vec_KeyID keys is a list of ID_KA.

Reply

struct M_Cmd_MergeKeyIDs_Reply {
   M_KeyID newkey;
};

M_KeyID newkey is ID_KA

Notes

MergeKeyIDs does not check to see whether the supplied KeyIDs actually refer to the same key.

Merged KeyIDs may not themselves be supplied to MergeKeyIDs.

A merged KeyID will continue to work even if some of the modules containing the component KeyIDs are reset or fail, though performance may be reduced in such cases. The merged KeyID will only stop working after all the modules containing the component KeyIDs are reset or fail.

MergeKeyIDs can be used to group keys, logical tokens, SEE Worlds, and any other objects that are referred to by a KeyID and destroyed by Destroy.

The server does not attempt to ensure that the merged KeyIDs refer to the same underlying data, or even to the same types of objects.

ReadShare

Operational state, initialization state

Requires a ClientID

This command is used to assemble a logical token from shares.

The smart card architecture keeps public data storage areas separate from the areas that are used to store logical token shares. Specifically, if a given piece of information can be read or written with ReadShare or WriteShare, then it cannot be read or written with ReadFile or WriteFile. The converse is also true.

Arguments

struct M_Cmd_ReadShare_Args {
   M_Cmd_ReadShare_Args_flags flags;
   M_PhysToken token;
   M_KeyID idkt;
   M_Word i;
   M_PIN *pin;
};

The following flags are defined:
- Cmd_ReadShare_Args_flags_pin_present
  
  This flag must be set if the input includes a PIN.
  
  If the slot uses the ProtectedPINPath, do not include the PIN with the command.
- Cmd_ReadShare_Args_flags_UseLimitsUnwanted
  
  If this flag is set the module does not allocate Per-Authorisation Use limits to this logical token. Keys protected by the assembled local token will only be permitted to perform actions that do not have use limits. Per authorisation use limits can only be allocated to one logical token for each insertion of the card. However, it is possible that the logical token is required on several modules, or by several clients on one module. Therefore, you should set this flag, if you are aware that you do not need the uselimits and wish to make them available elsewhere.
M_KeyID idkt is the ID_KT.
M_Word i is share number i.
M_PIN *pin

If the share is protected by a PIN, this must be specified in order to successfully decrypt the share, otherwise pin must be a NULL pointer. If the input includes a PIN, the pin_present flag must be set.

Reply

struct M_Cmd_ReadShare_Reply {
   M_Word sharesleft;
};

M_Word sharesleft is the number of shares that are still required in order to recreate the token. You can issue further ReadShare commands when the shares are present.

A sharesleft value of 0 indicates that all shares are present. At that point, the module will automatically assemble the token.

Notes

If an error occurs during an individual share reading operation (because of, for example, an incorrect PIN or the wrong token), the current state of the logical token is retained, and the operation can simply be repeated.

If an error occurs during the final share reassembly process (implying that the shares have been corrupted in some way), the logical token is invalidated, and Status_TokenReassemblyFailed is returned. The token must then be destroyed, and the whole operation must be restarted.

At any time during the share reassembly sequence, the host can abort it (and clear the reassembly buffer) by calling Destroy with the given ID_KT. If the client closes before the token has been assembled, the server automatically issues the Destroy command.

RedeemTicket

Operational state, initialization state

Requires a ClientID

This command gets a KeyID in return for a key ticket.

Arguments

struct M_Cmd_RedeemTicket_Args {
   M_Cmd_RedeemTicket_Args_flags flags;
   M_ModuleID module;
   M_nest_Ticket ticket;
};

No flags are defined.
M_ModuleID module

This specifies the module ID of the module that contains this object.
M_nest_Ticket ticket

This is the ticket that is supplied by GetTicket.

Reply

struct M_Cmd_RedeemTicket_Reply {
   M_KeyID obj;
};

M_KeyID obj is the new KeyID for this object.

RemoveKM

Operational state, initialization state

Requires a ClientID

May require a KNSO certificate

"Privileged" users only

This command deletes a given K_M value from permanent storage. The deletion process overwrites the value in order to ensure its destruction.

K_M0 cannot be deleted.

Arguments

struct M_Cmd_RemoveKM_Args {
   M_ModuleID module;
   M_Cmd_RemoveKM_Args_flags flags;
   M_KMHash hkm;
};

M_ModuleID module is the ModuleID.
No flags are defined.
M_KMHash hkm is H_KM.

Reply

The reply structure for this command is empty.

RSAImmedSignDecrypt

Operational state, initialization state

This command performs RSA decryption by using an RSA private key that is provided in plain text.

Arguments

struct M_Cmd_RSAImmedSignDecrypt_Args {
   M_Bignum m;
   M_Bignum k_p;
   M_Bignum k_q;
   M_Bignum k_dmp1;
   M_Bignum k_dmq1;
   M_Bignum k_iqmp;
};

M_Bignum m Ciphertext
M_Bignum k_p P modulus first factor
M_Bignum k_q Q modulus first factor
M_Bignum k_dmp1 D MOD_P-1
M_Bignum k_dmq1 D MOD_Q-1
M_Bignum k_iqmp Q^-1 MOD_P

Reply

struct M_Cmd_RSAImmedSignDecrypt_Reply {
   M_Bignum r;
};

M_Bignum r is plain text .

Notes

The plain text and cipher text are in the nShield bignum format.

No padding is done.

RSAImmedVerifyEncrypt

Operational state, initialization state

This command performs RSA encryption with an RSA public key provided in plain text.

Arguments

struct M_Cmd_RSAImmedVerifyEncrypt_Args {
   M_Bignum a;
   M_Bignum k_e;
   M_Bignum k_n;
};

M_Bignum a Message
M_Bignum k_e Key exponent
M_Bignum k_n Key modulus

Reply

Uses M_Cmd_RSAImmedSignDecrypt_Reply.

Notes

The plain text and cipher text are in nShield bignum format.

No padding or unpadding is performed.

SetACL

Operational state, initialization state

Requires a ClientID

This command replaces the ACL of a given key object with a new ACL. The existing ACL must have either ExpandACL or ReduceACL permission. If the existing ACL only includes the ReduceACL permission, you must set the Cmd_SetACL_Args_flags_reduce flag, and also the new ACL must be a subset of the existing ACL.

Arguments

struct M_Cmd_SetKM_Args {
   M_Cmd_SetKM_Args_flags flags;
   M_KeyID idka;
   M_ACL *acl;
};

The following flag is defined:
- Cmd_SetACL_Args_flags_reduce
  
  If this flag is not set, the command checks the ExpandACL permission in the existing ACL. However, if this flag is set:
  - the command checks the ReduceACL permission in the existing ACL
  - the new ACL must be a subset of the existing ACL
M_KeyID idka is ID_KA.
M_ACL *acl is the new ACL for the key.

Reply

The reply structure for this command is empty.

Notes

The new ACL will be a subset of the original ACL if for every action in the new ACL there exists an entry in the existing ACL in a permission group with:

the same certifier or no certifier
the same or more restrictive FreshCerts flag
use limits that are at least as permissive as those in the new ACL

The use limits are considered to be as permissive as those in the new ACL if for each limit in the original ACL there is a limit in the new ACL:

of the same type, global or per-authorization
with the same limit ID
with a use count and a time limit that are no greater than those in the original.

The following changes count as reducing an ACL:

adding a certifier or NSOCertified to a group
adding UseLimits to a group that did not have them previously
adding a time limit or a use count to a use limit that did not have one previously
reducing an existing use count or time limit
adding a module serial number to a group.

The following changes do not count as reducing an ACL:

changing the certifier for a group
changing the module serial number for a group
changing a use count to a time limit or changing a time limit to a use count
changing from NSOCertified to a specific certifier or changing from a specific certifier to NSOCertified.

If the Strict_FIPS140 flag was set in the SetKNSO command, then SetACL will fail with status Status_FIPS_Compliance if you attempt to add ExportAsPlain to the ACL of a secret key. A secret key is any key that can have Sign or Decrypt permissions.

If you want to record the new ACL permanently, you must make a new blob of the key.

SetKM

Operational state, initialization state

Requires a ClientID

May require a KNSO certificate

"Privileged" users only

This command allows a key object to be stored internally as a module key (K_M) value. The K_M value is derived from the key material given by ID_KA. The ACL and other information associated with ID_KA are not stored.

Arguments

struct M_Cmd_SetKM_Args {
   M_ModuleID module;
   M_Cmd_SetKM_Args_flags flags;
   M_KeyID idka;
};

M_ModuleID module
No flags are defined.
M_KeyID idka is ID_KA.
K_A must be a DES3 key with UseAsKM permission.

Reply

The reply structure for this command is empty.

Notes

If you attempt to set as a K_M a key that has the same hash as an existing K_M, then SetKM will overwrite the existing module key with the new key. If you are attempting to overwrite K_M0, the command will return Status_AccessDenied.

SetNSOPerms

Initialization state only

Requires a ClientID

"Privileged" users only

The SetNSOPerms command stores the key hash H_KA, which is returned by GetKeyInfo as the new Security Officer’s key.

It also determines which operations require a KNSO certificate.

The SetNSOPerms command requires you to set a flag if you want an operation to be allowed without a certificate. This is the opposite behavior to the SetKNSO command.

This command may only be called once after each use of InitialiseUnit (see InitialiseUnit). After it is set, the Security Officer’s key can only be changed by completely reinitializing the module.

Arguments

struct M_Cmd_SetNSOPerms_Args {
   M_ModuleID module;
   M_Cmd_SetNSOPerms_Args_flags flags;
   M_KeyHash hknso;
   M_NSOPerms publicperms;
};

M_ModuleID module is the module id

The following flag is defined:

Cmd_SetNSOPerms_Args_flags_FIPS140Level3

If this flag is set, the module adopts a security policy that complies with FIPS 140-2 Level 3. This enforces the following restrictions:
- the Import command fails if you attempt to import a key of a type that can be used to sign or decrypt messages.
  
  Use of the Import command for other key types requires a K_NSO certificate.
- GenerateKey and GenerateKeyPair require K_NSO certificates
- GenerateKey and GenerateKeyPair fail if you attempt to generate a key of a type that can be used to sign or decrypt messages with an ACL that allows ExportAsPlain
- SetACL fails if you attempt to add the ExportAsPlain action to the ACL of a key of a type that can be used to sign or decrypt messages.
  
  All cryptographic mechanisms which do not use a FIPS-approved algorithm are disabled. (This restriction is new for firmware versions 2.18.13 and later).
  
  Cryptographic algorithms which are disabled are: ArcFour, Blowfish, CAST, CAST256, HAS160, KCDSA, MD2, MD5, RIPEMD160, SEED, Serpent, Tiger, Twofish.
  
  The following algorithms are unaffected: DES, DES2, DES3, Diffie-Hellman, DSA, Rijndael (AES), RSA, SHA-1, SHA-256, SHA-384 and SHA-512

In order to fully comply with FIPS 140-2 Level 3 you must also ensure that none of the following are set: NSOPerms_ops_ReadFile, NSOPerms_ops_WriteFile, NSOPerms_ops_EraseShare, NSOPerms_ops_EraseFile, NSOPerms_ops_FormatToken, NSOPerms_ops_GenerateLogToken, NSOPerms_ops_SetKM, NSOPerms_ops_RemoveKM.

M_KeyHash hkns is H_KA to set as H_KNSO
M_NSOPerms publicperms

The NSOPerms word is a bit map that determines which operations do not require a certificate from the nShield Security Officer. These certificates can be reusable. The following flags are defined:
- NSOPerms_ops_LoadLogicalToken
- NSOPerms_ops_ReadFile
- NSOPerms_ops_WriteShare
- NSOPerms_ops_WriteFile
- NSOPerms_ops_EraseShare
- NSOPerms_ops_EraseFile
- NSOPerms_ops_FormatToken
- NSOPerms_ops_SetKM
- NSOPerms_ops_RemoveKM
- NSOPerms_ops_GenerateLogToken
- NSOPerms_ops_ChangeSharePIN
- NSOPerms_ops_OriginateKey Not allowed in SetKNSO
- NSOPerms_ops_NVMemAlloc Not allowed in SetKNSO
- NSOPerms_ops_NVMemFree Not allowed in SetKNSO
- NSOPerms_ops_GetRTC Not allowed in SetKNSO
- NSOPerms_ops_SetRTC Not allowed in SetKNSO
- NSOPerms_ops_DebugSEEWorld Not allowed in SetKNSO
- NSOPerms_ops_SendShare Not allowed in SetKNSO
- NSOPerms_ops_ForeignTokenOpen Not allowed in SetKNSO

Reply

The reply structure for this command is empty.

Notes

Modules that are supplied by nShield are initialized with no operations that require K_NSO certificates. This means that the key whose hash is installed as H_KNSO is irrelevant.

SetRTC

Operational state, initialization state

Requires an SEE-Ready module

May require a KNSO certificate

"Privileged" users only

Arguments

struct M_Cmd_SetRTC_Args {
   M_ModuleID module;
   M_Cmd_SetRTC_Args_flags flags;
   M_RTCTime time;
};

M_ModuleID module

The module ID of the module. If you enter a module ID of 0, the command returns with status InvalidParameter.
The following flag is defined:
- Cmd_SetRTC_Args_flags_adjust
  
  If this flag is set, the module calculates the difference between the current time according to the RTC and the time supplied in the command. Next, it divides this difference by the length of time since the clock was last set in order to determine a drift rate. The result of all future calls to GetRTC is corrected using this drift rate. The command returns status OutOfRange if the implied drift rate is larger than the chip’s guaranteed maximum drift rate. If, however, this flag is not set, the module will clear any current drift rate adjustment.
M_RTCTime time is the new time.

Reply

The reply structure for this command is empty.

Sign

Operational state, initialization state

Requires a ClientID

This command signs a message with a stored key.

For information on formats, see Encrypt.

Sign pads the message as specified by the relevant algorithm, unless you use plaintext of the type Bignum.

You cannot sign a message that is longer than the maximum size of an nShield command. In order to sign longer messages, use the Hash command first, and then call Sign with the appropriate Hash plain text type.

Arguments

struct M_Cmd_Sign_Args {
   M_Word flags;
   M_KeyID key;
   M_Mech mech;
   M_PlainText plain;
   M_IV *given_iv
};

No flags are defined.
M_KeyID key is the ID_KA.

Reply

struct M_Cmd_Sign_Reply {
   M_CipherText sig;
};

SignModuleState

Operational state, initialization state

Requires a ClientID

SignModuleState makes the module generate a signed Module Certificate that contains data about the current state of the module. Optionally, a challenge value may be supplied to provide a provably fresh certificate.

Arguments

struct M_Cmd_SignModuleState_Args{
    M_ModuleID module;
    M_Cmd_SignModuleState_Args_flags flags;
    M_SignerType enum;
    M_Nonce challenge;
    M_wrap_vec_ModuleAttribTag *attribs;
};

The following flags are defined:
- Cmd_SignModuleState_Args_flags_challenge_present
  
  This flag must be set if the command contains a challenge.
- Cmd_SignModuleState_Args_flags_attribs_present
  
  This flag must be set if the command contains Module Attribute Tags. If not set the module delivers a default set of attributes.
SignerType can have the following values:
- KLF: The certificate is signed by the KLF long-term key. Status_NotAvailable is returned if this key has not been set.
- KML: The certificate is signed by the KML key. This is always available (except in pre-initialization mode, when the command is not accepted anyway).
- Appkey: The certificate is signed a user key, using the given mechanism (which can be Mech_Any). The key must have a new OpPermission bit in its ACL, called SignModuleCert. SignModuleCert is a less generate permission than Sign: the module uses it only to sign well-formed messages whose content it believes to be true. Sign permission doesn’t imply SignModuleCert permission.
M_wrap_vec_ModuleAttribTag *attribs is a list of the attributes to include in the signed message
```
struct M_wrap_vec_ModuleAttribTag {
   int n;
   M_vec_ModuleAttribTag v;
};
```
The following attributes are defined:
- ModuleAttribTag_None
- ModuleAttribTag_Challenge (default if included in command)
- ModuleAttribTag_ESN (default)
- ModuleAttribTag_KML (default)
- ModuleAttribTag_KLF (default)
- ModuleAttribTag_KNSO (default)
- ModuleAttribTag_KMList (default)
- ModuleAttribTag_PhysSerial
- ModuleAttribTag_PhysFIPSl3
- ModuleAttribTag_FeatureGoldCert
- ModuleAttribTag_Enquiry
- ModuleAttribTag_AdditionalInfo
- ModuleAttribTag_ModKeyInfo

Reply

The reply structure for this command is as follows:

struct M_Cmd_SignModuleState_Reply {
    M_ModuleCert *cert;
};

M_ModuleCert *cert is a certificate that describes how the key was generated.

struct M_ModuleCert {
    M_CipherText signature;
    M_ByteBlock modcertmsg;
};

struct M_ModCertMsg {
    M_ModCertType type;
    union M_ModCertType__ModCertData data;
};

union M_ModCertType__ModCertData {
    M_ModCertType_KeyGen_ModCertData keygen;
};

struct M_ModCertType_KeyGen_ModCertData {
    M_ModCertType_KeyGen_ModCertData_flags flags:
    M_KeyGenParams genparams;
    M_ACL acl;
    M_Hash hka;
};

M_ModCertType type is one of the following:
- None
- Challenge: appears if a challenge is present in the SignModuleState command
- ESN: ASCII string
- KML: KML key, defined with key hash and key data
- KLF: KLF key, defined with key hash and key data
- KNSO: not present if module is in initialization mode
- KMList
The following flag is defined:
- ModCertType_KeyGen_ModCertData_flags_public
  
  Set this flag if this is the public half of a key pair.
M_KeyGenParams genparams

These are the key generation parameters to be used to generate this key.
M_ACL acl

This is the ACL that was applied to this key when it was created.
M_Hash hka

This is the SHA-1 hash of the key value.

StaticFeatureEnable

Operational state, initialization state

This command is used to enable a purchased feature. It requires a certificate signed by the nShield master feature enabling key, KSA, authorizing the feature on the specified module.

Use the fet command-line utility to perform this function.

Arguments

struct M_Cmd_StaticFeatureEnable_Args {
   M_ModuleID module; Module ID
   M_FeatureInfo info;
};

M_FeatureInfo info is a description of the feature to authorize

Reply

The reply structure for this command is empty.

UpdateMergedKey

All non-error states

Processed by the nShield Server.

This command allows a merged key set to be manipulated, listed, or both.

Arguments

struct M_Cmd_UpdateMergedKey_Args {
    M_PlainText mkey; IDKA
    M_Cmd_UpdateMergedKeys_Args_flags flags
    int n_addkeys;
    M_KeyID *addkeys;
    int n_delkeys;
    M_KeyID *delkeys;
};

M_PlainText mkey (ID_KA) is a merged key set created with MergeKeyIDs.
The following flags are defined:
- Cmd_UpdateMergedKey_Args_flags_ListWorking
  
  If this flag is set, the keys in the resulting merged key that are in working modules are returned.
- Cmd_UpdateMergedKey_Args_flags_ListNonworking
  
  If this flag is set, the keys in the resulting merged key that are not in working modules are returned.
  
  These two flags can be set together if required.
M_KeyID *addkeys is a table of keys to be added to the merged key.

Merged key IDs that currently contain no key IDs are allowed.
M_KeyID *delkeys is a table of keys to be deleted from the merged key.

Including a key in this list deletes all copies of the specified key.

Reply

struct M_Cmd_UpdateMergedKey_Reply {
   int n_keys;
   M_KeyID *keys;
};

M_KeyID *keys is a table containing the merged key that results once the specified keys are added and deleted from the input merged key.

If ListWorking is set, keys in working modules are included; if ListNonWorking is set, keys not in working modules are included. If both are set, all keys are included.

Notes

You cannot add a merged key to another merged key, or delete a merged key from another merged key.

The same key can be present more than once in a merged key.

The keys specified in addkeys are added to the target merged key first. The keys specified in delkeys are then deleted. This means that if the same key is present in both addkeys and delkeys, it is not present in the resulting merged key.

Verify

Operational state, initialization state

Requires a ClientID

This command verifies a digital signature. It returns Status_OK if the signature verifies correctly and Status_VerifyFailed if the verification fails.

The limit of 8K does not apply to data signed by this command. This is because the Generic Stub library splits the command into a ChannelOpen command followed by a number of ChannelUpdate commands.

For information on formats, see Sign.

Arguments

struct M_Cmd_Verify_Args {
    M_Cmd_Verify_Args_flags flags;
    M_KeyID key;
    M_Mech mech;
    M_PlainText plain;
    M_CipherText sig;
};

No flags are defined.
M_KeyID key: ID_KA
M_Mech mech: set Mech_Any in order to use the mechanism specified in the signature. If you specify a mechanism, Verify will compare this with the mechanism in the signature and return Status_MechanismNotExpected if the mechanisms do not match.
M_PlainText plain: message.
M_CipherText sig: signature.

Reply

The reply structure for this command is empty.

WriteShare

Operational state, initialization state

Requires a ClientID

May require a KNSO certificate

This command creates one share of a logical token and writes it to a smart card identified by the SlotID, insertion counter pair. The i value identifies the share number. This command needs to be given once for each share that is to be generated.

Arguments

struct M_Cmd_WriteShare_Args {
    M_Cmd_WriteShare_Args_flags flags;
    M_PhysToken token;
    M_KeyID idkt;
    M_Word i;
    M_PIN *pin;
    M_ACL *acl;
};

The following flags are defined:
- Cmd_WriteShare_Args_flags_pin_present
  
  This flag must be set if the input includes a pass phrase.
- Cmd_WriteShare_Args_flags_UseProtectedPINPath
  
  Set this flag if the token reads a pass phrase by means of a protected path. However, this feature is not currently implemented.
- Cmd_WriteShare_Args_flags_acl_present
  
  Set this flag if the command contains an ACL for the share.
  
  Setting both pin_present and UseProtectedPINPath will cause the command to fail with InvalidParameter.
M_KeyID idkt: ID_KT
M_Word i is the share number for the share you are writing. Share numbers start at 0. Each share in a token can only be written once.
M_ACL *acl is an ACL for this share. If no ACL is specified, a default ACL is assumed, containing a single ReadShare action without any flags set and requiring no certification.

If any shares of a logical token are to have an ACL set, you must set an ACL for all of them. Shares with ACLs cannot be read in modules running firmware earlier than version 1.75.0.

Reply

The reply structure for this command is empty.

Commands used by the generic stub only

The following commands are used by the generic stub library to connect to the module.

ExistingClient
NewClient

Applications usually do not have to call these commands directly.

ExistingClient

All non-error states

Connection must not be associated with a ClientID

This command identifies a connection as belonging to an existing client. There must be at least one other connection from this client still open. The ExistingClient command is called automatically by the generic stub function NFastApp_Connect as appropriate, for example when making an additional connection to an existing client.

Arguments

struct M_Cmd_ExistingClient_Args {
    M_Cmd_ExistingClient_Args_flags flags;
    M_ClientID client;
};

No flags are defined.
M_ClientID client: R_SC

Reply

struct M_Cmd_ExistingClient_Reply {
    M_Cmd_ExistingClient_Reply_flags flags;
};

No flags are defined.

NewClient

Initialization state, operational state

Connection must not be associated with a ClientID

This command asks the module for a random number to use as the ClientID for a new connection. It is called automatically by the generic stub function NFastApp_Connect.

Arguments

typedef struct M_Cmd_NewClient_Args {
   M_Cmd_NewClient_Args_flags flags;
};

No flags are defined.

Reply

struct M_Cmd_NewClient_Reply {
    M_Cmd_NewClient_Reply_flags flags;
    M_ClientID client;
};

No flags are defined.
M_ClientID client: R_SC