pqs.h File Reference

PQS support header. More...

#include "common.h"
#include "../../QSC/QSC/dilithium.h"
#include "../../QSC/QSC/kyber.h"
#include "../../QSC/QSC/rcs.h"
#include "../../QSC/QSC/sha3.h"
#include "../../QSC/QSC/socketbase.h"

Go to the source code of this file.

Data Structures
struct	pqs_asymmetric_cipher_keypair
	Container for an asymmetric cipher key pair. More...
struct	pqs_asymmetric_signature_keypair
	Container for an asymmetric signature key pair. More...
struct	pqs_network_packet
	Represents a network packet in the PQS protocol. More...
struct	pqs_client_verification_key
	Structure holding a PQS client public key. More...
struct	pqs_server_signature_key
	Structure holding a PQS server secret signature key. More...
struct	pqs_keep_alive_state
	Maintains the state for a keep-alive mechanism. More...
struct	pqs_connection_state
	Maintains the state for a PQS socket connection. More...

Macros
#define	PQS_CONFIG_SIZE   48
	The size in bytes of the protocol configuration string.
#define	PQS_ASYMMETRIC_CIPHER_TEXT_SIZE   (QSC_KYBER_CIPHERTEXT_SIZE)
	The size in bytes of the asymmetric cipher-text array.
#define	PQS_ASYMMETRIC_PRIVATE_KEY_SIZE   (QSC_KYBER_PRIVATEKEY_SIZE)
	The size in bytes of the asymmetric cipher private-key array.
#define	PQS_ASYMMETRIC_PUBLIC_KEY_SIZE   (QSC_KYBER_PUBLICKEY_SIZE)
	The size in bytes of the asymmetric cipher public-key array.
#define	PQS_ASYMMETRIC_SIGNING_KEY_SIZE   (QSC_DILITHIUM_PRIVATEKEY_SIZE)
	The size in bytes of the asymmetric signature signing-key array.
#define	PQS_ASYMMETRIC_VERIFY_KEY_SIZE   (QSC_DILITHIUM_PUBLICKEY_SIZE)
	The size in bytes of the asymmetric signature verification-key array.
#define	PQS_ASYMMETRIC_SIGNATURE_SIZE   (QSC_DILITHIUM_SIGNATURE_SIZE)
	The size in bytes of the asymmetric signature array.
#define	PQS_PUBKEY_ENCODING_SIZE   3456
	The size in bytes of the encoded PQS public-key.
#define	PQS_PUBKEY_STRING_SIZE   3745
	The size in bytes of the serialized PQS client-key structure.
#define	PQS_CLIENT_PORT   33118
	The default port number for PQS client connections.
#define	PQS_CONNECTIONS_INIT   1000
	The initial size of the PQS connection queue.
#define	PQS_CONNECTIONS_MAX   50000
	The maximum number of concurrent PQS connections.
#define	PQS_CONNECTION_MTU   1500
	The maximum transmission unit (MTU) size for a PQS packet.
#define	PQS_ERROR_SEQUENCE   0xFF00000000000000ULL
	The sequence number used to indicate an error in a packet.
#define	PQS_ERROR_MESSAGE_SIZE   1
	The size in bytes of the error message contained in a packet.
#define	PQS_FLAG_SIZE   1
	The size in bytes of the packet flag.
#define	PQS_HASH_SIZE   32
	The output size in bytes of the Simplex 256-bit hash function.
#define	PQS_HEADER_SIZE   21
	The size in bytes of a PQS packet header.
#define	PQS_KEEPALIVE_TIMEOUT   (120 * 1000)
	The timeout period (in milliseconds) for keep-alive messages.
#define	PQS_KEYID_SIZE   16
	The size in bytes of a PQS key identity.
#define	PQS_MACTAG_SIZE   32
	The size in bytes of the MAC tag for the Simplex 256-bit MAC.
#define	PQS_MESSAGE_MAX   0x3D090000
	The maximum allowed message size (in bytes) during the key exchange.
#define	PQS_MSGLEN_SIZE   4
	The size in bytes of the packet message length field.
#define	PQS_NONCE_SIZE   32
	The size in bytes of the nonce used in symmetric encryption.
#define	PQS_NETWORK_BUFFER_SIZE   1280
	The size in bytes of the network buffer.
#define	PQS_PACKET_TIME_THRESHOLD   60
	The maximum time (in seconds) a packet is considered valid.
#define	PQS_PUBKEY_DURATION_DAYS   365
	The validity duration (in days) of a public key.
#define	PQS_PUBKEY_DURATION_SECONDS   (PQS_PUBKEY_DURATION_DAYS * 24 * 60 * 60)
	The validity duration (in seconds) of a public key.
#define	PQS_PUBKEY_LINE_LENGTH   64
	The maximum number of characters per line in a printed PQS public key.
#define	PQS_SCHASH_SIZE   32
	The size in bytes of the Simplex 256-bit session token hash.
#define	PQS_SECRET_SIZE   32
	The size in bytes of the shared secret for each communication channel.
#define	PQS_SEQUENCE_SIZE   8
	The size in bytes of the packet sequence number.
#define	PQS_SEQUENCE_TERMINATOR   0xFFFFFFFFUL
	The sequence number that indicates a packet which closes a connection.
#define	PQS_SERVER_LISTEN_BACKLOG   0
	The backlog size for the server listen socket.
#define	PQS_SERVER_PORT   3119
	The default port number for PQS server connections.
#define	PQS_SYMMETRIC_KEY_SIZE   32
	The size in bytes of the Simplex 256-bit symmetric cipher key.
#define	PQS_TIMESTAMP_SIZE   8
	The size in bytes of the key expiration timestamp.
#define	PQS_SIGKEY_ENCODED_SIZE
	The size in bytes of the encoded secret signature key structure.
#define	pqs_cipher_generate_keypair   qsc_kyber_generate_keypair
	Generate an asymmetric cipher key-pair.
#define	pqs_cipher_decapsulate   qsc_kyber_decapsulate
	Decapsulate a shared-secret with the asymmetric cipher.
#define	pqs_cipher_encapsulate   qsc_kyber_encapsulate
	Encapsulate a shared-secret with the asymmetric cipher.
#define	pqs_signature_generate_keypair   qsc_dilithium_generate_keypair
	Generate an asymmetric signature key-pair.
#define	pqs_signature_sign   qsc_dilithium_sign
	Sign a message with the asymmetric signature scheme.
#define	pqs_signature_verify   qsc_dilithium_verify
	Verify a message with the asymmetric signature scheme.

Typedefs
typedef PQS_EXPORT_API enum pqs_client_commands	pqs_client_commands
typedef PQS_EXPORT_API enum pqs_errors	pqs_errors
typedef PQS_EXPORT_API enum pqs_flags	pqs_flags
typedef PQS_EXPORT_API enum pqs_messages	pqs_messages
typedef PQS_EXPORT_API struct pqs_asymmetric_cipher_keypair	pqs_asymmetric_cipher_keypair
typedef PQS_EXPORT_API struct pqs_asymmetric_signature_keypair	pqs_asymmetric_signature_keypair
typedef PQS_EXPORT_API struct pqs_network_packet	pqs_network_packet
typedef PQS_EXPORT_API struct pqs_client_verification_key	pqs_client_verification_key
typedef PQS_EXPORT_API struct pqs_server_signature_key	pqs_server_signature_key
typedef PQS_EXPORT_API struct pqs_keep_alive_state	pqs_keep_alive_state
typedef PQS_EXPORT_API struct pqs_connection_state	pqs_connection_state

Enumerations
enum	pqs_client_commands { pqs_client_command_none = 0x00 , pqs_client_command_cprint = 0x01 , pqs_client_command_execute = 0x02 , pqs_client_command_quit = 0x03 }
	Enumeration of client commands in the PQS protocol. More...
enum	pqs_errors {   pqs_error_none = 0x00 , pqs_error_accept_fail = 0x01 , pqs_error_authentication_failure = 0x02 , pqs_error_bad_keep_alive = 0x03 ,   pqs_error_channel_down = 0x04 , pqs_error_connection_failure = 0x05 , pqs_error_connect_failure = 0x06 , pqs_error_decapsulation_failure = 0x07 ,   pqs_error_decryption_failure = 0x08 , pqs_error_establish_failure = 0x09 , pqs_error_exchange_failure = 0x0A , pqs_error_hash_invalid = 0x0B ,   pqs_error_hosts_exceeded = 0x0C , pqs_error_invalid_input = 0x0D , pqs_error_invalid_request = 0x0E , pqs_error_keepalive_expired = 0x0F ,   pqs_error_keepalive_timeout = 0x10 , pqs_error_key_expired = 0x11 , pqs_error_key_unrecognized = 0x12 , pqs_error_keychain_fail = 0x13 ,   pqs_error_listener_fail = 0x14 , pqs_error_memory_allocation = 0x15 , pqs_error_packet_unsequenced = 0x16 , pqs_error_random_failure = 0x17 ,   pqs_error_receive_failure = 0x18 , pqs_error_transmit_failure = 0x19 , pqs_error_unknown_protocol = 0x1A , pqs_error_verify_failure = 0x1B ,   pqs_error_login_failure = 0x1C , pqs_error_login_success = 0x1D , pqs_error_message_time_invalid = 0x1E , pqs_error_connection_refused = 0x1F }
	Enumeration of error codes returned by PQS functions. More...
enum	pqs_flags {   pqs_flag_none = 0x00 , pqs_flag_connect_request = 0x01 , pqs_flag_connect_response = 0x02 , pqs_flag_connection_terminate = 0x03 ,   pqs_flag_encrypted_message = 0x04 , pqs_flag_exstart_request = 0x05 , pqs_flag_exstart_response = 0x06 , pqs_flag_exchange_request = 0x07 ,   pqs_flag_exchange_response = 0x08 , pqs_flag_establish_request = 0x09 , pqs_flag_establish_response = 0x0A , pqs_flag_keep_alive_request = 0x0B ,   pqs_flag_keep_alive_response = 0x0C , pqs_flag_remote_connected = 0x0E , pqs_flag_remote_terminated = 0x0F , pqs_flag_session_established = 0x10 ,   pqs_flag_session_establish_verify = 0x11 , pqs_flag_unrecognized_protocol = 0x12 , pqs_flag_asymmetric_ratchet_request = 0x13 , pqs_flag_asymmetric_ratchet_response = 0x14 ,   pqs_flag_symmetric_ratchet_request = 0x15 , pqs_flag_transfer_request = 0x16 , pqs_flag_error_condition = 0xFF }
	Enumeration of packet flags used in the PQS protocol. More...
enum	pqs_messages {   pqs_messages_none = 0x00 , pqs_messages_accept_fail = 0x01 , pqs_messages_listen_fail = 0x02 , pqs_messages_bind_fail = 0x03 ,   pqs_messages_create_fail = 0x04 , pqs_messages_connect_success = 0x05 , pqs_messages_receive_fail = 0x06 , pqs_messages_allocate_fail = 0x07 ,   pqs_messages_kex_fail = 0x08 , pqs_messages_disconnect = 0x09 , pqs_messages_disconnect_fail = 0x0A , pqs_messages_socket_message = 0x0B ,   pqs_messages_queue_empty = 0x0C , pqs_messages_listener_fail = 0x0D , pqs_messages_sockalloc_fail = 0x0E , pqs_messages_decryption_fail = 0x0F ,   pqs_messages_keepalive_fail = 0x10 , pqs_messages_keepalive_timeout = 0x11 , pqs_messages_connection_fail = 0x12 , pqs_messages_invalid_request = 0x13 ,   pqs_messages_connection_refused = 0x14 }
	Enumeration of logging and status messages used by PQS. More...

Functions
PQS_EXPORT_API void	pqs_connection_close (pqs_connection_state *cns, pqs_errors err, bool notify)
	Closes the network connection between hosts.
PQS_EXPORT_API void	pqs_connection_state_dispose (pqs_connection_state *cns)
	Resets and disposes of the connection state.
PQS_EXPORT_API const char *	pqs_error_description (pqs_messages emsg)
	Retrieves the description string for a given message enumeration.
PQS_EXPORT_API const char *	pqs_error_to_string (pqs_errors error)
	Converts an error code to its corresponding string description.
PQS_EXPORT_API void	pqs_generate_keypair (pqs_client_verification_key *pubkey, pqs_server_signature_key *prikey, const uint8_t keyid[PQS_KEYID_SIZE])
	Generates a PQS key pair.
PQS_EXPORT_API void	pqs_log_error (pqs_messages emsg, qsc_socket_exceptions err, const char *msg)
	Logs an error message along with socket error details.
PQS_EXPORT_API void	pqs_log_message (pqs_messages emsg)
	Logs a message based on the provided message enumeration.
PQS_EXPORT_API void	pqs_log_write (pqs_messages emsg, const char *msg)
	Logs a message with an accompanying description.
PQS_EXPORT_API void	pqs_packet_clear (pqs_network_packet *packet)
	Clears the state of a network packet.
PQS_EXPORT_API pqs_errors	pqs_packet_decrypt (pqs_connection_state *cns, uint8_t *message, size_t *msglen, const pqs_network_packet *packetin)
	Decrypts an incoming packet's payload.
PQS_EXPORT_API pqs_errors	pqs_packet_encrypt (pqs_connection_state *cns, pqs_network_packet *packetout, const uint8_t *message, size_t msglen)
	Encrypts a message and constructs an output packet.
PQS_EXPORT_API void	pqs_packet_error_message (pqs_network_packet *packet, pqs_errors error)
	Populates a packet structure with an error message.
PQS_EXPORT_API void	pqs_packet_header_create (pqs_network_packet *packetout, pqs_flags flag, uint64_t sequence, uint32_t msglen)
	Creates and populates a packet header.
PQS_EXPORT_API void	pqs_packet_header_deserialize (const uint8_t *header, pqs_network_packet *packet)
	Deserializes a byte array into a packet header.
PQS_EXPORT_API void	pqs_packet_header_serialize (const pqs_network_packet *packet, uint8_t *header)
	Serializes a packet header into a byte array.
PQS_EXPORT_API pqs_errors	pqs_header_validate (pqs_connection_state *cns, const pqs_network_packet *packetin, pqs_flags kexflag, pqs_flags pktflag, uint64_t sequence, uint32_t msglen)
	Validates a packet header and its associated timestamp.
PQS_EXPORT_API void	pqs_packet_time_set (pqs_network_packet *packet)
	Sets the packet's UTC timestamp to the current time.
PQS_EXPORT_API bool	pqs_packet_time_validate (const pqs_network_packet *packet)
	Validates the timestamp of a packet against the local UTC time.
PQS_EXPORT_API size_t	pqs_packet_to_stream (const pqs_network_packet *packet, uint8_t *pstream)
	Serializes a full packet (header and payload) into a byte stream.
PQS_EXPORT_API bool	pqs_public_key_decode (pqs_client_verification_key *pubk, const char enck[PQS_PUBKEY_STRING_SIZE])
	Decodes an encoded public key string into a client verification key structure.
PQS_EXPORT_API void	pqs_public_key_encode (char enck[PQS_PUBKEY_STRING_SIZE], const pqs_client_verification_key *pubkey)
	Encodes a client public key structure into a printable string.
PQS_EXPORT_API void	pqs_public_key_hash (uint8_t *hash, const pqs_client_verification_key *pubk)
	Computes a hash of a public key structure.
PQS_EXPORT_API void	pqs_signature_key_deserialize (pqs_server_signature_key *kset, const uint8_t serk[PQS_SIGKEY_ENCODED_SIZE])
	Deserializes an encoded secret signature key into a server signature key structure.
PQS_EXPORT_API void	pqs_signature_key_serialize (uint8_t serk[PQS_SIGKEY_ENCODED_SIZE], const pqs_server_signature_key *kset)
	Serializes a server secret signature key structure into an encoded array.
PQS_EXPORT_API void	pqs_stream_to_packet (const uint8_t *pstream, pqs_network_packet *packet)
	Deserializes a byte stream into a network packet structure.

Detailed Description

PQS support header.

This header defines the common parameters, macros, data structures, enumerations, and function prototypes used by both the PQS client and server implementations. PQS (Post Quantum Shell) implements a one-way trust, client-server key-exchange model designed for efficiency and 256-bit post-quantum security. The underlying cryptographic primitives are provided by the QSC library, using combinations of the Dilithium (for signatures) and Kyber (for key encapsulation) schemes.

The protocol configuration is determined at compile-time by preprocessor definitions (such as QSC_DILITHIUM_S1P2544, QSC_KYBER_S1P1632, etc.) defined in the QSC library's common.h file. Although library defaults are used by default, the parameter sets may be changed to suit different security or performance requirements.

The file also defines the structures for network packets, connection state, and key containers, along with function prototypes for operations such as connection management, encryption/decryption, logging, public key encoding/decoding, and key generation.

Note

This header does not include any test functions. The test routines (if implemented elsewhere) validate operations such as key generation, packet encryption/decryption, and error handling.

Project Description:

The PQS exchange is a one-way trust, client-server key-exchange model in which the client trusts the server, and a single shared secret is securely shared between them. Designed for efficiency, the Simplex exchange is fast and lightweight, while providing 256-bit post-quantum security, ensuring protection against future quantum-based threats. This protocol is versatile and applicable to a wide range of secure communications and key distribution scenarios.

Macro Definition Documentation

PQS_ASYMMETRIC_CIPHER_TEXT_SIZE

#define PQS_ASYMMETRIC_CIPHER_TEXT_SIZE   (QSC_KYBER_CIPHERTEXT_SIZE)

The size in bytes of the asymmetric cipher-text array.

This macro is defined as the value of QSC_KYBER_CIPHERTEXT_SIZE, representing the output size for the Kyber key encapsulation mechanism.

PQS_ASYMMETRIC_PRIVATE_KEY_SIZE

#define PQS_ASYMMETRIC_PRIVATE_KEY_SIZE   (QSC_KYBER_PRIVATEKEY_SIZE)

The size in bytes of the asymmetric cipher private-key array.

This is defined in terms of QSC_KYBER_PRIVATEKEY_SIZE.

PQS_ASYMMETRIC_PUBLIC_KEY_SIZE

#define PQS_ASYMMETRIC_PUBLIC_KEY_SIZE   (QSC_KYBER_PUBLICKEY_SIZE)

The size in bytes of the asymmetric cipher public-key array.

This value is taken from QSC_KYBER_PUBLICKEY_SIZE.

PQS_ASYMMETRIC_SIGNATURE_SIZE

#define PQS_ASYMMETRIC_SIGNATURE_SIZE   (QSC_DILITHIUM_SIGNATURE_SIZE)

The size in bytes of the asymmetric signature array.

This value is defined as QSC_DILITHIUM_SIGNATURE_SIZE.

PQS_ASYMMETRIC_SIGNING_KEY_SIZE

#define PQS_ASYMMETRIC_SIGNING_KEY_SIZE   (QSC_DILITHIUM_PRIVATEKEY_SIZE)

The size in bytes of the asymmetric signature signing-key array.

This value corresponds to QSC_DILITHIUM_PRIVATEKEY_SIZE.

PQS_ASYMMETRIC_VERIFY_KEY_SIZE

#define PQS_ASYMMETRIC_VERIFY_KEY_SIZE   (QSC_DILITHIUM_PUBLICKEY_SIZE)

The size in bytes of the asymmetric signature verification-key array.

This value corresponds to QSC_DILITHIUM_PUBLICKEY_SIZE.

PQS_CONFIG_SIZE

#define PQS_CONFIG_SIZE   48

The size in bytes of the protocol configuration string.

This constant defines the fixed length (48 bytes) of the configuration string that specifies the selected cryptographic primitive parameter set.

PQS_CONNECTIONS_INIT

#define PQS_CONNECTIONS_INIT   1000

The initial size of the PQS connection queue.

This value is used when initializing the connection state.

PQS_CONNECTIONS_MAX

#define PQS_CONNECTIONS_MAX   50000

The maximum number of concurrent PQS connections.

This is calculated based on an approximate memory footprint per connection. For example, with a 256GB DRAM system, the maximum may be set to 50,000 connections.

PQS_KEEPALIVE_TIMEOUT

#define PQS_KEEPALIVE_TIMEOUT   (120 * 1000)

The timeout period (in milliseconds) for keep-alive messages.

The default value is 2 minutes.

PQS_MESSAGE_MAX

#define PQS_MESSAGE_MAX   0x3D090000

The maximum allowed message size (in bytes) during the key exchange.

This value is approximately 1 GB.

PQS_PACKET_TIME_THRESHOLD

#define PQS_PACKET_TIME_THRESHOLD   60

The maximum time (in seconds) a packet is considered valid.

This threshold can be tuned based on network conditions. For interior networks with synchronized clocks, it might be as low as 1 second; for exterior networks, it may be higher.

PQS_PUBKEY_DURATION_SECONDS

#define PQS_PUBKEY_DURATION_SECONDS   (PQS_PUBKEY_DURATION_DAYS * 24 * 60 * 60)

The validity duration (in seconds) of a public key.

Calculated from PQS_PUBKEY_DURATION_DAYS.

PQS_PUBKEY_ENCODING_SIZE

#define PQS_PUBKEY_ENCODING_SIZE   3456

The size in bytes of the encoded PQS public-key.

The encoding size varies depending on the selected Dilithium parameter set.

PQS_PUBKEY_STRING_SIZE

#define PQS_PUBKEY_STRING_SIZE   3745

The size in bytes of the serialized PQS client-key structure.

This defines the length of the string produced when encoding a public key.

PQS_SERVER_LISTEN_BACKLOG

#define PQS_SERVER_LISTEN_BACKLOG   0

The backlog size for the server listen socket.

Set to zero since concurrent connections are disallowed at the listen level.

PQS_SIGKEY_ENCODED_SIZE

#define PQS_SIGKEY_ENCODED_SIZE

Value:

    (PQS_KEYID_SIZE + PQS_TIMESTAMP_SIZE + PQS_CONFIG_SIZE + \
    PQS_HASH_SIZE + PQS_ASYMMETRIC_SIGNING_KEY_SIZE + PQS_ASYMMETRIC_VERIFY_KEY_SIZE)

The size in bytes of the encoded secret signature key structure.

The encoded key consists of the key identity, timestamp, configuration string, public key hash, signature key, and verification key.

Enumeration Type Documentation

pqs_client_commands

enum pqs_client_commands

Enumeration of client commands in the PQS protocol.

DOXYGEN_IGNORE

/*-------------------------------------------------------------------------—

Error code string parameters

DOXYGEN_IGNORE DOXYGEN_IGNORE

These commands are used by the client to indicate the desired operation.

Enumerator
pqs_client_command_none	No command was specified
pqs_client_command_cprint	The certificate print command
pqs_client_command_execute	The execute command
pqs_client_command_quit	The quit command

pqs_errors

enum pqs_errors

Enumeration of error codes returned by PQS functions.

These error values indicate various failure conditions encountered during connection establishment, encryption/decryption, key exchange, and other operations.

Enumerator
pqs_error_none	No error was detected
pqs_error_accept_fail	The socket accept function returned an error
pqs_error_authentication_failure	The symmetric cipher had an authentication failure
pqs_error_bad_keep_alive	The keep alive check failed
pqs_error_channel_down	The communications channel has failed
pqs_error_connection_failure	The device could not make a connection to the remote host
pqs_error_connect_failure	The transmission failed at the KEX connection phase
pqs_error_decapsulation_failure	The asymmetric cipher failed to decapsulate the shared secret
pqs_error_decryption_failure	The decryption authentication has failed
pqs_error_establish_failure	The transmission failed at the KEX establish phase
pqs_error_exchange_failure	The transmission failed at the KEX exchange phase
pqs_error_hash_invalid	The public-key hash is invalid
pqs_error_hosts_exceeded	The server has run out of socket connections
pqs_error_invalid_input	The expected input was invalid
pqs_error_invalid_request	The packet flag was unexpected
pqs_error_keepalive_expired	The keep alive has expired with no response
pqs_error_keepalive_timeout	The decryption authentication has failed
pqs_error_key_expired	The PQS public key has expired
pqs_error_key_unrecognized	The key identity is unrecognized
pqs_error_keychain_fail	The ratchet operation has failed
pqs_error_listener_fail	The listener function failed to initialize
pqs_error_memory_allocation	The server has run out of memory
pqs_error_packet_unsequenced	The packet was received out of sequence
pqs_error_random_failure	The random generator has failed
pqs_error_receive_failure	The receiver failed at the network layer
pqs_error_transmit_failure	The transmitter failed at the network layer
pqs_error_unknown_protocol	The protocol string was not recognized
pqs_error_verify_failure	The expected data could not be verified
pqs_error_login_failure	The client received an authentication failure response
pqs_error_login_success	The client received an authentication success response
pqs_error_message_time_invalid	The packet valid time has expired
pqs_error_connection_refused	The connection was refused by the remote server

pqs_flags

enum pqs_flags

Enumeration of packet flags used in the PQS protocol.

The flags indicate the type or purpose of a packet (e.g., connection requests, key exchange phases, keep alive messages, error conditions, etc.).

Enumerator
pqs_flag_none	No flag was specified
pqs_flag_connect_request	The PQS key-exchange client connection request flag
pqs_flag_connect_response	The PQS key-exchange server connection response flag
pqs_flag_connection_terminate	The connection is to be terminated
pqs_flag_encrypted_message	The message has been encrypted
pqs_flag_exstart_request	The PQS key-exchange client exstart request flag
pqs_flag_exstart_response	The PQS key-exchange server exstart response flag
pqs_flag_exchange_request	The PQS key-exchange client exchange request flag
pqs_flag_exchange_response	The PQS key-exchange server exchange response flag
pqs_flag_establish_request	The PQS key-exchange client establish request flag
pqs_flag_establish_response	The PQS key-exchange server establish response flag
pqs_flag_keep_alive_request	The packet contains a keep alive request
pqs_flag_keep_alive_response	The packet contains a keep alive response
pqs_flag_remote_connected	The remote host is connected flag
pqs_flag_remote_terminated	The remote host has terminated the connection
pqs_flag_session_established	The exchange is in the established state
pqs_flag_session_establish_verify	The exchange is in the established verify state
pqs_flag_unrecognized_protocol	The protocol string is not recognized
pqs_flag_asymmetric_ratchet_request	The host has received an asymmetric key ratchet request
pqs_flag_asymmetric_ratchet_response	The host has received an asymmetric key ratchet request
pqs_flag_symmetric_ratchet_request	The host has received a symmetric key ratchet request
pqs_flag_transfer_request	Reserved - The host has received a transfer request
pqs_flag_error_condition	The connection experienced an error

pqs_messages

enum pqs_messages

Enumeration of logging and status messages used by PQS.

These messages correspond to various events and errors occurring within the protocol, and are used for diagnostic logging.

Enumerator
pqs_messages_none	No configuration was specified
pqs_messages_accept_fail	The socket accept failed
pqs_messages_listen_fail	The listener socket could not connect
pqs_messages_bind_fail	The listener socket could not bind to the address
pqs_messages_create_fail	The listener socket could not be created
pqs_messages_connect_success	The server connected to a host
pqs_messages_receive_fail	The socket receive function failed
pqs_messages_allocate_fail	The server memory allocation request has failed
pqs_messages_kex_fail	The key exchange has experienced a failure
pqs_messages_disconnect	The server has disconnected the client
pqs_messages_disconnect_fail	The server has disconnected the client due to an error
pqs_messages_socket_message	The server has had a socket level error
pqs_messages_queue_empty	The server has reached the maximum number of connections
pqs_messages_listener_fail	The server listener socket has failed
pqs_messages_sockalloc_fail	The server has run out of socket connections
pqs_messages_decryption_fail	The message decryption has failed
pqs_messages_keepalive_fail	The keepalive function has failed
pqs_messages_keepalive_timeout	The keepalive period has been exceeded
pqs_messages_connection_fail	The connection failed or was interrupted
pqs_messages_invalid_request	The function received an invalid request
pqs_messages_connection_refused	The remote host is busy and refused the connection

Function Documentation

pqs_connection_close()

PQS_EXPORT_API void pqs_connection_close	(	pqs_connection_state *	cns,
		pqs_errors	err,
		bool	notify )

Closes the network connection between hosts.

If the connection is active, this function optionally sends a disconnect notification. In the case of a normal disconnect (no error), a simple disconnect packet is transmitted. If an error has occurred, an error packet is encrypted and sent before closing the connection.

Parameters

cns	A pointer to the connection state structure.
err	The error code to be reported (if any).
notify	Set to true to notify the remote host of the connection closure.

pqs_connection_state_dispose()

PQS_EXPORT_API void pqs_connection_state_dispose

(

pqs_connection_state *

cns

)

Resets and disposes of the connection state.

This function disposes of the internal cipher states and clears the socket and sequence information in the connection state structure.

Parameters

cns	A pointer to the connection state structure to dispose.

pqs_error_description()

PQS_EXPORT_API const char * pqs_error_description

(

pqs_messages

emsg

)

Retrieves the description string for a given message enumeration.

Parameters

emsg	The message enumeration value.

Returns

A pointer to the corresponding message string, or NULL if invalid.

pqs_error_to_string()

PQS_EXPORT_API const char * pqs_error_to_string

(

pqs_errors

error

)

Converts an error code to its corresponding string description.

Parameters

error

The error code.

Returns

A pointer to the error description string, or NULL if invalid.

pqs_generate_keypair()

PQS_EXPORT_API void pqs_generate_keypair	(	pqs_client_verification_key *	pubkey,
		pqs_server_signature_key *	prikey,
		const uint8_t	keyid[PQS_KEYID_SIZE] )

Generates a PQS key pair.

This function creates a new asymmetric signature key pair for the server. The expiration time is set to the current UTC time plus the public key duration. The configuration string and key identity are copied to the server key structure, and the generated verification key is also copied to the client public key structure.

Parameters

pubkey	A pointer to the client public key structure (output).
prikey	A pointer to the server secret key structure (output).
keyid	A pointer to a key identity string (input).

pqs_header_validate()

PQS_EXPORT_API pqs_errors pqs_header_validate	(	pqs_connection_state *	cns,
		const pqs_network_packet *	packetin,
		pqs_flags	kexflag,
		pqs_flags	pktflag,
		uint64_t	sequence,
		uint32_t	msglen )

Validates a packet header and its associated timestamp.

Checks that the packet's message length, sequence number, flag, and timestamp are as expected. If the packet carries an error flag, the error code is extracted from the payload.

Parameters

cns	A pointer to the connection state structure.
packetin	A pointer to the input packet structure.
kexflag	The expected key exchange stage flag.
pktflag	The expected packet flag.
sequence	The expected packet sequence number.
msglen	The expected length of the message payload.

Returns

A pqs_errors value indicating the result of the validation.

pqs_log_error()

PQS_EXPORT_API void pqs_log_error	(	pqs_messages	emsg,
		qsc_socket_exceptions	err,
		const char *	msg )

Logs an error message along with socket error details.

This function writes an error message based on the provided message enumeration and appends additional error information from the socket exception if present.

Parameters

emsg	The message enumeration indicating the error type.
err	The socket exception value.
msg	A constant string providing additional context (input).

pqs_log_message()

PQS_EXPORT_API void pqs_log_message

(

pqs_messages

emsg

)

Logs a message based on the provided message enumeration.

Parameters

emsg	The message enumeration to be logged.

pqs_log_write()

PQS_EXPORT_API void pqs_log_write	(	pqs_messages	emsg,
		const char *	msg )

Logs a message with an accompanying description.

Parameters

emsg	The message enumeration.
msg	A constant string containing additional information.

pqs_packet_clear()

PQS_EXPORT_API void pqs_packet_clear

(

pqs_network_packet *

packet

)

Clears the state of a network packet.

Resets the packet flag, message length, and sequence number to default values. If the packet contains a message payload, it is cleared.

Parameters

packet

A pointer to the packet structure to clear.

pqs_packet_decrypt()

PQS_EXPORT_API pqs_errors pqs_packet_decrypt	(	pqs_connection_state *	cns,
		uint8_t *	message,
		size_t *	msglen,
		const pqs_network_packet *	packetin )

Decrypts an incoming packet's payload.

This function verifies the packet sequence number and timestamp before attempting to decrypt the payload using the associated receive cipher state. The decrypted message is copied to the output buffer.

Parameters

cns	A pointer to the connection state structure.
message	An output buffer for the decrypted message.
msglen	A pointer to a size variable to receive the length of the decrypted message.
packetin	A constant pointer to the input packet structure.

Returns

A pqs_errors value indicating the status of the decryption operation.

pqs_packet_encrypt()

PQS_EXPORT_API pqs_errors pqs_packet_encrypt	(	pqs_connection_state *	cns,
		pqs_network_packet *	packetout,
		const uint8_t *	message,
		size_t	msglen )

Encrypts a message and constructs an output packet.

This function increments the transmit sequence number, creates a packet header, and sets the associated data for the transmit cipher state before encrypting the provided message payload.

Parameters

cns	A pointer to the connection state structure.
packetout	A pointer to the output packet structure to be populated.
message	A constant pointer to the input message to encrypt.
msglen	The length in bytes of the input message.

Returns

A pqs_errors value indicating the status of the encryption operation.

pqs_packet_error_message()

PQS_EXPORT_API void pqs_packet_error_message	(	pqs_network_packet *	packet,
		pqs_errors	error )

Populates a packet structure with an error message.

Sets the packet flag to indicate an error, assigns a predefined sequence number, and writes the error code into the message payload.

Parameters

packet	A pointer to the packet structure (output).
error	The error code to embed in the packet.

pqs_packet_header_create()

PQS_EXPORT_API void pqs_packet_header_create	(	pqs_network_packet *	packetout,
		pqs_flags	flag,
		uint64_t	sequence,
		uint32_t	msglen )

Creates and populates a packet header.

This function sets the flag, sequence number, and message length in the packet header, and assigns the current UTC time as the creation timestamp.

Parameters

packetout	A pointer to the output packet structure.
flag	The packet flag indicating the packet type.
sequence	The packet sequence number.
msglen	The length in bytes of the message payload.

pqs_packet_header_deserialize()

PQS_EXPORT_API void pqs_packet_header_deserialize	(	const uint8_t *	header,
		pqs_network_packet *	packet )

Deserializes a byte array into a packet header.

Parameters

header	A constant pointer to the byte array representing the packet header.
packet	A pointer to the packet structure to populate.

pqs_packet_header_serialize()

PQS_EXPORT_API void pqs_packet_header_serialize	(	const pqs_network_packet *	packet,
		uint8_t *	header )

Serializes a packet header into a byte array.

Parameters

packet	A constant pointer to the packet structure to serialize.
header	A pointer to the byte array that will receive the serialized header.

pqs_packet_time_set()

PQS_EXPORT_API void pqs_packet_time_set

(

pqs_network_packet *

packet

)

Sets the packet's UTC timestamp to the current time.

Parameters

packet

A pointer to the network packet whose timestamp is to be set.

pqs_packet_time_validate()

PQS_EXPORT_API bool pqs_packet_time_validate

(

const pqs_network_packet *

packet

)

Validates the timestamp of a packet against the local UTC time.

Ensures that the packet's timestamp is within the acceptable time threshold (PQS_PACKET_TIME_THRESHOLD) relative to the current UTC time.

Parameters

packet

A constant pointer to the network packet.

Returns

True if the packet timestamp is valid; otherwise, false.

pqs_packet_to_stream()

PQS_EXPORT_API size_t pqs_packet_to_stream	(	const pqs_network_packet *	packet,
		uint8_t *	pstream )

Serializes a full packet (header and payload) into a byte stream.

Parameters

packet	A constant pointer to the packet structure to serialize.
pstream	A pointer to the output byte array.

Returns

The total number of bytes written to the byte stream.

pqs_public_key_decode()

PQS_EXPORT_API bool pqs_public_key_decode	(	pqs_client_verification_key *	pubk,
		const char	enck[PQS_PUBKEY_STRING_SIZE] )

Decodes an encoded public key string into a client verification key structure.

This function parses the encoded string (which includes header, configuration, key identity, expiration timestamp, and base64-encoded verification key) and populates the client key structure.

Parameters

pubk	A pointer to the output client verification key structure.
enck	A constant encoded public key string.

Returns

True if decoding and parsing were successful; otherwise, false.

pqs_public_key_encode()

PQS_EXPORT_API void pqs_public_key_encode	(	char	enck[PQS_PUBKEY_STRING_SIZE],
		const pqs_client_verification_key *	pubkey )

Encodes a client public key structure into a printable string.

The encoded string includes the header, version, configuration, key identity, expiration timestamp, and a base64-encoded verification key, formatted with line breaks.

Parameters

enck	A pointer to the output encoded public key string.
pubkey	A constant pointer to the client verification key structure.

pqs_public_key_hash()

PQS_EXPORT_API void pqs_public_key_hash	(	uint8_t *	hash,
		const pqs_client_verification_key *	pubk )

Computes a hash of a public key structure.

Uses the SHA3/Keccak hash function to compute a 256-bit hash over the public key's configuration, expiration, key identity, and verification key.

Parameters

hash	An output array to receive the hash (must be at least PQS_HASH_SIZE bytes).
pubk	A constant pointer to the client verification key structure.

pqs_signature_key_deserialize()

PQS_EXPORT_API void pqs_signature_key_deserialize	(	pqs_server_signature_key *	kset,
		const uint8_t	serk[PQS_SIGKEY_ENCODED_SIZE] )

Deserializes an encoded secret signature key into a server signature key structure.

Parameters

kset	A pointer to the output server signature key structure.
serk	A constant array containing the encoded secret key.

pqs_signature_key_serialize()

PQS_EXPORT_API void pqs_signature_key_serialize	(	uint8_t	serk[PQS_SIGKEY_ENCODED_SIZE],
		const pqs_server_signature_key *	kset )

Serializes a server secret signature key structure into an encoded array.

Parameters

serk	A pointer to the output encoded key array.
kset	A constant pointer to the server signature key structure.

pqs_stream_to_packet()

PQS_EXPORT_API void pqs_stream_to_packet	(	const uint8_t *	pstream,
		pqs_network_packet *	packet )

Deserializes a byte stream into a network packet structure.

Parameters

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