client.h File Reference

The SATP client. More...

#include "satpcommon.h"
#include "satp.h"
#include "socketclient.h"

Go to the source code of this file.

Functions
SATP_EXPORT_API void	satp_client_send_error (const qsc_socket *sock, satp_errors error)
	Send an error code to the remote host.
SATP_EXPORT_API satp_errors	satp_client_connect_ipv4 (satp_device_key *ckey, const qsc_ipinfo_ipv4_address *address, uint16_t port, void(*send_func)(satp_connection_state *), void(*receive_callback)(satp_connection_state *, const uint8_t *, size_t))
	Establish an IPv4 connection and perform the SATP key exchange.
SATP_EXPORT_API satp_errors	satp_client_connect_ipv6 (satp_device_key *ckey, const qsc_ipinfo_ipv6_address *address, uint16_t port, void(*send_func)(satp_connection_state *), void(*receive_callback)(satp_connection_state *, const uint8_t *, size_t))
	Establish an IPv6 connection and perform the SATP key exchange.
SATP_EXPORT_API void	satp_client_connection_close (satp_connection_state *cns, satp_errors error)
	Close the remote session and dispose of client resources.

Detailed Description

The SATP client.

This header defines the client-side functions and state structures for the Symmetric Key Distribution Protocol (SATP). The SATP client is responsible for initiating secure key exchange sessions with an SATP server, managing encryption and decryption of messages, and handling key ratcheting to provide forward secrecy. It supports network connections over both IPv4 and IPv6.

The key exchange process in SATP involves several stages, including connection, exchange, establish, and ratchet operations. In each phase, ephemeral keys are derived from pre-shared keys so that even if a device's embedded key is compromised, past communications remain secure.

Note

All functions and structures defined in this header are part of the internal client implementation.

Function Documentation

satp_client_connect_ipv4()

SATP_EXPORT_API satp_errors satp_client_connect_ipv4	(	satp_device_key *	ckey,
		const qsc_ipinfo_ipv4_address *	address,
		uint16_t	port,
		void(*	send_func )(satp_connection_state *),
		void(*	receive_callback )(satp_connection_state *, const uint8_t *, size_t) )

Establish an IPv4 connection and perform the SATP key exchange.

This function connects to an SATP server over IPv4 and performs the key exchange protocol. It updates the client state with session parameters including cipher states and sequence numbers, and returns the connected socket via the provided socket pointer.

Parameters

ckey	A pointer to the key state structure.
address	A pointer to the server's IPv4 network address.
port	The server's port number.
send_func	A pointer to the send callback function responsible for transmitting messages.
receive_callback	A pointer to the receive callback function used to process incoming data.

Returns

Returns a value of type satp_errors indicating the success or failure of the connection and key exchange process.

satp_client_connect_ipv6()

SATP_EXPORT_API satp_errors satp_client_connect_ipv6	(	satp_device_key *	ckey,
		const qsc_ipinfo_ipv6_address *	address,
		uint16_t	port,
		void(*	send_func )(satp_connection_state *),
		void(*	receive_callback )(satp_connection_state *, const uint8_t *, size_t) )

Establish an IPv6 connection and perform the SATP key exchange.

This function connects to an SATP server over IPv4 and performs the key exchange protocol. It updates the client state with session parameters including cipher states and sequence numbers, and returns the connected socket via the provided socket pointer.

Parameters

ckey	A pointer to the key state structure.
address	A pointer to the server's IPv6 network address.
port	The server's port number.
send_func	A pointer to the send callback function responsible for transmitting messages.
receive_callback	A pointer to the receive callback function used to process incoming data.

Returns

Returns a value of type satp_errors indicating the success or failure of the connection and key exchange process.

satp_client_connection_close()

SATP_EXPORT_API void satp_client_connection_close	(	satp_connection_state *	cns,
		satp_errors	error )

Close the remote session and dispose of client resources.

This function closes the SATP client session by sending an error notification (if necessary) to the remote host, and then disposing of the client state and releasing the associated socket resources.

Parameters

cns	A pointer to the connection state structure.
error	The SATP error code indicating the reason for closing the session.

satp_client_send_error()

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

Send an error code to the remote host.

This function transmits an SATP error code over the specified socket, thereby informing the remote host of an error condition encountered during communication.

Parameters

sock	A pointer to the initialized socket structure.
error	The SATP error code to be sent.