skdpclient.h File Reference

The SKDP client. More...

#include "common.h"
#include "skdp.h"
#include "../../QSC/QSC/rcs.h"
#include "../../QSC/QSC/socketclient.h"

Go to the source code of this file.

Data Structures
struct	skdp_client_state
	The SKDP client state structure. More...

Typedefs
typedef SKDP_EXPORT_API struct skdp_client_state	skdp_client_state

Functions
SKDP_EXPORT_API void	skdp_client_send_error (const qsc_socket *sock, skdp_errors error)
	Send an error code to the remote host.
SKDP_EXPORT_API void	skdp_client_initialize (skdp_client_state *ctx, const skdp_device_key *ckey)
	Initialize the SKDP client state.
SKDP_EXPORT_API skdp_errors	skdp_client_connect_ipv4 (skdp_client_state *ctx, qsc_socket *sock, const qsc_ipinfo_ipv4_address *address, uint16_t port)
	Establish an IPv4 connection and perform the SKDP key exchange.
SKDP_EXPORT_API skdp_errors	skdp_client_connect_ipv6 (skdp_client_state *ctx, qsc_socket *sock, const qsc_ipinfo_ipv6_address *address, uint16_t port)
	Establish an IPv6 connection and perform the SKDP key exchange.
SKDP_EXPORT_API void	skdp_client_connection_close (skdp_client_state *ctx, qsc_socket *sock, skdp_errors error)
	Close the remote session and dispose of client resources.
SKDP_EXPORT_API skdp_errors	skdp_client_decrypt_packet (skdp_client_state *ctx, const skdp_network_packet *packetin, uint8_t *message, size_t *msglen)
	Decrypt an SKDP packet.
SKDP_EXPORT_API skdp_errors	skdp_client_encrypt_packet (skdp_client_state *ctx, const uint8_t *message, size_t msglen, skdp_network_packet *packetout)
	Encrypt a message into an SKDP packet.
SKDP_EXPORT_API skdp_errors	skdp_client_ratchet_request (skdp_client_state *ctx, skdp_network_packet *packetout)
	Send a ratchet request to the server.

Detailed Description

The SKDP client.

This header defines the client-side functions and state structures for the Symmetric Key Distribution Protocol (SKDP). The SKDP client is responsible for initiating secure key exchange sessions with an SKDP 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 SKDP 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

skdp_client_connect_ipv4()

SKDP_EXPORT_API skdp_errors skdp_client_connect_ipv4	(	skdp_client_state *	ctx,
		qsc_socket *	sock,
		const qsc_ipinfo_ipv4_address *	address,
		uint16_t	port )

Establish an IPv4 connection and perform the SKDP key exchange.

This function connects to an SKDP 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

ctx	A pointer to the SKDP client state structure.
sock	A pointer to the socket structure which will be connected.
address	A pointer to the server's IPv4 network address.
port	The server's port number.

Returns

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

skdp_client_connect_ipv6()

SKDP_EXPORT_API skdp_errors skdp_client_connect_ipv6	(	skdp_client_state *	ctx,
		qsc_socket *	sock,
		const qsc_ipinfo_ipv6_address *	address,
		uint16_t	port )

Establish an IPv6 connection and perform the SKDP key exchange.

This function connects to an SKDP server over IPv6 and executes the key exchange protocol. It updates the client state with the negotiated session parameters and returns the connected socket through the provided pointer.

Parameters

ctx	A pointer to the SKDP client state structure.
sock	A pointer to the socket structure which will be connected.
address	A pointer to the server's IPv6 network address.
port	The server's port number.

Returns

Returns a value of type skdp_errors representing the outcome of the connection and key exchange.

skdp_client_connection_close()

SKDP_EXPORT_API void skdp_client_connection_close	(	skdp_client_state *	ctx,
		qsc_socket *	sock,
		skdp_errors	error )

Close the remote session and dispose of client resources.

This function closes the SKDP 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

ctx	A pointer to the SKDP client state structure.
sock	A pointer to the initialized socket structure.
error	The SKDP error code indicating the reason for closing the session.

skdp_client_decrypt_packet()

SKDP_EXPORT_API skdp_errors skdp_client_decrypt_packet	(	skdp_client_state *	ctx,
		const skdp_network_packet *	packetin,
		uint8_t *	message,
		size_t *	msglen )

Decrypt an SKDP packet.

This function decrypts the message contained in the input SKDP 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

ctx	A pointer to the SKDP client state structure.
packetin	[const] A pointer to the input SKDP 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 skdp_errors indicating the result of the decryption operation.

skdp_client_encrypt_packet()

SKDP_EXPORT_API skdp_errors skdp_client_encrypt_packet	(	skdp_client_state *	ctx,
		const uint8_t *	message,
		size_t	msglen,
		skdp_network_packet *	packetout )

Encrypt a message into an SKDP packet.

This function encrypts the provided plaintext message using the client's current transmit cipher state. It then constructs an SKDP 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

ctx	A pointer to the SKDP 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 SKDP network packet structure.

Returns

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

skdp_client_initialize()

SKDP_EXPORT_API void skdp_client_initialize	(	skdp_client_state *	ctx,
		const skdp_device_key *	ckey )

Initialize the SKDP client state.

This function initializes the SKDP client state structure by configuring the cipher states and copying the client's device key information. The device key, which includes the device derivation key and identity, is used to derive the session keys for encryption and decryption.

Parameters

ctx	A pointer to the SKDP client state structure to be initialized.
ckey	A pointer to the SKDP device key structure containing the client's key information.

skdp_client_ratchet_request()

SKDP_EXPORT_API skdp_errors skdp_client_ratchet_request	(	skdp_client_state *	ctx,
		skdp_network_packet *	packetout )

Send a ratchet request to the server.

In SKDP, a ratchet request is used to ask the server for a new token key on demand. This mechanism is useful in static tunnel configurations to periodically inject additional entropy into the system based on uptime or data transferred. The function constructs a ratchet request packet using the current client state and sends it to the server.

Parameters

ctx	A pointer to the SKDP client state structure.
packetout	A pointer to the output SKDP network packet structure that will contain the ratchet request.

Returns

Returns a value of type skdp_errors indicating the outcome of the ratchet request operation.

skdp_client_send_error()

SKDP_EXPORT_API void skdp_client_send_error	(	const qsc_socket *	sock,
		skdp_errors	error )

Send an error code to the remote host.

This function transmits an SKDP 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 SKDP error code to be sent.