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

#include "satpcommon.h"
#include "sha3.h"
#include "socket.h"
#include "socketclient.h"
#include "rcs.h"

Data Structures
struct	satp_connection_state
	The SATP socket connection state structure. More...
struct	satp_device_key
	The SATP device key structure. This structure represents the SATP device key, which is derived from the server key. It includes the device key identity, device derivation key, and an expiration time. More...
struct	satp_master_key
	The SATP master key structure. This structure holds the SATP master key information, including the key identity, the master derivation key, and the expiration time. The master key is used as the root from which branch keys are derived. More...
struct	satp_server_key
	The SATP server key structure. This structure represents the SATP server key, which is derived from the master key. It contains the server's key identity, server derivation key, and expiration time. More...
struct	qsmp_keep_alive_state
	The SATP keep alive state structure. This structure tracks the state of keep alive messages within SATP. It includes the epoch time when the last keep alive message was sent, a packet sequence counter, and a flag indicating whether a response has been received. More...
struct	satp_network_packet
	The SATP network packet structure. This structure defines the format of a SATP network packet. It includes a packet flag, the message length, a sequence number, a UTC timestamp for packet creation, and a pointer to the message data. More...

Macros
#define	SATP_USE_RCS_ENCRYPTION
	If the RCS encryption option is chosen SATP uses the more modern RCS stream cipher with KMAC/QMAC authentication. The default symmetric cipher/authenticator is AES-256/GCM (GMAC Counter Mode) NIST standardized per SP800-38a.
#define	satp_cipher_state qsc_rcs_state
#define	satp_cipher_dispose qsc_rcs_dispose
#define	satp_cipher_initialize qsc_rcs_initialize
#define	satp_cipher_keyparams qsc_rcs_keyparams
#define	satp_cipher_set_associated qsc_rcs_set_associated
#define	satp_cipher_transform qsc_rcs_transform
#define	SATP_CLIENT_PASSWORD_MAX 256U
	The client passphrase maximum string length.
#define	SATP_CLIENT_USERNAME_MAX 256U
	The client username maximum string length.
#define	SATP_CONNECTIONS_INIT 1000U
	The intitial SATP connections queue size.
#define	SATP_CONNECTIONS_MAX 50000U
	The maximum number of connections.
#define	SATP_CONFIG_SIZE 25U
	The size of the protocol configuration string.
#define	SATP_ERROR_SIZE 1U
	The size of a system error message.
#define	SATP_EXPIRATION_SIZE 8U
	The size (in bytes) of the expiration field.
#define	SATP_HASH_SIZE 32U
	The SATP hash size in bytes.
#define	SATP_HEADER_SIZE 21U
	The SATP packet header size in bytes.
#define	SATP_KEEPALIVE_MESSAGE 8U
	The size (in bytes) of the keep alive integer message.
#define	SATP_KEEPALIVE_STRING 20U
	The keep alive string size in bytes.
#define	SATP_KEEPALIVE_TIMEOUT (300U * 1000U)
	The keep alive timeout in milliseconds (5 minutes).
#define	SATP_KEY_TREE_COUNT 1024
	The SATP key tree count.
#define	SATP_MACTAG_SIZE 32U
	The SATP configuration string for 256-bit security.
#define	SATP_MESSAGE_SIZE 1024U
	The message size (in bytes) used during a communications session.
#define	SATP_MESSAGE_MAX (SATP_MESSAGE_SIZE + SATP_HEADER_SIZE)
	The maximum message size in bytes (may exceed MTU).
#define	SATP_CONNECTION_MTU 1500U
	The SATP packet buffer size.
#define	SATP_NONCE_SIZE 32U
	The nonce size in bytes.
#define	SATP_SALT_SIZE 32U
	The SATP salt size in bytes.
#define	SATP_SERVER_PORT 2701U
	The default SATP server port number.
#define	SATP_SEQUENCE_TERMINATOR 0xFFFFFFFFUL
	The sequence number of a packet that closes a connection.
#define	SATP_KEY_DURATION_DAYS 365U
	The number of days a key remains valid.
#define	SATP_PACKET_TIME_THRESHOLD 60U
	The maximum number of seconds a packet is considered valid.
#define	SATP_KEY_DURATION_SECONDS (SATP_KEY_DURATION_DAYS * 24U * 60U * 60U)
	The number of seconds a key remains valid.
#define	SATP_BRANCH_ID_SIZE 2U
	Branch ID size in bytes.
#define	SATP_DOMAIN_ID_SIZE 2U
	Domain (Master) ID size in bytes.
#define	SATP_DEVICE_ID_SIZE 4U
	Device ID size in bytes.
#define	SATP_EPOCH_SIZE 2U
	Epoch class size in bytes.
#define	SATP_ERROR_MESSAGE_SIZE 1U
	The packet error message size.
#define	SATP_ERROR_SEQUENCE 0xFF00000000000000ULL
	The packet error sequence number.
#define	SATP_FLAG_SIZE 1
	The packet flag size.
#define	SATP_KEY_ID_SIZE 4U
	Key ID size in bytes.
#define	SATP_SERVICE_ID_SIZE 2U
	Service ID size in bytes.
#define	SATP_DID_SIZE (SATP_DOMAIN_ID_SIZE + SATP_BRANCH_ID_SIZE + SATP_EPOCH_SIZE + SATP_SERVICE_ID_SIZE + SATP_DEVICE_ID_SIZE)
	The full sub-key ID size in bytes.
#define	SATP_MID_SIZE (SATP_DOMAIN_ID_SIZE)
	The master key identity size in bytes.
#define	SATP_SID_SIZE (SATP_DOMAIN_ID_SIZE + SATP_BRANCH_ID_SIZE)
	The server ID size in bytes.
#define	SATP_KID_SIZE (SATP_DID_SIZE + SATP_KEY_ID_SIZE)
	The key ID size in bytes.
#define	SATP_DKEY_SIZE 32U
	The client key size in bytes.
#define	SATP_MKEY_SIZE 32U
	The master key size in bytes.
#define	SATP_SKEY_SIZE 32U
	The server key size in bytes.
#define	SATP_KTREE_SIZE (SATP_DKEY_SIZE * SATP_KEY_TREE_COUNT)
	The key tree size in bytes.
#define	SATP_DKEY_ENCODED_SIZE (SATP_KID_SIZE + SATP_SKEY_SIZE + SATP_EXPIRATION_SIZE + (SATP_DKEY_SIZE * SATP_KEY_TREE_COUNT))
	The serialized device key size in bytes.
#define	SATP_MKEY_ENCODED_SIZE (SATP_MKEY_SIZE + SATP_MID_SIZE + SATP_EXPIRATION_SIZE)
	serialized master key size in bytes.
#define	SATP_SKEY_ENCODED_SIZE (SATP_SKEY_SIZE + SATP_SKEY_SIZE + SATP_SID_SIZE + SATP_EXPIRATION_SIZE)
	serialized server key size in bytes.
#define	SATP_STOK_SIZE 32U
	The session token size in bytes.

Typedefs
typedef SATP_EXPORT_API enum satp_errors	satp_errors
typedef SATP_EXPORT_API enum satp_flags	satp_flags
typedef SATP_EXPORT_API struct satp_connection_state	satp_connection_state
typedef SATP_EXPORT_API struct satp_device_key	satp_device_key
typedef SATP_EXPORT_API struct satp_master_key	satp_master_key
typedef SATP_EXPORT_API struct satp_server_key	satp_server_key
typedef SATP_EXPORT_API struct qsmp_keep_alive_state	satp_keep_alive_state
typedef SATP_EXPORT_API struct satp_network_packet	satp_network_packet

Enumerations
enum	satp_errors { satp_error_none = 0x00U , satp_error_accept_fail = 0x01 , satp_error_authentication_failure = 0x02U , satp_error_authentication_success = 0x03U , satp_erroe_listen_fail = 0x04U , satp_error_allocation_failure = 0x05U , satp_error_bad_keep_alive = 0x06U , satp_error_cipher_auth_failure = 0x07U , satp_error_channel_down = 0x08U , satp_error_connection_failure = 0x09U , satp_error_decryption_failure = 0x0AU , satp_error_device_unrecognized = 0x0BU , satp_error_establish_failure = 0x0CU , satp_error_hosts_exceeded = 0x0DU , satp_error_invalid_input = 0x0EU , satp_error_invalid_request = 0x0FU , satp_error_keep_alive_expired = 0x10U , satp_error_kex_auth_failure = 0x11U , satp_error_key_expired = 0x12U , satp_error_key_not_recognized = 0x13U , satp_error_listener_fail = 0x14U , satp_error_message_time_invalid = 0x15U , satp_error_packet_expired = 0x16U , satp_error_packet_unsequenced = 0x17U , satp_error_random_failure = 0x18U , satp_error_receive_failure = 0x19U , satp_error_transmit_failure = 0x1AU , satp_error_unknown_protocol = 0x1BU , satp_error_unsequenced = 0x1CU , satp_error_verify_failure = 0x1DU , satp_error_general_failure = 0xFFU }
	The SATP error values. This enumeration defines the error codes returned by SATP functions. More...
enum	satp_flags { satp_flag_none = 0x00U , satp_flag_connect_request = 0x01U , satp_flag_connect_response = 0x02U , satp_flag_connection_terminate = 0x03U , satp_flag_encrypted_message = 0x04U , satp_flag_authentication_request = 0x05U , satp_flag_authentication_response = 0x06U , satp_flag_auth_verify = 0x08U , satp_flag_keepalive_request = 0x09U , satp_flag_session_established = 0x0AU , satp_flag_error_condition = 0xFFU }
	The SATP packet flag values. This enumeration defines the flag values used in SATP packets to indicate the type and purpose of the packet. More...

Functions
SATP_EXPORT_API void	satp_connection_close (satp_connection_state *cns, satp_errors err, bool notify)
	Close the network connection between hosts.
SATP_EXPORT_API void	satp_connection_dispose (satp_connection_state *cns)
	Reset the connection state.
SATP_EXPORT_API satp_errors	satp_decrypt_error_message (satp_connection_state cns, uint8_t message)
	Decrypt an error message.
SATP_EXPORT_API satp_errors	satp_decrypt_packet (satp_connection_state cns, const satp_network_packet packetin, uint8_t message, size_t msglen)
	Decrypt an SATP packet.
SATP_EXPORT_API satp_errors	satp_encrypt_packet (satp_connection_state cns, const uint8_t message, size_t msglen, satp_network_packet *packetout)
	Encrypt a message into an SATP packet.
SATP_EXPORT_API void	satp_deserialize_device_key (satp_device_key dkey, const uint8_t input)
	Deserialize a client device key. This function deserializes a byte array into a SATP device key structure.
SATP_EXPORT_API void	satp_serialize_device_key (uint8_t output, const satp_device_key dkey)
	Serialize a client device key. This function serializes a SATP device key structure into a byte array.
SATP_EXPORT_API const char *	satp_error_to_string (satp_errors error)
	Return a string description of an SATP error code. This function returns a human-readable string corresponding to the provided SATP error code.
SATP_EXPORT_API bool	satp_extract_device_key (uint8_t dk, const uint8_t sk, const uint8_t *kid)
	Extract a device key. This function extracts a device key by hashing the server key and key identity.
SATP_EXPORT_API void	satp_packet_error_message (satp_network_packet *packet, satp_errors error)
	Populate a packet structure with an error message.
SATP_EXPORT_API void	satp_deserialize_master_key (satp_master_key mkey, const uint8_t input)
	Deserialize a master key from a byte array. This function deserializes a byte array into a SATP master key structure.
SATP_EXPORT_API void	satp_serialize_master_key (uint8_t output, const satp_master_key mkey)
	Serialize a master key into a byte array. This function serializes a SATP master key structure into a byte array.
SATP_EXPORT_API void	satp_deserialize_server_key (satp_server_key skey, const uint8_t input)
	Deserialize a server key from a byte array. This function deserializes a byte array into a SATP server key structure.
SATP_EXPORT_API void	satp_serialize_server_key (uint8_t output, const satp_server_key skey)
	Serialize a server key into a byte array. This function serializes a SATP server key structure into a byte array.
SATP_EXPORT_API void	satp_increment_device_key (uint8_t *sdkey)
	Increment the serialized key This function clears a key at the current position and increments the kid counter.
SATP_EXPORT_API bool	satp_generate_master_key (satp_master_key mkey, const uint8_t mid)
	Generate a master key-set. This function generates a new SATP master key-set. It populates the provided master key structure with a randomly generated master derivation key and the key identity, and sets the expiration time. The master key serves as the root from which branch keys are derived.
SATP_EXPORT_API bool	satp_generate_server_key (satp_server_key skey, const satp_master_key mkey, const uint8_t *sid)
	Generate a server key-set. This function generates a new SATP server key-set based on the provided master key. It populates the server key structure with a derived server key and sets the key identity and expiration time.
SATP_EXPORT_API void	satp_generate_device_key (satp_device_key dkey, const satp_server_key skey, const uint8_t *did)
	Generate a device key-set. This function generates a new SATP device key-set using the provided server key. It derives the device key from the server key and sets the key identity and expiration time.
SATP_EXPORT_API void	satp_packet_clear (satp_network_packet *packet)
	Clear a SATP network packet. This function resets the fields of a SATP network packet to zero, effectively clearing its state.
SATP_EXPORT_API void	satp_packet_header_create (satp_network_packet *packetout, satp_flags flag, uint64_t sequence, uint32_t msglen)
	Populate a packet header and set the creation time.
SATP_EXPORT_API void	satp_packet_header_deserialize (const uint8_t header, satp_network_packet packet)
	Deserialize a byte array into a SATP packet header. This function converts a serialized byte array representing a SATP packet header into a structured SATP network packet.
SATP_EXPORT_API void	satp_packet_header_serialize (const satp_network_packet packet, uint8_t header)
	Serialize a SATP packet header into a byte array. This function converts a structured SATP network packet header into a serialized byte array for transmission.
SATP_EXPORT_API satp_errors	satp_packet_header_validate (const satp_network_packet *packetin, satp_flags pktflag, uint64_t sequence, uint32_t msglen)
	Validate a packet header and timestamp.
SATP_EXPORT_API void	satp_packet_set_utc_time (satp_network_packet *packet)
	Set the local UTC seconds time in a SATP packet header. This function updates the SATP packet header with the current UTC time (in seconds).
SATP_EXPORT_API bool	satp_packet_time_valid (const satp_network_packet *packet)
	Check if a SATP packet is received within the valid time threshold. This function compares the UTC time in the SATP packet header against the local time to verify that the packet was received within the allowed time threshold.
SATP_EXPORT_API size_t	satp_packet_to_stream (const satp_network_packet packet, uint8_t pstream)
	Serialize a SATP packet into a byte array. This function converts a SATP network packet into a contiguous byte stream suitable for network transmission.
SATP_EXPORT_API void	satp_send_network_error (const qsc_socket *sock, satp_errors error)
	Send a plaintext SATP network error message Used only during key exchange, the connection close is sent over an encrypted tunnel.
SATP_EXPORT_API void	satp_stream_to_packet (const uint8_t pstream, satp_network_packet packet)
	Deserialize a byte stream into a SATP network packet. This function converts a contiguous byte stream into a structured SATP network packet.

Detailed Description

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

The SATP settings.

This header defines the configuration parameters, macros, and constants used in the Symmetric Key Distribution Protocol (SATP). SATP is designed to securely distribute symmetric keys between a master, server, device, and session while providing forward secrecy. The protocol employs ephemeral keys for each session, ensuring that even if a device or server key is compromised, past communications remain secure.

SATP is structured into several phases:

Connect Request: The client sends its identity string, configuration string, and a random session token to the server. The client computes a device session hash from its device ID, configuration, and token.
Connect Response: The server verifies the client's configuration and key identity, generates its own session token, computes its session hash, and responds with its server ID, configuration string, and token.
Exchange Request: The client generates a secret random token key, derives encryption and MAC keys using a combination of its device session hash and embedded key, and then encrypts and MACs the secret token before sending it to the server.
Exchange Response: The server verifies the MAC, decrypts the token, and derives the receive channel cipher key using its embedded key and the client's device session hash.
Establish Request: The client verifies the server's token hash and, if valid, encrypts its key identity to send to the server.
Establish Response: The server decrypts and verifies the key identity, then re-encrypts and echoes it back.
Establish Verify: The client decrypts the echoed key identity and verifies it, thereby finalizing the established session.

In addition, this header defines sizes for configuration strings, error messages, expiration fields, packet headers, keepalive messages, and various key and identity fields, ensuring consistency across SATP implementations.

Note: The SATP settings provided herein are critical for the proper operation and security of the key distribution process.

Macro Definition Documentation

◆ SATP_PACKET_TIME_THRESHOLD

#define SATP_PACKET_TIME_THRESHOLD 60U

The maximum number of seconds a packet is considered valid.

On networks with a shared (NTP) time source, this may be set to as low as 1 second. On exterior networks, it should be adjusted (typically between 30 and 100 seconds) to account for clock differences.

Enumeration Type Documentation

◆ satp_errors

enum satp_errors

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

Enumerator
satp_error_none	No error was detected
satp_error_accept_fail	The socket accept failed
satp_error_authentication_failure	The authentication failed
satp_error_authentication_success	The authentication succeeded
satp_erroe_listen_fail	The listener socket could not connect
satp_error_allocation_failure	The memory could not be allocated
satp_error_bad_keep_alive	The keep alive check failed
satp_error_cipher_auth_failure	The cipher authentication has failed
satp_error_channel_down	The communications channel has failed
satp_error_connection_failure	The device could not make a connection to the remote host
satp_error_decryption_failure	The decryption authentication has failed
satp_error_device_unrecognized	The device identity is unrecognized
satp_error_establish_failure	The transmission failed at the key exchange establish phase
satp_error_hosts_exceeded	The server has run out of socket connections
satp_error_invalid_input	The input provided is invalid
satp_error_invalid_request	The packet flag was unexpected
satp_error_keep_alive_expired	The keep alive has expired with no response
satp_error_kex_auth_failure	The key exchange authentication has failed
satp_error_key_expired	The SATP public key has expired
satp_error_key_not_recognized	The key identity is not recognized
satp_error_listener_fail	The listener function failed to initialize
satp_error_message_time_invalid	The packet has valid time expired
satp_error_packet_expired	The packet keep alive is invalid
satp_error_packet_unsequenced	The packet was received out of sequence
satp_error_random_failure	The random generator has failed
satp_error_receive_failure	The receiver failed at the network layer
satp_error_transmit_failure	The transmitter failed at the network layer
satp_error_unknown_protocol	The protocol string was not recognized
satp_error_unsequenced	The packets sequence number is out of sync
satp_error_verify_failure	The expected data could not be verified
satp_error_general_failure	A general failure occurred

◆ satp_flags

enum satp_flags

The SATP packet flag values. This enumeration defines the flag values used in SATP packets to indicate the type and purpose of the packet.

Enumerator
satp_flag_none	No flag was selected
satp_flag_connect_request	The packet contains a connection request
satp_flag_connect_response	The packet contains a connection response
satp_flag_connection_terminate	Indicates that the connection is to be terminated
satp_flag_encrypted_message	The packet contains an encrypted message
satp_flag_authentication_request	The packet contains an authentication request
satp_flag_authentication_response	The packet contains an authentication response
satp_flag_auth_verify	The packet contains an authentication verify message
satp_flag_keepalive_request	The packet is a keep alive request
satp_flag_session_established	Indicates that the session has been established
satp_flag_error_condition	Indicates that the connection experienced an error

Function Documentation

◆ satp_connection_close()

SATP_EXPORT_API void satp_connection_close	(	satp_connection_state *	cns,
		satp_errors	err,
		bool	notify )

Close the network connection between hosts.

Parameters

cns	A pointer to the connection state structure
err	The error message
notify	Notify the remote host connection is closing

◆ satp_connection_dispose()

SATP_EXPORT_API void satp_connection_dispose ( satp_connection_state * cns )

Reset the connection state.

Parameters

cns	A pointer to the connection state structure

◆ satp_decrypt_error_message()

SATP_EXPORT_API satp_errors satp_decrypt_error_message	(	satp_connection_state *	cns,
		uint8_t *	message )

Decrypt an error message.

Parameters

cns	A pointer to the SATP client state structure.
message	The serialized error packet.

Returns: Returns a value of type satp_errors indicating the error message.

◆ satp_decrypt_packet()

SATP_EXPORT_API satp_errors satp_decrypt_packet	(	satp_connection_state *	cns,
		const satp_network_packet *	packetin,
		uint8_t *	message,
		size_t *	msglen )

Decrypt an SATP packet.

This function decrypts the message contained in the input SATP network packet using the client's current decryption state, and copies the plaintext into the provided output buffer. The length of the decrypted message is returned via the msglen parameter.

Parameters

cns	A pointer to the SATP client state structure.
packetin	[const] A pointer to the input SATP network packet.
message	The output buffer where the decrypted message will be stored.
msglen	A pointer to a variable that receives the length of the decrypted message.

Returns: Returns a value of type satp_errors indicating the result of the decryption operation.

◆ satp_deserialize_device_key()

SATP_EXPORT_API void satp_deserialize_device_key	(	satp_device_key *	dkey,
		const uint8_t *	input )

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

Parameters

dkey	The output SATP device key structure.
input	The input serialized device key array of size `SATP_DEVKEY_ENCODED_SIZE`.

◆ satp_deserialize_master_key()

SATP_EXPORT_API void satp_deserialize_master_key	(	satp_master_key *	mkey,
		const uint8_t *	input )

Deserialize a master key from a byte array. This function deserializes a byte array into a SATP master key structure.

Parameters

mkey	The output SATP master key structure.
input	The input serialized master key array of size `SATP_MSTKEY_ENCODED_SIZE`.

◆ satp_deserialize_server_key()

SATP_EXPORT_API void satp_deserialize_server_key	(	satp_server_key *	skey,
		const uint8_t *	input )

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

Parameters

skey	The output SATP server key structure.
input	The input serialized server key array of size `SATP_SRVKEY_ENCODED_SIZE`.

◆ satp_encrypt_packet()

SATP_EXPORT_API satp_errors satp_encrypt_packet	(	satp_connection_state *	cns,
		const uint8_t *	message,
		size_t	msglen,
		satp_network_packet *	packetout )

Encrypt a message into an SATP packet.

This function encrypts the provided plaintext message using the client's current transmit cipher state. It then constructs an SATP network packet containing the encrypted message along with the appropriate header fields (such as message length, sequence number, and UTC timestamp), and outputs the packet via the provided structure.

Parameters

cns	A pointer to the SATP client state structure.
message	[const] The plaintext message to be encrypted.
msglen	The length of the plaintext message in bytes.
packetout	A pointer to the output SATP network packet structure.

Returns: Returns a value of type satp_errors indicating the success or failure of the encryption process.

◆ satp_error_to_string()

SATP_EXPORT_API const char * satp_error_to_string ( satp_errors error )

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

Parameters

error The SATP error code.

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

◆ satp_extract_device_key()

SATP_EXPORT_API bool satp_extract_device_key	(	uint8_t *	dk,
		const uint8_t *	sk,
		const uint8_t *	kid )

Extract a device key. This function extracts a device key by hashing the server key and key identity.

Parameters

dk	The pointer to the output device key array.
sk	The input server derivation key.
kid	The key identity including client id and key counter.

◆ satp_generate_device_key()

SATP_EXPORT_API void satp_generate_device_key	(	satp_device_key *	dkey,
		const satp_server_key *	skey,
		const uint8_t *	did )

Generate a device key-set. This function generates a new SATP device key-set using the provided server key. It derives the device key from the server key and sets the key identity and expiration time.

Parameters

dkey	A pointer to the SATP device key structure.
skey	[const] A pointer to the SATP server key structure.
did	[const] The key identity string.

◆ satp_generate_master_key()

SATP_EXPORT_API bool satp_generate_master_key	(	satp_master_key *	mkey,
		const uint8_t *	mid )

Generate a master key-set. This function generates a new SATP master key-set. It populates the provided master key structure with a randomly generated master derivation key and the key identity, and sets the expiration time. The master key serves as the root from which branch keys are derived.

Parameters

mkey	A pointer to the SATP master key structure.
mid	[const] The master key identity.

Returns: Returns false if the random generator fails; otherwise, returns true.

◆ satp_generate_server_key()

SATP_EXPORT_API bool satp_generate_server_key	(	satp_server_key *	skey,
		const satp_master_key *	mkey,
		const uint8_t *	sid )

Generate a server key-set. This function generates a new SATP server key-set based on the provided master key. It populates the server key structure with a derived server key and sets the key identity and expiration time.

Parameters

skey	A pointer to the SATP server key structure.
mkey	[const] A pointer to the SATP master key structure.
sid	[const] The key identity string.

Returns: Returns false if the random generator fails; otherwise, returns true.

◆ satp_increment_device_key()

SATP_EXPORT_API void satp_increment_device_key ( uint8_t * sdkey )

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

Parameters

sdkey The input/output serialized SATP server key structure.

◆ satp_packet_clear()

SATP_EXPORT_API void satp_packet_clear ( satp_network_packet * packet )

Clear a SATP network packet. This function resets the fields of a SATP network packet to zero, effectively clearing its state.

Parameters

packet A pointer to the SATP network packet to clear.

◆ satp_packet_error_message()

SATP_EXPORT_API void satp_packet_error_message	(	satp_network_packet *	packet,
		satp_errors	error )

Populate a packet structure with an error message.

Parameters

packet	A pointer to the packet structure
error	The error type

◆ satp_packet_header_create()

SATP_EXPORT_API void satp_packet_header_create	(	satp_network_packet *	packetout,
		satp_flags	flag,
		uint64_t	sequence,
		uint32_t	msglen )

Populate a packet header and set the creation time.

Parameters

packetout	A pointer to the output packet structure
flag	The packet flag
sequence	The packet sequence number
msglen	The length of the message array

◆ satp_packet_header_deserialize()

SATP_EXPORT_API void satp_packet_header_deserialize	(	const uint8_t *	header,
		satp_network_packet *	packet )

Deserialize a byte array into a SATP packet header. This function converts a serialized byte array representing a SATP packet header into a structured SATP network packet.

Parameters

header	A pointer to the input header byte array.
packet	A pointer to the SATP network packet structure to populate.

◆ satp_packet_header_serialize()

SATP_EXPORT_API void satp_packet_header_serialize	(	const satp_network_packet *	packet,
		uint8_t *	header )

Serialize a SATP packet header into a byte array. This function converts a structured SATP network packet header into a serialized byte array for transmission.

Parameters

packet	A pointer to the SATP network packet structure to serialize.
header	The output header byte array.

◆ satp_packet_header_validate()

SATP_EXPORT_API satp_errors satp_packet_header_validate	(	const satp_network_packet *	packetin,
		satp_flags	pktflag,
		uint64_t	sequence,
		uint32_t	msglen )

Validate a packet header and timestamp.

Parameters

packetin	A pointer to the input packet structure
pktflag	The packet flag
sequence	The packet sequence number
msglen	The length of the message array

Returns: : Returns the function error state

◆ satp_packet_set_utc_time()

SATP_EXPORT_API void satp_packet_set_utc_time ( satp_network_packet * packet )

Set the local UTC seconds time in a SATP packet header. This function updates the SATP packet header with the current UTC time (in seconds).

Parameters

packet A pointer to the SATP network packet structure.

◆ satp_packet_time_valid()

SATP_EXPORT_API bool satp_packet_time_valid ( const satp_network_packet * packet )

Check if a SATP packet is received within the valid time threshold. This function compares the UTC time in the SATP packet header against the local time to verify that the packet was received within the allowed time threshold.

Parameters

packet A pointer to the SATP network packet structure.

Returns: Returns true if the packet was received within the valid time threshold; otherwise, returns false.

◆ satp_packet_to_stream()

SATP_EXPORT_API size_t satp_packet_to_stream	(	const satp_network_packet *	packet,
		uint8_t *	pstream )

Serialize a SATP packet into a byte array. This function converts a SATP network packet into a contiguous byte stream suitable for network transmission.

Parameters

packet	A pointer to the SATP network packet structure.
pstream	The output byte stream buffer.

Returns: Returns the size (in bytes) of the serialized packet.

◆ satp_send_network_error()

SATP_EXPORT_API void satp_send_network_error	(	const qsc_socket *	sock,
		satp_errors	error )

Send a plaintext SATP network error message Used only during key exchange, the connection close is sent over an encrypted tunnel.

Parameters

sock	A pointer to the SATP network packet structure.
error	The output byte stream buffer.

◆ satp_serialize_device_key()

SATP_EXPORT_API void satp_serialize_device_key	(	uint8_t *	output,
		const satp_device_key *	dkey )

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

Parameters

output	The output byte array to hold the serialized device key.
dkey	The input SATP device key structure.

◆ satp_serialize_master_key()

SATP_EXPORT_API void satp_serialize_master_key	(	uint8_t *	output,
		const satp_master_key *	mkey )

Serialize a master key into a byte array. This function serializes a SATP master key structure into a byte array.

Parameters

output	The output byte array to hold the serialized master key.
mkey	The input SATP master key structure.

◆ satp_serialize_server_key()

SATP_EXPORT_API void satp_serialize_server_key	(	uint8_t *	output,
		const satp_server_key *	skey )

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

Parameters

output	The output byte array to hold the serialized server key.
skey	The input SATP server key structure.

◆ satp_stream_to_packet()

SATP_EXPORT_API void satp_stream_to_packet	(	const uint8_t *	pstream,
		satp_network_packet *	packet )

Deserialize a byte stream into a SATP network packet. This function converts a contiguous byte stream into a structured SATP network packet.

Parameters

pstream	A pointer to the input byte stream.
packet	A pointer to the SATP network packet structure to populate.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SATP_PACKET_TIME_THRESHOLD

Enumeration Type Documentation

◆ satp_errors

◆ satp_flags

Function Documentation

◆ satp_connection_close()

◆ satp_connection_dispose()

◆ satp_decrypt_error_message()

◆ satp_decrypt_packet()

◆ satp_deserialize_device_key()

◆ satp_deserialize_master_key()

◆ satp_deserialize_server_key()

◆ satp_encrypt_packet()

◆ satp_error_to_string()

◆ satp_extract_device_key()

◆ satp_generate_device_key()

◆ satp_generate_master_key()

◆ satp_generate_server_key()

◆ satp_increment_device_key()

◆ satp_packet_clear()

◆ satp_packet_error_message()

◆ satp_packet_header_create()

◆ satp_packet_header_deserialize()

◆ satp_packet_header_serialize()

◆ satp_packet_header_validate()

◆ satp_packet_set_utc_time()

◆ satp_packet_time_valid()

◆ satp_packet_to_stream()

◆ satp_send_network_error()

◆ satp_serialize_device_key()

◆ satp_serialize_master_key()

◆ satp_serialize_server_key()

◆ satp_stream_to_packet()