4.1 WFS_CMD_PIN_CRYPT

Description The input data is either encrypted or decrypted using the specified or selected encryption mode. The available modes are defined in the WFS_INF_PIN_CAPABILITIES command.

This command can also be used for Message Authentication Code generation (i.e. MACing). For this purpose, it is possible to specify how the data is formatted before the encryption.

The input data can be expanded with a fill-character to the necessary length (mandated by the encryption algorithm being used).

The Start Value (or Initialization Vector) should be able to be passed encrypted like the specified encryption/decryption key. It would therefore need to be decrypted with a loaded key so the name of this key must also be passed. However, both these parameters are optional.

Input Param LPWFSPINCRYPT lpCrypt;

typedef struct _wfs_pin_crypt
{
WORD wMode;
LPSTR lpsKey;
LPWFSXDATA lpxKeyEncKey;
WORD wAlgorithm;
LPSTR lpsStartValueKey;
LPWFSXDATA lpxStartValue;
BYTE bPadding;
BYTE bCompression;
LPWFSXDATA lpxCryptData;
} WFSPINCRYPT, * LPWFSPINCRYPT;

wMode
Specifies whether to encrypt or decrypt, values are one of the following:

Value Meaning

WFS_PIN_MODEENCRYPT encrypt with key

WFS_PIN_MODEDECRYPT decrypt with key

This parameter does not apply to MACing.

lpsKey
Specifies the name of the stored key.

lpxKeyEncKey
If NULL, lpsKey is used directly for encryption/decryption. Otherwise, lpsKey is used to decrypt the encrypted key passed in lpxKeyEncKey and the result is used for encryption/decryption. Key is a double length key when used for Triple DES encryption/decryption. Users of this specification must adhere to local regulations when using Triple DES.

wAlgorithm
Specifies the encryption algorithm. Possible values are those described in WFS_INF_PIN_CAPABILITIES.

lpsStartValueKey
Specifies the name of the stored key used to decrypt the lpxStartValue to obtain the Initialization Vector. If this parameter is NULL, lpxStartValue is used as the Initialization Vector.

lpxStartValue
DES and Triple DES initialization vector for CBC / CFB encryption and MACing. If this parameter is NULL lpsStartValueKey is used as the Start Value. If lpsStartValueKey is also NULL, the default value for CBC / CFB / MAC is 16 hex digits 0x0.

bPadding
Specifies the padding character for encryption.

bCompression
Specifies whether data is to be compressed (blanks removed) before building the MAC. If bCompression is 0x00 no compression is selected, otherwise bCompression holds the representation of the blank character in the actual code table.

lpxCryptData
Pointer to the data to be encrypted, decrypted, or MACed.

Output Param LPWFSXDATA lpxCryptData;

lpxCryptData
Pointer to the encrypted or decrypted data, or MAC value.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_MODENOTSUPPORTED The specified mode is not supported.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_INVALIDKEYLENGTH The length of lpxKeyEncKey or lpxStartValue is not supported.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments The datatype LPWFSXDATA is used to pass hexadecimal data and is defined as follows :

typedef struct _wfs_hex_data
{
USHORT usLength;
LPBYTE lpbData;
} WFSXDATA, *LPWFSXDATA;

usLength
Length of the byte stream pointed to by lpbData.

lpbData
Pointer to the binary data stream.