hkds_config.h File Reference

HKDS configuration definitions. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	hkds_packet_header
	The primary header for all HKDS messages. More...
struct	hkds_client_message_request
	Represents the client's encrypted message request packet. More...
struct	hkds_client_token_request
	Represents the client token request packet. More...
struct	hkds_server_message_response
	Represents the server's plaintext message response packet. More...
struct	hkds_server_token_response
	Represents the server's token response packet. More...
struct	hkds_administrative_message
	Represents an administrative message packet. More...
struct	hkds_error_message
	Represents an error message packet. More...

Macros
#define	HKDS_SHAKE_256
	Use the SHAKE-256 variant for HKDS.
#define	HKDS_CACHE_MULTIPLIER   4
	Defines the transaction key cache multiplier.
#define	HKDS_ADMIN_SIZE   2
	The size of the administrative message in bytes.
#define	HKDS_AUTHENTICATION_KMAC   0x11
	The KMAC authentication mode designator contained in a client's DID.
#define	HKDS_AUTHENTICATION_NONE   0x10
	The authentication mode designator for no authentication.
#define	HKDS_AUTHENTICATION_SHA3   0x12
	The SHA3 authentication mode designator contained in a client's DID.
#define	HKDS_PARALLEL_DEPTH   8
	The AVX512 depth multiplier.
#define	HKDS_CACHX8_DEPTH   8
	The AVX512 depth multiplier for cache operations.
#define	HKDS_CACHX64_SIZE   64
	The total number of tokens when using the multi-threaded/SIMD 3-d array (x64) API.
#define	HKDS_CTOK_SIZE   23
	Internal size of the token customization string.
#define	HKDS_DID_SIZE   12
	The device identity size in bytes.
#define	HKDS_ERROR_SIZE   16
	The error message size in bytes.
#define	HKDS_HEADER_SIZE   4
	The size of the HKDS packet header in bytes.
#define	HKDS_KID_SIZE   4
	The master key identity string size in bytes.
#define	HKDS_KSN_SIZE   16
	The Key Serial Number (KSN) size in bytes.
#define	HKDS_MESSAGE_SIZE   16
	The encrypted message size in bytes.
#define	HKDS_NAME_SIZE   7
	Internal: The formal algorithm name size in bytes.
#define	HKDS_TAG_SIZE   16
	The size of the authentication tag (MAC) in bytes.
#define	HKDS_TKC_SIZE   4
	The transaction key counter size (big endian) in bytes.
#define	HKDS_TMS_SIZE   (HKDS_KSN_SIZE + HKDS_NAME_SIZE)
	The size of the token MAC string.
#define	HKDS_BDK_SIZE   32
	The Base Derivation Key size for SHAKE-256 in bytes.
#define	HKDS_EDK_SIZE   32
	The Embedded Device Key size for SHAKE-256 in bytes.
#define	HKDS_ETOK_SIZE   48
	The encrypted token (server response) size for SHAKE-256 in bytes.
#define	HKDS_PRF_RATE   136
	The output length of the underlying PRF (SHAKE-256) in bytes.
#define	HKDS_PROTOCOL_TYPE   protocol_shake_256
	The protocol type supported by this implementation (SHAKE-256).
#define	HKDS_STK_SIZE   32
	The Secret Token Key size for SHAKE-256 in bytes.
#define	HKDS_CACHE_SIZE   ((HKDS_CACHE_MULTIPLIER * HKDS_PRF_RATE) / HKDS_MESSAGE_SIZE)
	The size of the transaction key cache.
#define	HKDS_CLIENT_MESSAGE_REQUEST_SIZE   (HKDS_HEADER_SIZE + HKDS_KSN_SIZE + HKDS_MESSAGE_SIZE + HKDS_TAG_SIZE)
	The size of the client message request packet.
#define	HKDS_CLIENT_TOKEN_REQUEST_SIZE   (HKDS_HEADER_SIZE + HKDS_KSN_SIZE)
	The size of the client token request packet.
#define	HKDS_SERVER_MESSAGE_RESPONSE_SIZE   (HKDS_HEADER_SIZE + HKDS_MESSAGE_SIZE)
	The size of the server message response packet.
#define	HKDS_SERVER_TOKEN_RESPONSE_SIZE   (HKDS_HEADER_SIZE + HKDS_ETOK_SIZE)
	The size of the server token response packet.
#define	HKDS_ADMIN_MESSAGE_SIZE   (HKDS_HEADER_SIZE + HKDS_ADMIN_SIZE)
	The size of the administrative message packet.
#define	HKDS_ERROR_MESSAGE_SIZE   (HKDS_HEADER_SIZE + HKDS_ERROR_SIZE)
	The size of the error message packet.

Typedefs
typedef enum hkds_packet_type	hkds_packet_type
typedef enum hkds_protocol_id	hkds_protocol_id
typedef enum hkds_error_type	hkds_error_type
typedef enum hkds_message_type	hkds_message_type

Enumerations
enum	hkds_packet_type {   packet_token_request = 0x01 , packet_token_response = 0x02 , packet_message_request = 0x03 , packet_message_response = 0x04 ,   packet_administrative_message = 0x05 , packet_error_message = 0x06 }
	Enumerates the types of packets used in HKDS communications. More...
enum	hkds_protocol_id { protocol_shake_128 = 0x09 , protocol_shake_256 = 0x0A , protocol_shake_512 = 0x0B }
	Enumerates the supported cryptographic protocol identifiers. More...
enum	hkds_error_type {   error_general_failure = 0x1F , error_connection_aborted = 0x21 , error_disconnected = 0x22 , error_connection_refused = 0x23 ,   error_invalid_format = 0x24 , error_retries_exceeded = 0x25 , error_connection_failure = 0x26 , error_unkown_failure = 0xFF }
	Enumerates the error types for HKDS packet communications. More...
enum	hkds_message_type {   message_synchronize_token = 0x01 , message_reinitialized_token = 0x02 , message_token_requests_exceeded = 0x03 , message_remote_reset = 0x04 ,   message_diagnostic = 0x05 , message_reserved1 = 0x06 , message_reserved2 = 0x07 , message_reserved3 = 0x08 }
	Enumerates the HKDS packet message types. More...

Detailed Description

HKDS configuration definitions.

This header file defines the configuration parameters, enumerations, macros, and structures used by the Hierarchical Key Derivation System (HKDS) protocol. The HKDS protocol leverages cryptographic primitives (such as SHA-3, SHAKE, and KMAC) to securely exchange tokens and messages between client devices and a transaction server.

The file is organized as follows:

• Enumerations: Define the packet types, protocol identifiers, error types, and message types used in HKDS communications.
• Modifiable Values: Macros allowing customization of the Keccak round settings, SHAKE implementations, and key cache multiplier.
• Static Values: Fixed-size constants (key sizes, message sizes, identifiers, etc.) required for the HKDS protocol.
• Packet Headers: Structures that describe the layout of the various HKDS message packets.

These definitions ensure consistency across the protocol implementation and allow flexibility to adapt the system to different security levels and performance requirements.

Macro Definition Documentation

HKDS_ADMIN_MESSAGE_SIZE

#define HKDS_ADMIN_MESSAGE_SIZE   (HKDS_HEADER_SIZE + HKDS_ADMIN_SIZE)

The size of the administrative message packet.

This size is computed as the sum of the header size and the administrative message size.

HKDS_CACHE_MULTIPLIER

#define HKDS_CACHE_MULTIPLIER   4

Defines the transaction key cache multiplier.

Changes the size of the transaction key cache. Allowed values are multiples of 2 (2, 4, 6, 8, 10, and 12). A larger multiplier results in fewer token exchanges, but leads to slower decryption and a larger client cache. The recommended value is 4, and it should not exceed 8.

HKDS_CACHE_SIZE

#define HKDS_CACHE_SIZE   ((HKDS_CACHE_MULTIPLIER * HKDS_PRF_RATE) / HKDS_MESSAGE_SIZE)

The size of the transaction key cache.

Calculated as ((HKDS_CACHE_MULTIPLIER * HKDS_PRF_RATE) / HKDS_MESSAGE_SIZE).

HKDS_CACHX8_DEPTH

#define HKDS_CACHX8_DEPTH   8

The AVX512 depth multiplier for cache operations.

Specifies the number of simultaneous operations when using the (x8) SIMD API.

HKDS_CLIENT_MESSAGE_REQUEST_SIZE

#define HKDS_CLIENT_MESSAGE_REQUEST_SIZE   (HKDS_HEADER_SIZE + HKDS_KSN_SIZE + HKDS_MESSAGE_SIZE + HKDS_TAG_SIZE)

The size of the client message request packet.

This size is computed as the sum of the header size, KSN size, message size, and tag size.

HKDS_CLIENT_TOKEN_REQUEST_SIZE

#define HKDS_CLIENT_TOKEN_REQUEST_SIZE   (HKDS_HEADER_SIZE + HKDS_KSN_SIZE)

The size of the client token request packet.

This size is computed as the sum of the header size and the KSN size.

HKDS_ERROR_MESSAGE_SIZE

#define HKDS_ERROR_MESSAGE_SIZE   (HKDS_HEADER_SIZE + HKDS_ERROR_SIZE)

The size of the error message packet.

This size is computed as the sum of the header size and the error message size.

HKDS_PARALLEL_DEPTH

#define HKDS_PARALLEL_DEPTH   8

The AVX512 depth multiplier.

Specifies the number of simultaneous server decryption and token generation operations when using the (x8) SIMD API.

HKDS_SERVER_MESSAGE_RESPONSE_SIZE

#define HKDS_SERVER_MESSAGE_RESPONSE_SIZE   (HKDS_HEADER_SIZE + HKDS_MESSAGE_SIZE)

The size of the server message response packet.

This size is computed as the sum of the header size and the message size.

HKDS_SERVER_TOKEN_RESPONSE_SIZE

#define HKDS_SERVER_TOKEN_RESPONSE_SIZE   (HKDS_HEADER_SIZE + HKDS_ETOK_SIZE)

The size of the server token response packet.

This size is computed as the sum of the header size and the encrypted token size.

HKDS_SHAKE_256

#define HKDS_SHAKE_256

Use the SHAKE-256 variant for HKDS.

When defined, the implementation uses SHAKE-256 for cryptographic operations.

HKDS_TMS_SIZE

#define HKDS_TMS_SIZE   (HKDS_KSN_SIZE + HKDS_NAME_SIZE)

The size of the token MAC string.

This value is computed as the sum of the KSN size and the formal name size.

Enumeration Type Documentation

hkds_error_type

enum hkds_error_type

Enumerates the error types for HKDS packet communications.

This enumeration defines the error codes that may be communicated in HKDS error messages:

• error_general_failure: General failure.
• error_connection_aborted: The connection was aborted by the remote host.
• error_disconnected: The network link was lost.
• error_connection_refused: The connection was refused by the remote host.
• error_invalid_format: The request format was invalid.
• error_retries_exceeded: The allowed number of retries was exceeded.
• error_connection_failure: The connection experienced a general failure.
• error_unkown_failure: The cause of failure is unknown.

Enumerator
error_general_failure	General failure
error_connection_aborted	The connection was aborted by the remote host
error_disconnected	The network link was lost
error_connection_refused	The connection was refused by the remote host
error_invalid_format	The request format was invalid
error_retries_exceeded	The allowed number of retries was exceeded
error_connection_failure	The connection had a general failure
error_unkown_failure	The cause of failure is unknown

hkds_message_type

enum hkds_message_type

Enumerates the HKDS packet message types.

This enumeration defines the specific message types sent after token processing:

• message_synchronize_token: Sent by the client when a token key fails authentication.
• message_reinitialized_token: The server's (optional) response to a token key rejection.
• message_token_requests_exceeded: Indicates that the maximum number of token failures has occurred.
• message_remote_reset: Sent by the server to remotely reset the client terminal.
• message_diagnostic: Requests diagnostic output from the terminal's hardware components.
• message_reserved1, message_reserved2, message_reserved3: Reserved for future use.

Enumerator
message_synchronize_token	Sent by the client indicating a token key failure
message_reinitialized_token	The server's response to a token key rejection
message_token_requests_exceeded	The server indicates that maximum token failures occurred
message_remote_reset	The server sends a remote reset to the client terminal
message_diagnostic	The server requests diagnostic output
message_reserved1	Reserved message 1
message_reserved2	Reserved message 2
message_reserved3	Reserved message 3

hkds_packet_type

enum hkds_packet_type

Enumerates the types of packets used in HKDS communications.

This enumeration defines the various packet types exchanged between client and server:

• packet_token_request: A client token request.
• packet_token_response: A server token response.
• packet_message_request: A client message request.
• packet_message_response: A server message response.
• packet_administrative_message: An administrative message.
• packet_error_message: An error message.

Enumerator
packet_token_request	A client token request
packet_token_response	A server token response
packet_message_request	A client message request
packet_message_response	A server message response
packet_administrative_message	An administrative message
packet_error_message	An error message

hkds_protocol_id

enum hkds_protocol_id

Enumerates the supported cryptographic protocol identifiers.

This enumeration specifies which SHAKE variant is employed by the HKDS protocol:

• protocol_shake_128: Uses SHAKE-128.
• protocol_shake_256: Uses SHAKE-256.
• protocol_shake_512: Uses SHAKE-512.

Enumerator
protocol_shake_128	Protocol is SHAKE-128
protocol_shake_256	Protocol is SHAKE-256
protocol_shake_512	Protocol is SHAKE-512