1.1ChaCha20

ChaCha20 is a secret-key stream cipher described in [CHACHA].

Table1,ChaCha20 Mechanisms vs. Functions

Functions
Mechanism / Encrypt
Decrypt / Sign
Verify / SR
VR1 / Digest / Gen.
Key/
Key
Pair / Wrap
Unwrap / Derive
CKM_CHACHA20_KEY_GEN / ✓
CKM_CHACHA20 / ✓ / ✓

1.1.1Definitions

This section defines the key type “CKK_CHACHA20” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.

Mechanisms:

CKM_CHACHA20_KEY_GEN

CKM_CHACHA20

1.1.2ChaCha20 secret key objects

ChaCha20 secret key objects (object class CKO_SECRET_KEY, key type CKK_CHACHA) hold ChaCha20 keys. The following table defines the ChaCha20 secret key object attributes, in addition to the common attributes defined for this object class:

Table 2, ChaCha20 Secret Key Object

Attribute / Data type / Meaning
CKA_VALUE1,4,6,7 / Byte array / Key length is fixed at 256 bits. Bit length restricted to a byte array.
CKA_VALUE_LEN2,3 / CK_ULONG / Length in bytes of key value

The following is a sample template for creating a ChaCha20 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;

CK_KEY_TYPE keyType = CKK_CHACHA20;

CK_UTF8CHAR label[] = “A ChaCha20 secret key object”;

CK_BYTE value[32] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

{CKA_CLASS, &class, sizeof(class)},

{CKA_KEY_TYPE, &keyType, sizeof(keyType)},

{CKA_TOKEN, &true, sizeof(true)},

{CKA_LABEL, label, sizeof(label)-1},

{CKA_ENCRYPT, &true, sizeof(true)},

{CKA_VALUE, value, sizeof(value)}

};

1.1.3ChaCha20 mechanism parameters

1.1.3.1CK_CHACHA20_PARAMS; CK_CHACHA20_PARAMS_PTR

CK_CHACHA20_PARAMS provides the parameters to the CKM_CHACHA20 mechanism. It is defined as follows:

typedef struct CK_CHACHA20_PARAMS {

CK_BYTE_PTRpIv;

CK_ULONGulIvLen;

CK_ULONGnonce;

} CK_CHACHA20_PARAMS;

The fields of the structure have the following meanings:

pIVpointer to initialization vector (IV)

ulIVLenlength of initialization vector (must be 96 bits)

nonce32 bit initial counter (This can be any number, but will usually be zero or one)

1.1.4ChaCha20 key generation

The ChaCha20 key generation mechanism, denoted CKM_CHACHA20_KEY_GEN, is a key generation mechanism for ChaCha20.

It does not have a parameter.

The mechanism generates ChaCha20 keys with a particular length, as specified in the CKA_VALUE_LEN attribute of the template for the key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of key sizes in bytes. As a practical matter, the key size for ChaCha20 is fixed at 256 bits.

1.1.5ChaCha20 mechanism

ChaCha20, denoted CKM_CHACHA20, is a mechanism for single and multiple-part encryption and decryption based on the ChaCha20 stream cipher.

It has a parameter, CK_CHACHA20_PARAMS, which indicates the IV and initial counter value.

Constraints on key types and the length of input and output data are summarized in the following table:

Table 3, ChaCha20: Key and Data Length

Function / Key type / Input length / Output length / Comments
C_Encrypt / ChaCha20 / Any / Same as input length / No final part
C_Decrypt / ChaCha20 / Any / Same as input length / No final part

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of ChaCha20 key sizes, in bits.

1.2Poly1305

Poly1305 is a message authentication code designed by D.J Bernsterin [POLY1305]. Poly1305 takes a 256 bit key and a message and produces a 128 bit tag that is used to verify the message.

Table4,Poly1305 Mechanisms vs. Functions

Functions
Mechanism / Encrypt
Decrypt / Sign
Verify / SR
VR1 / Digest / Gen.
Key/
Key
Pair / Wrap
Unwrap / Derive
CKM_POLY1305_KEY_GEN / ✓
CKM_POLY1305 / ✓

1.2.1Definitions

This section defines the key type “CKK_POLY1305” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.

Mechanisms:

CKM_POLY1305_KEY_GEN

CKM_POLY1305_MAC

1.2.2Poly1305 secret key objects

Poly1305 secret key objects (object class CKO_SECRET_KEY, key type CKK_POLY1305) hold Poly1305 keys. The following table defines the Poly1305 secret key object attributes, in addition to the common attributes defined for this object class:

Table 5, Poly1305 Secret Key Object

Attribute / Data type / Meaning
CKA_VALUE1,4,6,7 / Byte array / Key length is fixed at 256 bits. Bit length restricted to a byte array.
CKA_VALUE_LEN2,3 / CK_ULONG / Length in bytes of key value

The following is a sample template for creating a Poly1305 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;

CK_KEY_TYPE keyType = CKK_POLY1305;

CK_UTF8CHAR label[] = “A Poly1305 secret key object”;

CK_BYTE value[32] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

{CKA_CLASS, &class, sizeof(class)},

{CKA_KEY_TYPE, &keyType, sizeof(keyType)},

{CKA_TOKEN, &true, sizeof(true)},

{CKA_LABEL, label, sizeof(label)-1},

{CKA_SIGN, &true, sizeof(true)},

{CKA_VALUE, value, sizeof(value)}

};

1.2.3Poly1305 mechanism

Poly1305, denoted CKM_POLY1305, is a mechanism for producing an output tag based on a 256 bit key and arbitrary length input.

It has no parameters.

Signatures (MACs) produced by this mechanism will be fixed at 128 bits in size.

Table 6, Poly1305: Key and Data Length

Function / Key type / Data length / Signature Length
C_Sign / Poly1305 / Any / 128 bits
C_Verify / Poly1305 / Any / 128 bits

B.3 Key types

#define CKK_CHACHA200x00000033

#define CKK_POLY13050x00000034

B.4 Mechanisms

#define CKM_CHACHA20_KEY_GEN0x00001225

#define CKM_CHACHA200x00001226

#define CKM_POLY1305_KEY_GEN0x00001227

#define CKM_POLY13050x00001228