SIAP support header Common defined parameters and functions of the SIAP client and server implementations. More...

#include "siapcommon.h"
#include "logger.h"
#include "sha3.h"
#include "socket.h"
#include "socketclient.h"

Data Structures
struct	siap_device_key
	The SIAP device key structure. This structure contains the SIAP device key, the device key identity, and expiration time. More...
struct	siap_device_tag
struct	siap_server_key
	The SIAP server key structure. This structure contains the SIAP server key, the server's domain identity, the device key, and expiration time. More...

Macros
#define	SIAP_CLIENT_PASSWORD_MAX 256U
	The client passphrase maximum string length.
#define	SIAP_CLIENT_USERNAME_MAX 256U
	The client username maximum string length.
#define	SIAP_CONFIG_SIZE 26U
	The size of the protocol configuration string.
#define	SIAP_DEVICE_ID_SIZE 4U
	Key card device ID size in bytes.
#define	SIAP_AUTHENTICATION_TOKEN_SIZE 32U
	The client key size in bytes.
#define	SIAP_DOMAIN_ID_SIZE 2U
	Domain (Master) ID size in bytes.
#define	SIAP_ERROR_SIZE 1U
	The size of a system error message.
#define	SIAP_EXPIRATION_SIZE 8U
	The size (in bytes) of the expiration field.
#define	SIAP_HASH_SIZE 32U
	The SIAP hash size in bytes.
#define	SIAP_KEY_DURATION_DAYS 365U
	The number of days a key remains valid.
#define	SIAP_KEY_DURATION_SECONDS (SIAP_KEY_DURATION_DAYS * 24U * 60U * 60U)
	The number of seconds a key remains valid.
#define	SIAP_KEY_ID_SIZE 4U
	User key ID size in bytes.
#define	SIAP_KTREE_COUNT 1024
	The SIAP key tree count.
#define	SIAP_KTAG_STATE_HASH 32U
	The client key state hash size.
#define	SIAP_MAC_SIZE 32U
	The SIAP MAC size in bytes.
#define	SIAP_NONCE_SIZE 32U
	The nonce size.
#define	SIAP_SALT_SIZE 32U
	The SIAP salt size in bytes.
#define	SIAP_SERVER_GROUP_ID_SIZE 2U
	Server Group ID size in bytes.
#define	SIAP_SERVER_ID_SIZE 2U
	Server ID size in bytes.
#define	SIAP_SERVER_KEY_SIZE 32U
	The master key size in bytes.
#define	SIAP_USER_GROUP_ID_SIZE 2U
	User Group ID size in bytes.
#define	SIAP_USER_ID_SIZE 4U
	User ID size in bytes.
#define	SIAP_DID_SIZE (SIAP_DOMAIN_ID_SIZE + SIAP_SERVER_GROUP_ID_SIZE + SIAP_SERVER_ID_SIZE + SIAP_USER_GROUP_ID_SIZE + SIAP_USER_ID_SIZE + SIAP_DEVICE_ID_SIZE)
	The full sub-key ID size in bytes.
#define	SIAP_SID_SIZE (SIAP_DOMAIN_ID_SIZE + SIAP_SERVER_GROUP_ID_SIZE + SIAP_SERVER_ID_SIZE)
	The server ID size in bytes.
#define	SIAP_KID_SIZE (SIAP_DID_SIZE + SIAP_KEY_ID_SIZE)
	The tree-key ID size in bytes.
#define	SIAP_KTREE_SIZE (SIAP_AUTHENTICATION_TOKEN_SIZE * SIAP_KTREE_COUNT)
	The key tree size in bytes.
#define	SIAP_DEVICE_KEY_ENCODED_SIZE ((SIAP_AUTHENTICATION_TOKEN_SIZE * SIAP_KTREE_COUNT) + SIAP_MAC_SIZE + SIAP_KID_SIZE + SIAP_EXPIRATION_SIZE)
	The device key size in bytes.
#define	SIAP_DEVICE_TAG_ENCODED_SIZE (SIAP_KID_SIZE + SIAP_KTAG_STATE_HASH + SIAP_HASH_SIZE)
	The device tag size in bytes.
#define	SIAP_SERVER_KEY_ENCODED_SIZE (SIAP_SERVER_KEY_SIZE + SIAP_SID_SIZE + SIAP_SERVER_KEY_SIZE + SIAP_EXPIRATION_SIZE)
	The server key size in bytes.

Typedefs
typedef SIAP_EXPORT_API enum siap_errors	siap_errors
typedef SIAP_EXPORT_API struct siap_device_key	siap_device_key
typedef SIAP_EXPORT_API struct siap_device_tag	siap_device_tag
typedef SIAP_EXPORT_API struct siap_server_key	siap_server_key

Enumerations
enum	siap_errors { siap_error_none = 0x00U , siap_error_authentication_failure = 0x01U , siap_error_identity_mismatch = 0x02U , siap_error_key_expired = 0x03U , siap_error_passphrase_unrecognized = 0x04U , siap_error_token_tree_invalid = 0x05U , siap_error_decryption_failure = 0x06U , siap_error_token_invalid = 0x07U , siap_error_token_not_created = 0x08U , siap_error_file_read_failure = 0x09U , siap_error_file_invalid_path = 0x0AU , siap_error_file_copy_failure = 0x0BU }
	The SIAP error values. This enumeration defines the error codes returned by SIAP functions. More...

Functions
SIAP_EXPORT_API void	siap_deserialize_device_key (siap_device_key dkey, const uint8_t input)
	Deserialize a client device key. This function deserializes a byte array into a SIAP device key structure.
SIAP_EXPORT_API void	siap_serialize_device_key (uint8_t output, const siap_device_key dkey)
	Serialize a client device key. This function serializes a SIAP device key structure into a byte array.
SIAP_EXPORT_API const char *	siap_error_to_string (siap_errors error)
	Return a string description of an SIAP error code. This function returns a human-readable string corresponding to the provided SIAP error code.
SIAP_EXPORT_API const char *	siap_get_error_description (siap_errors emsg)
	Get the error string description.
SIAP_EXPORT_API void	siap_log_error (siap_errors emsg, const char *msg)
	Log the message, socket error, and string description.
SIAP_EXPORT_API void	siap_log_system_error (siap_errors err)
	Log a system error message.
SIAP_EXPORT_API void	siap_deserialize_device_tag (siap_device_tag dtag, const uint8_t input)
	Deserialize a device tag from a byte array. This function deserializes a byte array into a SIAP device tag structure.
SIAP_EXPORT_API void	siap_serialize_device_tag (uint8_t output, const siap_device_tag dtag)
	Serialize a device tag into a byte array. This function serializes a SIAP device tag structure into a byte array.
SIAP_EXPORT_API void	siap_deserialize_server_key (siap_server_key skey, const uint8_t input)
	Deserialize a server key from a byte array. This function deserializes a byte array into a SIAP server key structure.
SIAP_EXPORT_API void	siap_serialize_server_key (uint8_t output, const siap_server_key skey)
	Serialize a server key into a byte array. This function serializes a SIAP server key structure into a byte array.
SIAP_EXPORT_API void	siap_increment_device_key (siap_device_key *dkey)
	Increment the device key This function clears a key at the current position and increments the kid counter.

Detailed Description

SIAP support header Common defined parameters and functions of the SIAP client and server implementations.

Enumeration Type Documentation

◆ siap_errors

enum siap_errors

The SIAP error values. This enumeration defines the error codes returned by SIAP functions.

Enumerator
siap_error_none	The operation was succesful
siap_error_authentication_failure	The authentication has failed
siap_error_identity_mismatch	The identity strings do not match
siap_error_key_expired	The key card has expired
siap_error_passphrase_unrecognized	The device passphrase is unrecognized
siap_error_token_tree_invalid	The cards authentication tokens are invalid
siap_error_decryption_failure	The key card decryption failed
siap_error_token_invalid	The authentication token is invalid
siap_error_token_not_created	The server could not generate the token
siap_error_file_read_failure	The file could not be read
siap_error_file_invalid_path	The file path specified is invalid
siap_error_file_copy_failure	The file is locked or unavailable

Function Documentation

◆ siap_deserialize_device_key()

SIAP_EXPORT_API void siap_deserialize_device_key	(	siap_device_key *	dkey,
		const uint8_t *	input )

Deserialize a client device key. This function deserializes a byte array into a SIAP device key structure.

Parameters

dkey	A pointer to the output SIAP device key structure.
input	[const] The input serialized device key array of size `SIAP_DEVICE_KEY_ENCODED_SIZE`.

◆ siap_deserialize_device_tag()

SIAP_EXPORT_API void siap_deserialize_device_tag	(	siap_device_tag *	dtag,
		const uint8_t *	input )

Deserialize a device tag from a byte array. This function deserializes a byte array into a SIAP device tag structure.

Parameters

dtag	A pointer to the output SIAP device tag structure.
input	[const] The input serialized device tag array of size `SIAP_DEVICE_TAG_ENCODED_SIZE`.

◆ siap_deserialize_server_key()

SIAP_EXPORT_API void siap_deserialize_server_key	(	siap_server_key *	skey,
		const uint8_t *	input )

Deserialize a server key from a byte array. This function deserializes a byte array into a SIAP server key structure.

Parameters

skey	A pointer to the output SIAP server key structure.
input	[const] The input serialized server key array of size `SIAP_SERVER_KEY_ENCODED_SIZE`.

◆ siap_error_to_string()

SIAP_EXPORT_API const char * siap_error_to_string ( siap_errors error )

Return a string description of an SIAP error code. This function returns a human-readable string corresponding to the provided SIAP error code.

Parameters

error The SIAP error code.

Returns: Returns a pointer to the error description string, or NULL if the error code is not recognized.

◆ siap_get_error_description()

SIAP_EXPORT_API const char * siap_get_error_description ( siap_errors emsg )

Get the error string description.

Parameters

emsg	The message enumeration

Returns: Returns a pointer to the message string or NULL

◆ siap_increment_device_key()

SIAP_EXPORT_API void siap_increment_device_key ( siap_device_key * dkey )

Increment the device key This function clears a key at the current position and increments the kid counter.

Parameters

dkey	[const] A pointer to the input/output SIAP device key structure.

◆ siap_log_error()

SIAP_EXPORT_API void siap_log_error	(	siap_errors	emsg,
		const char *	msg )

Log the message, socket error, and string description.

Parameters

emsg	The message enumeration
msg	[const] The message string

◆ siap_log_system_error()

SIAP_EXPORT_API void siap_log_system_error ( siap_errors err )

Log a system error message.

Parameters

err	The system error enumerator

◆ siap_serialize_device_key()

SIAP_EXPORT_API void siap_serialize_device_key	(	uint8_t *	output,
		const siap_device_key *	dkey )

Serialize a client device key. This function serializes a SIAP device key structure into a byte array.

Parameters

output	The output byte array to hold the serialized device key array of size `SIAP_DEVICE_KEY_ENCODED_SIZE`.
dkey	[const] A pointer to the input SIAP device key structure.

◆ siap_serialize_device_tag()

SIAP_EXPORT_API void siap_serialize_device_tag	(	uint8_t *	output,
		const siap_device_tag *	dtag )

Serialize a device tag into a byte array. This function serializes a SIAP device tag structure into a byte array.

Parameters

output	The output byte array to hold the serialized device tag of size `SIAP_DEVICE_TAG_ENCODED_SIZE`.
dtag	[const] A pointer to the input SIAP device tag structure.

◆ siap_serialize_server_key()

SIAP_EXPORT_API void siap_serialize_server_key	(	uint8_t *	output,
		const siap_server_key *	skey )

Serialize a server key into a byte array. This function serializes a SIAP server key structure into a byte array.

Parameters

output	The output byte array to hold the serialized server key of size `SIAP_SERVER_KEY_ENCODED_SIZE`.
skey	[const] A pointer to the input SIAP server key structure.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ siap_errors

Function Documentation

◆ siap_deserialize_device_key()

◆ siap_deserialize_device_tag()

◆ siap_deserialize_server_key()

◆ siap_error_to_string()

◆ siap_get_error_description()

◆ siap_increment_device_key()

◆ siap_log_error()

◆ siap_log_system_error()

◆ siap_serialize_device_key()

◆ siap_serialize_device_tag()

◆ siap_serialize_server_key()