DKTP Client Functions. More...

#include "dktp.h"
#include "rcs.h"
#include "socketclient.h"

Functions
DKTP_EXPORT_API bool	dktp_send_asymmetric_ratchet_request (dktp_connection_state *cns)
	Send an asymmetric key-ratchet request to the remote host.
DKTP_EXPORT_API dktp_errors	dktp_client_connect_ipv4 (dktp_local_peer_key lpk, dktp_remote_peer_key rpk, const qsc_ipinfo_ipv4_address address, uint16_t port, void(send_func)(dktp_connection_state ), void(receive_callback)(dktp_connection_state , const uint8_t , size_t))
	Connect to a remote host over IPv4 and perform the key exchange.
DKTP_EXPORT_API dktp_errors	dktp_client_connect_ipv6 (dktp_local_peer_key lpk, dktp_remote_peer_key rpk, const qsc_ipinfo_ipv6_address address, uint16_t port, void(send_func)(dktp_connection_state ), void(receive_callback)(dktp_connection_state , const uint8_t , size_t))
	Connect to a remote host over IPv6 and perform the key exchange.
DKTP_EXPORT_API dktp_errors	dktp_client_listen_ipv4 (dktp_local_peer_key lpk, dktp_remote_peer_key rpk, void(send_func)(dktp_connection_state ), void(receive_callback)(dktp_connection_state , const uint8_t *, size_t))
	Start the server over IPv4 and listen for a single host-to-host connection.
DKTP_EXPORT_API dktp_errors	dktp_client_listen_ipv6 (dktp_local_peer_key lpk, dktp_remote_peer_key rpk, void(send_func)(dktp_connection_state ), void(receive_callback)(dktp_connection_state , const uint8_t *, size_t))
	Start the server over IPv6 and listen for a single host-to-host connection.

Detailed Description

DKTP Client Functions.

This header file defines the client-side functions for the Dual Key Tunneling Protocol (DKTP). DKTP is a post-quantum secure messaging protocol that supports a Duplex key exchange mechanism over IPv4 and IPv6 networks. These functions enable DKTP clients to initiate secure connections, perform key exchanges, and manage cryptographic ratchet operations during an active session.

The DKTP client functionality provided in this header includes:

Key Ratchet Requests:
- Asymmetric Key Ratchet Request: (conditionally available when DKTP_ASYMMETRIC_RATCHET is defined) Initiates an asymmetric key ratchet to update session keys using asymmetric cryptographic operations, thereby enhancing forward secrecy.
Duplex Key Exchange Connections:
- Establishes secure, bi-directional (mutually authenticated) communication channels using the DKTP protocol.
- Supports connection establishment over both IPv4 and IPv6.
Listener Functions:
- Functions that start a network listener (acting as a server) to accept incoming connections and perform either the DKTP key exchange.

All connection functions accept callback functions for sending and receiving data over the DKTP connection, and they return a value of type 'dktp_errors' to indicate the success or failure of the operation.

Note: This header file does not include any internal test functions.

Function Documentation

◆ dktp_client_connect_ipv4()

DKTP_EXPORT_API dktp_errors dktp_client_connect_ipv4	(	dktp_local_peer_key *	lpk,
		dktp_remote_peer_key *	rpk,
		const qsc_ipinfo_ipv4_address *	address,
		uint16_t	port,
		void(*	send_func )(dktp_connection_state *),
		void(*	receive_callback )(dktp_connection_state , const uint8_t , size_t) )

Connect to a remote host over IPv4 and perform the key exchange.

This function establishes a connection to a remote host using its IPv4 address and initiates the Duplex key exchange protocol. The Duplex protocol enables mutual authentication and a bidirectional key exchange, setting up a secure two-way communication channel. Upon successful connection, the provided callback functions handle message transmission and reception.

Parameters

lpk	A pointer to the local peer key.
rpk	A pointer to the remote peer key.
address	[const] A pointer to the IPv4 address information structure of the remote server.
port	The DKTP application port number (typically defined by DKTP_CLIENT_PORT).
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 dktp_errors indicating the success or failure of the connection and key exchange.

◆ dktp_client_connect_ipv6()

DKTP_EXPORT_API dktp_errors dktp_client_connect_ipv6	(	dktp_local_peer_key *	lpk,
		dktp_remote_peer_key *	rpk,
		const qsc_ipinfo_ipv6_address *	address,
		uint16_t	port,
		void(*	send_func )(dktp_connection_state *),
		void(*	receive_callback )(dktp_connection_state , const uint8_t , size_t) )

Connect to a remote host over IPv6 and perform the key exchange.

This function establishes a connection to a remote host using its IPv6 address and initiates the key exchange protocol. The DKTP protocol provides mutual authentication and secure bidirectional communication. Upon connection, the designated callback functions are invoked to manage the data transmission and reception.

Parameters

lpk	A pointer to the local peer key.
rpk	A pointer to the remote peer key.
address	[const] A pointer to the IPv6 address information structure of the remote server.
port	The DKTP application port number (typically defined by DKTP_CLIENT_PORT).
send_func	A pointer to the send callback function responsible for message transmission.
receive_callback	A pointer to the receive callback function used to process incoming data.

Returns: Returns a value of type dktp_errors indicating the result of the connection and key exchange operation.

◆ dktp_client_listen_ipv4()

DKTP_EXPORT_API dktp_errors dktp_client_listen_ipv4	(	dktp_local_peer_key *	lpk,
		dktp_remote_peer_key *	rpk,
		void(*	send_func )(dktp_connection_state *),
		void(*	receive_callback )(dktp_connection_state , const uint8_t , size_t) )

Start the server over IPv4 and listen for a single host-to-host connection.

This function initiates a network listener on the IPv4 interface to accept an incoming connection for the DKTP key exchange. The DKTP protocol facilitates mutual authentication and a bidirectional key exchange, thereby establishing a secure communication channel. An additional key query callback is provided to identify and retrieve the correct public key based on a received key identifier.

Parameters

lpk	A pointer to the DKTP local peer key.
rpk	A pointer to the DKTP remote peer key.
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 client data.

Returns: Returns a value of type dktp_errors representing the outcome of the listener initialization and key exchange.

◆ dktp_client_listen_ipv6()

DKTP_EXPORT_API dktp_errors dktp_client_listen_ipv6	(	dktp_local_peer_key *	lpk,
		dktp_remote_peer_key *	rpk,
		void(*	send_func )(dktp_connection_state *),
		void(*	receive_callback )(dktp_connection_state , const uint8_t , size_t) )

Start the server over IPv6 and listen for a single host-to-host connection.

This function sets up a network listener on the IPv6 interface to accept an incoming connection for the DKTP key exchange protocol. The DKTP protocol enables secure bidirectional communication through mutual authentication and key exchange. A key query callback is provided to determine and return the correct public key based on a given key identifier during the connection process.

Parameters

lpk	A pointer to the DKTP server signature key used for signing messages.
rpk	A pointer to the DKTP remote peer key.
send_func	A pointer to the send callback function that handles outgoing message transmission.
receive_callback	A pointer to the receive callback function used to process incoming data from the connected host.

Returns: Returns a value of type dktp_errors indicating the status of the listener setup and key exchange operation.

◆ dktp_send_asymmetric_ratchet_request()

DKTP_EXPORT_API bool dktp_send_asymmetric_ratchet_request ( dktp_connection_state * cns )

Send an asymmetric key-ratchet request to the remote host.

This function sends a request to initiate an asymmetric key ratchet in an active DKTP session. The asymmetric ratchet mechanism employs asymmetric cryptographic operations to update the session keys, thereby providing enhanced forward secrecy. This function is only available when the DKTP_ASYMMETRIC_RATCHET macro is defined.

Parameters

cns	A pointer to the current DKTP connection state structure.

Returns: Returns true if the ratchet request was successfully sent to the remote host, otherwise false.