Algorithm-Specific Cipher Information
This section contains the following descriptions:
AES Cipher Object
Operation Supported : Encrypt, Decrypt, Multi-part MAC, Multi-part MAC Verify
Key Encoding
Supports 16, 24 and 32 byte key value.
Encrypt/Decrypt Modes
The least significant nibble (4 bits) determines the operational mode.
Possible values:
>SYM_MODE_ECB (0)
Electronic Code Book (ECB) mode.
>SYM_MODE_CBC (1)
Cipher Block Chaining (CBC) mode. It may be combined with a padding mode (see below).
>SYM_MODE_CFB (2)
Cipher Feedback (64-bit) mode
>SYM_MODE_BCF (3)
Byte Cipher Feedback (8-bit CFB) mode
>SYM_MODE_OFB (4)
Output Feed Back (OFB) mode.
>SYM_MODE_WRAP_KWP (7)
Key Wrap with Padding (KWP) mode
>SYM_MODE_GCM (9)
Galois Counter Mode (GCM)
>SYM_MODE_CCM (10)
Counter with CBC-MAC (CCM) mode
Padding Mode
The most significant nibble defines the padding mode used.
Possible values:
>SYM_MODE_PADPKCS1 (0x80)
PKCS#1 padding is applied. This causes 1 to 8 bytes of padding to be added to the data. Note that the padding is applicable to SYM_MODE_CBC only.
>SYM_MODE_PADCMAC (0x40)
CMAC padding is applied. This causes 1 to 7 bytes of padding to be added to the data.
MAC modes
For MAC generation and verification, available modes include:
>SYM_MODE_MAC_3 (0)
Standard CBC
>SYM_MODE_MAC_GEN (1)
Standard CBC with configurable MAC length
Encrypt/Decrypt Parameters
In SYM_MODE_CBC, the parameter buffer must contain the IV (16 bytes). In SYM_MODE_ECB, there are no parameters.
MAC Parameters
When mode is SYM_MODE_MAC_GEN, parameter buffer contains at least 4 bytes, which is the little-endian encoding of an integer. The integer value must contain a value from 1 to 8, indicating the number of bytes of the final IV that will be used as the MAC. This is optionally followed by 8 bytes containing the IV.
DES Cipher Object
Operations Supported
Encrypt, Decrypt, Multi-Part MAC, and Multi-Part Verify.
Key encoding
Every byte contains 7 key bits, and 1 parity bit. The parity bit is the least significant bit in each byte. There is no additional encoding of the key data. The key must be 8 bytes long.
Encrypt/Decrypt Modes
The least significant nibble (4 bits) determines the operational mode.
Possible values:
>SYM_MODE_ECB (0)
Electronic Code Book (ECB) mode. It may be combined with a padding mode (see below).
>SYM_MODE_CBC (1)
Cipher Block Chaining (CBC) mode. It may be combined with a padding mode (see below).
>SYM_MODE_CFB (2)
Cipher Feedback (64-bit) mode
>SYM_MODE_BCF (3)
Byte Cipher Feedback (8-bit CFB) mode
>SYM_MODE_OFB (4)
Output Feedback (64-bit) mode
>SYM_MODE_BOF (5)
Byte Output Feedback (8-bit OFB) mode
The most significant nibble defines the padding mode used.
Possible values:
>SYM_MODE_PADPKCS1 (0x80)
PKCS#1 padding is applied. This causes 1 to 8 bytes of padding to be added to the data.
>SYM_MODE_PADCMAC (0x40)
CMAC padding is applied. This causes 1 to 7 bytes of padding to be added to the data.
MAC modes
For MAC generation and verification operation the following modes are available:
>0: Standard DES CBC
>1: Standard DES CBC with configurable MAC length
In both methods, NULL padding is applied to the data.
Encrypt/Decrypt Parameters
In all modes, except SYM_MODE_ECB, the parameter buffer must contain the IV (8 bytes). In SYM_MODE_ECB, there are no parameters.
MAC Parameters
When mode 1 is used, parameter buffer contains 4 bytes, which contain a little-endian encoding of an integer. The integer value must contain a value from 1 to 8, indicating the number of bytes of the final IV that will be used as the MAC.
Triple DES Cipher Object
Operations Supported
Encrypt, Decrypt, Multi-Part MAC, and Multi-Part Verify.
Key encoding
Every byte contains 7 key bits, and 1 parity bit. The parity bit is the least significant bit in each byte. There is no additional encoding of the key data. The key must be 16 or 24 bytes.
Encrypt/Decrypt Modes
The least significant nibble (four bits) determines the operational mode. Possible values:
>SYM_MODE_ECB (0)
Electronic Code Book (ECB) mode. It may be combined with a padding mode (see below).
>SYM_MODE_CBC (1)
Cipher Block Chaining (CBC) mode. It may be combined with a padding mode (see below).
>SYM_MODE_CFB (2)
Cipher Feedback (64-bit) mode
>SYM_MODE_BCF (3)
Byte Cipher Feedback (8-bit CFB) mode
>SYM_MODE_OFB (4)
Output Feedback (64-bit) mode
>SYM_MODE_BOF (5)
Byte Output Feedback (8-bit OFB) mode
>SYM_MODE_WRAP_TKW (8)
Triple DES Key Wrap (TKW) mode
The most significant nibble determines the padding mode. Possible values:
>SYM_MODE_PADPKCS1 (0x80)
PKCS#1 padding is applied. This causes 1 to 8 bytes of padding to be added to the data.
>SYM_MODE_PADCMAC (0x40)
CMAC padding is applied. This causes 1 to 7 bytes of padding to be added to the data.
MAC modes
For MAC generation and verification, available modes include:
>0: Standard triple DES CBC
>1: Standard triple DES CBC with configurable MAC length
>2: X9.19 triple DES CBC
>3: X9.19 triple DES CBC with configurable MAC length
>4: Retail CFB MAC.
In all methods, NULL padding is applied to the data.
Encrypt/Decrypt Parameters
In all modes except SYM_MODE_ECB, the parameter buffer must contain the IV (8 bytes). In SYM_MODE_ECB, there are no parameters.
MAC Parameters
When mode is either 1 or 3, parameter buffer contains at least 4 bytes, which is the little-endian encoding of an integer. The integer value must contain a value from 1 to 8, indicating the number of bytes of the final IV that will be used as the MAC. This is optionally followed by 8 bytes containing the IV. For mode 4 (Retail MAC CFB), the parameter buffer must have 8 bytes containing the encrypted IV. For the remaining two modes, the parameter buffer is either empty, or has 8 bytes containing the IV.
ECDSA Cipher Object
Operations Supported
SignInit(), Sign(), VerifyInit(), and Verify().
Key Encoding
When performing:
>Sign operation: the key is specified as a buffer of ECC_Curve_t followed by Private Key ECC_PrivateKey_t.
>Verify operation: the key is specified as a buffer of ECC_Curve_t followed by Public Key ECC_PublicKey_t.
See also ECDSA Key Structures.
Modes
None
Sign/Verify Parameters
None
ECDSA Key Structures
#define ECC_MAX_MOD_LEN 571
#define ECC_MAX_BUF_LEN ROUND_UP(ECC_MAX_MOD_LEN, 8)/8
typedef enum ECC_FieldType_et {
ECC_FT_GFP,
ECC_FT_G2M
ECC_FT_MON
} ECC_FieldType_t;
Where:
>ECC_FT_GFP: Identifies a curve over a field with an odd prime number of elements.
>ECC_FT_G2M: Identifies a curve over a field of characteristic two (F_2^m).
>ECC_FT_MON: Identifies a curve that uses a Montgomery function.
typedef struct ECC_Point_st {
unsigned char x[ECC_MAX_BUF_LEN];
unsigned char y[ECC_MAX_BUF_LEN];
} ECC_Point_t;
Where:
>x: The X coordinate of the point. X is an element of the field over which the curve is defined.
>y: The Y coordinate of the point. Y is an element of the field over which the curve is defined.
typedef struct ECC_Curve_st {ECC_FieldType_t fieldType;
unsigned char modulus[ECC_MAX_BUF_LEN];
unsigned char a[ECC_MAX_BUF_LEN];
unsigned char b[ECC_MAX_BUF_LEN];
ECC_Point_t base;
unsigned char bpOrder[ECC_MAX_BUF_LEN];
} ECC_Curve_t;
Where:
>fieldType: The field type, over which this curve is defined.
>base: The base point.
>modulus: The curve modulus. This value is the field polynomial for ECC_FT_G2M field types.
>a: The coefficient 'a' in the elliptic curve equation.
>b: The coefficient 'b' in the elliptic curve equation.
>bpOrder: The base point order. This buffer contains a big endian large number regardless of the field type.
typedef struct ECC_PrivateKey_st {unsigned char d[ECC_MAX_BUF_LEN];
} ECC_PrivateKey_t;
Where:
>d: The buffer containing the private key. The private key is always a big-endian large number, d, regardless of the field type of the curve.
typedef struct ECC_PublicKey_st {ECC_Point_t p;
} ECC_PublicKey_t;
Where:
>p: The point P on the curve, which is calculated from the curve base and the private key.
IDEA Cipher Object
Operation Supported
Encrypt, Decrypt, Multi-part MAC, Multi-Part MAC Verify
Key Encoding
Supports 16 byte key value.
Encrypt/Decrypt Modes
The least significant nibble (four bits) is used to determine the operational mode.
Possible values:
>SYM_MODE_ECB (0)
Electronic Code Book (ECB) mode. It may be combined with a padding mode (see Padding Mode ).
>SYM_MODE_CBC (1)
Cipher Block Chaining (CBC) mode. It may be combined with a padding mode (see Padding Mode ).
Padding Mode
The most significant nibble defines the padding mode used.
Possible value: SYM_MODE_PADPKCS1 (0x80)
PKCS#1 padding is applied. This causes 1 to 8 bytes of padding to be added to the data.
MAC modes
For MAC generation and verification, available modes include:
>SYM_MODE_MAC_3 (0)
Standard MAC
>SYM_MODE_MAC_GEN (1)
Standard MAC configurable length
Encrypt/Decrypt Parameter
In SYM_MODE_CBC, the parameter buffer must contain the IV (8 bytes). In SYM_MODE_ECB, there are no parameters.
MAC Parameters
When mode is SYM_MODE_MAC_GEN, parameter buffer contains at least 4 bytes, which is the little-endian encoding of an integer. The integer value must contain a value from 1 to 8, indicating the number of bytes to return.
RC2 Cipher Object
Operations Supported
Encrypt, Decrypt, Multi-Part MAC, Multi-Part MAC Verify
Key Encoding
128 byte (Max)
Encrypt/Decrypt Modes
The least significant nibble (four bits) is used to determine the operational mode. The following list defines the possible values:
>SYM_MODE_ECB (0)
Electronic Code Book (ECB) mode. It may be combined with a padding mode (see below).
>SYM_MODE_CBC (1)
Cipher Block Chaining (CBC) mode. It may be combined with a padding mode (see below).
MAC modes
For MAC generation and verification the following modes are available:
>SYM_MODE_MAC_3 (0)
Standard CBC
>SYM_MODE_MAC_GEN (1)
Standard CBC with configurable MAC length (max 8 bytes).
Encrypt/Decrypt Parameters
In SYM_MODE_CBC, the parameter buffer must contain the IV (8 bytes). In SYM_MODE_ECB, there are no parameters.
MAC Parameters
When mode is SYM_MODE_MAC_GEN, parameter buffer contains at least 4 bytes, which is the little-endian encoding of an integer. The integer value must contain a value from 1 to 8, indicating the number of bytes of the final IV that will be used as the MAC.
RC4 Cipher Object
Operations Supported
Encrypt/Decrypt
Key Encoding
256 byte (Max)
Encrypt/Decrypt Modes
None
Encrypt/Decrypt Parameters
None
RSA Cipher Object
Operations Supported
New, Free, GetInfo, EncInit, DecInit, SignInit, VerifyInit, EncryptUpdate, DecryptUpdate, SignRecover, VerifyRecover and Verify.
To perform an encrypt call
EncInit + EncryptUpdate
To perform a decrypt call
DecInit + DecryptUpdate
To generate a signature call
SignInit + SignRecover
To verify a signature call
> and view the recovered signature:
VerifyInit + VerifyRecover
> without viewing the signature:
VerifyInit + Verify
Key encoding
The key format depends on whether the operation is expecting a public key or a private key.
Private Keys are used by:
>DecInit
>SignInit
Public Keys are used by:
>EncInit
>VerifyInit
Public Keys are stored in a CtPubRsaKey structure
Private Keys are stored in a CtPriRsaKey structure (see RSA Key Structures).
RSA Modes and Parameters
X509 Mode
#define RSA_MODE_X509 0
X509 Mode is the RAW uncooked mode. No padding or any other transformations are applied by the Cipher Object.
There is no parameter for this mode.
PKCS Mode
#define RSA_MODE_PKCS 1
PKCS Mode pads the input data into a specified block format according to the methods described in PKCS #1. The actual block padding method depends on whether encryption or signing operations are being performed.
For Encryption and Decryption, Block Type 2 is used.
For Signing, Block Type 1 is used.
There is no parameter for this mode.
9796 Mode
#define RSA_MODE_9796 2
ISO 9796 is a signature method only. Encrypt and Decrypt are not supported.
There is no parameter for this mode.
OAEP Mode
#define RSA_MODE_OAEP 3
OAEP is an Encryption/Decryption method only. Signing and Verification operations are not supported.
The padding is performed using the OAEP block format defined in PKCS #1.
This mode requires a parameter which is a structure of type CK_RSA_PKCS_OAEP_PARAMS (see cryptoki.h).
Restrictions apply to the values of members of the parameter structure:
>hashAlg must be CKM_SHA_1, CKM_SHA_244, CKM_SHA_256, CKM_SHA_384, CKM_SHA_512, CKM_SHA3_256, CKM_SHA3_224, CKM_SHA3_384, or CKM_SHA3_512
>mgf must be CKG_MGF1_SHA1, CKG_MGF1_SHA224, CKG_MGF1_SHA256, CKG_MGF1_SHA384, CKG_MGF1_SHA512, CKG_MGF1_SHA3_224, CKG_MGF1_SHA3_256, CKG_MGF1_SHA3_384, or CKG_MGF1_SHA3_512
>source must be CKZ_DATA_SPECIFIED
NOTE If you are using firmware 5.06.03 or older, the hash algorithm must be the same in hashAlg and mgf.
Example
unsigned char data [SZ_DATA];
RSA_PUBLIC_KEY pub;
CipherObj * pRsa;
CK_RSA_PKCS_OAEP_PARAMS param;
param.hashAlg = CKM_SHA_1;
param.mgf = CKG_MGF1_SHA1;
param.source = CKZ_DATA_SPECIFIED;
param.pSourceData = data;
param.sourceDataLen = SZ_DATA;
pRSA->EncInit(pRSA, RSA_MODE_OAEP, &pub, sizeof(pub),
¶m, sizeof(param));
NOTE The data pointed at by pSourceData must remain intact while the object is in use.
KEY WRAP OAEP Mode
#define RSA_MODE_KW_OAEP 4
Key Wrap OAEP is an Encryption/Decryption method only. Signing and Verification operations are not supported.
The padding is performed using the OAEP block format defined in PKCS #1 version 2.0
This mode requires a parameter which is a structure of type CK_KEY_WRAP_SET_OAEP_PARAMS (see cryptoki.h).
RSA Key Structures
#define MAX_RSA_MOD_BYTES (4096/8)
#define MAX_RSA_PRIME_BYTES ((MAX_RSA_MOD_BYTES / 2) + 4)
typedef unsigned char byte;
typedef struct {
byte bits[2]; /* not used */
byte mod [MAX_RSA_MOD_BYTES];
byte exp [MAX_RSA_MOD_BYTES];
}
RSA_PUBLIC_KEY;
struct CtPubRsaKey {
int isPub;/* TRUE */
unsigned int modSz; /* in bytes */
RSA_PUBLIC_KEY key;
};
typedef struct CtPubRsaKey CtPubRsaKey;
typedef struct {
byte bits[2]; /* not used */
byte mod [MAX_RSA_MOD_BYTES];
byte pub [MAX_RSA_MOD_BYTES];
byte pri [MAX_RSA_MOD_BYTES];
byte p [MAX_RSA_PRIME_BYTES];
byte q [MAX_RSA_PRIME_BYTES];
byte e1 [MAX_RSA_PRIME_BYTES];
byte e2 [MAX_RSA_PRIME_BYTES];
byte u [MAX_RSA_PRIME_BYTES];
}
RSA_PRIVATE_KEY_XCRT;
struct CtPriRsaKey {
int isPub;/* FALSE */
int isXcrt;/* TRUE */
unsigned int modSz; /* significant size in bytes */
RSA_PRIVATE_KEY_XCRT key;
};
typedef struct CtPriRsaKey CtPriRsaKey;
NOTE All values stored Big Endian i.e. most significant byte in mod[0] and least significant byte in mod[MAX_RSA_MOD_BYTES-1].
