QSTP support header. More...

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

Data Structures
struct	qstp_certificate_expiration
	Certificate expiration time structure. More...

struct	qstp_keep_alive_state
	The QSTP keep alive state structure. More...

struct	qstp_server_certificate
	The server certificate structure. More...

struct	qstp_server_signature_key
	The QSTP server key structure. More...

struct	qstp_root_certificate
	The root certificate structure. More...

struct	qstp_root_signature_key
	The QSTP root key structure. More...

struct	qstp_network_packet
	The QSTP network packet structure. More...

struct	qstp_connection_state
	The QSTP socket connection state structure. More...

Macros
#define	QSTP_CONFIG_DILITHIUM_KYBER
	Sets the asymmetric cryptographic primitive-set to Dilithium/Kyber.

#define	QSTP_PROTOCOL_SET_SIZE 42
	The size of the protocol configuration string.

#define	qstp_cipher_generate_keypair qsc_kyber_generate_keypair
	Generate an asymmetric cipher key-pair using Kyber.

#define	qstp_cipher_decapsulate qsc_kyber_decapsulate
	Decapsulate a shared-secret with the Kyber asymmetric cipher.

#define	qstp_cipher_encapsulate qsc_kyber_encapsulate
	Encapsulate a shared-secret with the Kyber asymmetric cipher.

#define	qstp_signature_generate_keypair qsc_dilithium_generate_keypair
	Generate an asymmetric signature key-pair using Dilithium.

#define	qstp_signature_sign qsc_dilithium_sign
	Sign a message using the Dilithium signature scheme.

#define	qstp_signature_verify qsc_dilithium_verify
	Verify a message using the Dilithium signature scheme.

#define	QSTP_ASYMMETRIC_CIPHER_TEXT_SIZE (QSC_KYBER_CIPHERTEXT_SIZE)
	The byte size of the asymmetric cipher-text array (Kyber)

#define	QSTP_ASYMMETRIC_PRIVATE_KEY_SIZE (QSC_KYBER_PRIVATEKEY_SIZE)
	The byte size of the asymmetric cipher private-key array (Kyber)

#define	QSTP_ASYMMETRIC_PUBLIC_KEY_SIZE (QSC_KYBER_PUBLICKEY_SIZE)
	The byte size of the asymmetric cipher public-key array (Kyber)

#define	QSTP_ASYMMETRIC_SIGNING_KEY_SIZE (QSC_DILITHIUM_PRIVATEKEY_SIZE)
	The byte size of the asymmetric signature signing-key array (Dilithium)

#define	QSTP_ASYMMETRIC_VERIFICATION_KEY_SIZE (QSC_DILITHIUM_PUBLICKEY_SIZE)
	The byte size of the asymmetric signature verification-key array (Dilithium)

#define	QSTP_ASYMMETRIC_SIGNATURE_SIZE (QSC_DILITHIUM_SIGNATURE_SIZE)
	The byte size of the asymmetric signature array (Dilithium)

#define	QSTP_ACTIVE_VERSION 1
	The QSTP active version.

#define	QSTP_CERTIFICATE_ALGORITHM_SIZE 1
	The certificate algorithm type field size in bytes.

#define	QSTP_CERTIFICATE_DESIGNATION_SIZE 1
	The certificate designation field size in bytes.

#define	QSTP_CERTIFICATE_EXPIRATION_SIZE 16
	The length (in bytes) of the certificate expiration date.

#define	QSTP_CERTIFICATE_HASH_SIZE 32
	The size in bytes of the certificate hash.

#define	QSTP_CERTIFICATE_ISSUER_SIZE 32
	The maximum length of the certificate issuer string (including terminator).

#define	QSTP_CERTIFICATE_LINE_LENGTH 64
	The line length for printing the MPDC certificate.

#define	QSTP_CERTIFICATE_DEFAULT_PERIOD ((uint64_t)365 * 24 * 60 * 60)
	The default certificate validity period in milliseconds.

#define	QSTP_CERTIFICATE_DEFAULT_DURATION_DAYS 365
	The default number of days a public key remains valid.

#define	QSTP_CERTIFICATE_DEFAULT_DURATION_SECONDS (QSTP_CERTIFICATE_DEFAULT_DURATION_DAYS * 24 * 60 * 60)
	The number of seconds a public key remains valid.

#define	QSTP_CERTIFICATE_LINE_LENGTH 64
	The line length for printing the MPDC certificate.

#define	QSTP_CERTIFICATE_MAXIMUM_PERIOD (QSTP_CERTIFICATE_DEFAULT_PERIOD * 2)
	The maximum certificate validity period in milliseconds.

#define	QSTP_CERTIFICATE_MINIMUM_PERIOD ((uint64_t)1 * 24 * 60 * 60)
	The minimum certificate validity period in milliseconds.

#define	QSTP_CERTIFICATE_SERIAL_SIZE 16
	The length of the certificate serial number field in bytes.

#define	QSTP_CERTIFICATE_SERIAL_ENCODED_SIZE 32
	The length of the hex-encoded certificate serial number string.

#define	QSTP_CERTIFICATE_SIGNED_HASH_SIZE (QSTP_ASYMMETRIC_SIGNATURE_SIZE + QSTP_CERTIFICATE_HASH_SIZE)
	The size in bytes of the signature and hash field in a certificate.

#define	QSTP_CERTIFICATE_TIMESTAMP_SIZE 8
	The size in bytes of the key expiration timestamp.

#define	QSTP_CERTIFICATE_VERSION_SIZE 1
	The size in bytes of the certificate version field.

#define	QSTP_CONNECTIONS_INIT 1000
	The initial QSTP connections queue size.

#define	QSTP_CONNECTIONS_MAX 50000
	The maximum number of QSTP connections.

#define	QSTP_CONNECTION_MTU 1500
	The QSTP packet buffer (MTU) size in bytes.

#define	QSTP_KEEPALIVE_TIMEOUT (120 * 1000)
	The keep alive timeout in milliseconds (2 minutes).

#define	QSTP_MACTAG_SIZE 32
	The MAC tag size in bytes.

#define	QSTP_NONCE_SIZE 32
	The size in bytes of the symmetric cipher nonce.

#define	QSTP_PACKET_ERROR_SEQUENCE 0xFF00000000000000ULL
	The packet error sequence number.

#define	QSTP_PACKET_ERROR_SIZE 1
	The size in bytes of the packet error message.

#define	QSTP_PACKET_FLAG_SIZE 1
	The size in bytes of the packet flag field.

#define	QSTP_PACKET_HEADER_SIZE 21
	The size in bytes of the QSTP packet header.

#define	QSTP_PACKET_MESSAGE_LENGTH_SIZE 4
	The size in bytes of the packet message length field.

#define	QSTP_PACKET_MESSAGE_MAX 0x3D090000
	The maximum message size (in bytes) used during the key exchange (approximately 1 GB).

#define	QSTP_PACKET_REVOCATION_SEQUENCE 0xFFUL
	The packet sequence number used for revocation messages.

#define	QSTP_PACKET_SEQUENCE_SIZE 8
	The size in bytes of the packet sequence number.

#define	QSTP_PACKET_SEQUENCE_TERMINATOR 0xFFFFFFFFUL
	The packet sequence number that indicates a connection termination.

#define	QSTP_PACKET_TIME_THRESHOLD 60
	The maximum number of seconds a packet is considered valid.

#define	QSTP_SECRET_SIZE 32
	The size in bytes of the shared secret for each channel.

#define	QSTP_CLIENT_PORT 32118
	The default QSTP client port number.

#define	QSTP_SERVER_PORT 32119
	The default QSTP server port number.

#define	QSTP_ROOT_PORT 32120
	The default QSTP root port number.

#define	QSTP_SYMMETRIC_KEY_SIZE 32
	The size in bytes of the Simplex 256-bit symmetric cipher key.

#define	QSTP_STORAGE_PATH_MAX 260
	The maximum file system path size.

#define	QSTP_ROOT_CERTIFICATE_SIZE
	The total length in bytes of the root certificate.

#define	QSTP_ROOT_SIGNATURE_KEY_SIZE
	The total length in bytes of the root signature key.

#define	QSTP_SERVER_CERTIFICATE_SIZE
	The total length in bytes of a server certificate.

#define	QSTP_SERVER_SIGNATURE_KEY_SIZE
	The total length in bytes of a server signing key.

Typedefs
typedef QSTP_EXPORT_API enum qstp_configuration_sets	qstp_configuration_sets

typedef QSTP_EXPORT_API enum qstp_messages	qstp_messages

typedef QSTP_EXPORT_API enum qstp_errors	qstp_errors

typedef QSTP_EXPORT_API enum qstp_flags	qstp_flags

typedef QSTP_EXPORT_API enum qstp_network_designations	qstp_network_designations

typedef QSTP_EXPORT_API enum qstp_version_sets	qstp_version_sets

typedef QSTP_EXPORT_API struct qstp_certificate_expiration	qstp_certificate_expiration

typedef QSTP_EXPORT_API struct qstp_keep_alive_state	qstp_keep_alive_state

typedef QSTP_EXPORT_API struct qstp_server_certificate	qstp_server_certificate

typedef QSTP_EXPORT_API struct qstp_server_signature_key	qstp_server_signature_key

typedef QSTP_EXPORT_API struct qstp_root_certificate	qstp_root_certificate

typedef QSTP_EXPORT_API struct qstp_root_signature_key	qstp_root_signature_key

typedef QSTP_EXPORT_API struct qstp_network_packet	qstp_network_packet

typedef QSTP_EXPORT_API struct qstp_connection_state	qstp_connection_state

Enumerations
enum	qstp_configuration_sets { qstp_configuration_set_none = 0x00 , qstp_configuration_set_dilithium1_kyber1_rcs256_shake256 = 0x01 , qstp_configuration_set_dilithium3_kyber3_rcs256_shake256 = 0x02 , qstp_configuration_set_dilithium5_kyber5_rcs256_shake256 = 0x03 , qstp_configuration_set_dilithium5_kyber6_rcs512_shake512 = 0x04 , qstp_configuration_set_dilithium1_mceliece1_rcs256_shake256 = 0x05 , qstp_configuration_set_dilithium3_mceliece3_rcs256_shake256 = 0x06 , qstp_configuration_set_dilithium5_mceliece5_rcs256_shake256 = 0x07 , qstp_configuration_set_dilithium5_mceliece6_rcs256_shake256 = 0x08 , qstp_configuration_set_dilithium5_mceliece7_rcs256_shake256 = 0x09 , qstp_configuration_set_sphincsplus1f_mceliece1_rcs256_shake256 = 0x0A , qstp_configuration_set_sphincsplus1s_mceliece1_rcs256_shake256 = 0x0B , qstp_configuration_set_sphincsplus3f_mceliece3_rcs256_shake256 = 0x0C , qstp_configuration_set_sphincsplus3s_mceliece3_rcs256_shake256 = 0x0D , qstp_configuration_set_sphincsplus5f_mceliece5_rcs256_shake256 = 0x0E , qstp_configuration_set_sphincsplus5s_mceliece5_rcs256_shake256 = 0x0F , qstp_configuration_set_sphincsplus5f_mceliece6_rcs256_shake256 = 0x10 , qstp_configuration_set_sphincsplus5s_mceliece6_rcs256_shake256 = 0x11 , qstp_configuration_set_sphincsplus5f_mceliece7_rcs256_shake256 = 0x12 , qstp_configuration_set_sphincsplus5s_mceliece7_rcs256_shake256 = 0x13 }
	The MPDC algorithm configuration sets. More...

enum	qstp_messages { qstp_messages_none = 0x00 , qstp_messages_accept_fail = 0x01 , qstp_messages_listen_fail = 0x02 , qstp_messages_bind_fail = 0x03 , qstp_messages_create_fail = 0x04 , qstp_messages_connect_success = 0x05 , qstp_messages_receive_fail = 0x06 , qstp_messages_allocate_fail = 0x07 , qstp_messages_kex_fail = 0x08 , qstp_messages_disconnect = 0x09 , qstp_messages_disconnect_fail = 0x0A , qstp_messages_socket_message = 0x0B , qstp_messages_queue_empty = 0x0C , qstp_messages_listener_fail = 0x0D , qstp_messages_sockalloc_fail = 0x0E , qstp_messages_decryption_fail = 0x0F , qstp_messages_keepalive_fail = 0x10 , qstp_messages_keepalive_timeout = 0x11 , qstp_messages_connection_fail = 0x12 , qstp_messages_invalid_request = 0x13 }
	The logging message enumeration. More...

enum	qstp_errors { qstp_error_none = 0x00 , qstp_error_accept_fail = 0x01 , qstp_error_authentication_failure = 0x02 , qstp_error_bad_keep_alive = 0x03 , qstp_error_channel_down = 0x04 , qstp_error_connection_failure = 0x05 , qstp_error_connect_failure = 0x06 , qstp_error_decapsulation_failure = 0x07 , qstp_error_decryption_failure = 0x08 , qstp_error_establish_failure = 0x09 , qstp_error_exchange_failure = 0x0A , qstp_error_hash_invalid = 0x0B , qstp_error_hosts_exceeded = 0x0C , qstp_error_invalid_input = 0x0D , qstp_error_invalid_request = 0x0E , qstp_error_keepalive_expired = 0x0F , qstp_error_keepalive_timeout = 0x10 , qstp_error_key_expired = 0x11 , qstp_error_key_unrecognized = 0x12 , qstp_error_keychain_fail = 0x13 , qstp_error_listener_fail = 0x14 , qstp_error_memory_allocation = 0x15 , qstp_error_message_time_invalid = 0x16 , qstp_error_packet_unsequenced = 0x17 , qstp_error_random_failure = 0x18 , qstp_error_receive_failure = 0x19 , qstp_error_signature_failure = 0x1A , qstp_error_transmit_failure = 0x1B , qstp_error_unknown_protocol = 0x1C , qstp_error_verify_failure = 0x1D }
	The QSTP error values. More...

enum	qstp_flags { qstp_flag_none = 0x00 , qstp_flag_connect_request = 0x01 , qstp_flag_connect_response = 0x02 , qstp_flag_connection_terminate = 0x03 , qstp_flag_encrypted_message = 0x04 , qstp_flag_exstart_request = 0x05 , qstp_flag_exstart_response = 0x06 , qstp_flag_exchange_request = 0x07 , qstp_flag_exchange_response = 0x08 , qstp_flag_establish_request = 0x09 , qstp_flag_establish_response = 0x0A , qstp_flag_keep_alive_request = 0x0B , qstp_flag_keep_alive_response = 0x0C , qstp_flag_remote_connected = 0x0E , qstp_flag_remote_terminated = 0x0F , qstp_flag_session_established = 0x10 , qstp_flag_session_establish_verify = 0x11 , qstp_flag_unrecognized_protocol = 0x12 , qstp_flag_certificate_revoke = 0x13 , qstp_flag_transfer_request = 0x14 , qstp_flag_error_condition = 0xFF }
	The QSTP packet flags. More...

enum	qstp_network_designations { qstp_network_designation_none = 0x00 , mpdc_network_designation_client = 0x01 , mpdc_network_designation_root = 0x02 , mpdc_network_designation_server = 0x03 , mpdc_network_designation_all = 0xFF }
	The MPDC device designations. More...

enum	qstp_version_sets { qstp_version_set_none = 0x00 , qstp_version_set_one_zero = 0x01 }
	The MPDC version sets. More...

Functions
QSTP_EXPORT_API qstp_configuration_sets	qstp_configuration_from_string (const char *config)
	Get the configuration enumerator from a string.

QSTP_EXPORT_API const char *	qstp_configuration_to_string (qstp_configuration_sets cset)
	Get the configuration string from the enumerator.

QSTP_EXPORT_API void	qstp_connection_close (qstp_connection_state *cns, qstp_errors err, bool notify)
	Close the network connection between hosts.

QSTP_EXPORT_API void	qstp_connection_state_dispose (qstp_connection_state *cns)
	Reset the connection state to zero.

QSTP_EXPORT_API qstp_errors	qstp_decrypt_packet (qstp_connection_state cns, uint8_t message, size_t msglen, const qstp_network_packet packetin)
	Decrypt a message from an input packet.

QSTP_EXPORT_API qstp_errors	qstp_encrypt_packet (qstp_connection_state cns, qstp_network_packet packetout, const uint8_t *message, size_t msglen)
	Encrypt a message and build an output packet.

QSTP_EXPORT_API const char *	qstp_error_to_string (qstp_errors error)
	Return a pointer to a string description of an error code.

QSTP_EXPORT_API void	qstp_header_create (qstp_network_packet *packetout, qstp_flags flag, uint64_t sequence, uint32_t msglen)
	Populate a packet header and set its creation time.

QSTP_EXPORT_API qstp_errors	qstp_header_validate (qstp_connection_state cns, const qstp_network_packet packetin, qstp_flags flag, uint64_t sequence, uint32_t msglen)
	Validate a packet header and timestamp.

QSTP_EXPORT_API const char *	qstp_get_error_description (qstp_messages emsg)
	Get the error description string for a QSTP logging message.

QSTP_EXPORT_API void	qstp_packet_header_deserialize (const uint8_t header, qstp_network_packet packet)
	Deserialize a byte array into a QSTP packet header.

QSTP_EXPORT_API void	qstp_packet_header_serialize (const qstp_network_packet packet, uint8_t header)
	Serialize a QSTP packet header into a byte array.

QSTP_EXPORT_API void	qstp_log_error (qstp_messages emsg, qsc_socket_exceptions err, const char *msg)
	Log an error with a message, socket error, and description.

QSTP_EXPORT_API void	qstp_log_message (qstp_messages emsg)
	Log a QSTP message.

QSTP_EXPORT_API void	qstp_log_write (qstp_messages emsg, const char *msg)
	Log a QSTP message with an additional description.

QSTP_EXPORT_API void	qstp_packet_clear (qstp_network_packet *packet)
	Clear the state of a QSTP network packet.

QSTP_EXPORT_API void	qstp_packet_error_message (qstp_network_packet *packet, qstp_errors error)
	Populate a QSTP packet with an error message.

QSTP_EXPORT_API void	qstp_packet_set_utc_time (qstp_network_packet *packet)
	Set the local UTC time (in seconds) in a QSTP packet header.

QSTP_EXPORT_API bool	qstp_packet_time_valid (const qstp_network_packet *packet)
	Check if a QSTP packet was received within the valid time threshold.

QSTP_EXPORT_API size_t	qstp_packet_to_stream (const qstp_network_packet packet, uint8_t pstream)
	Serialize a QSTP packet into a byte array.

QSTP_EXPORT_API bool	qstp_root_certificate_compare (const qstp_root_certificate a, const qstp_root_certificate b)
	Compare two root certificates for equivalence.

QSTP_EXPORT_API bool	qstp_root_certificate_decode (qstp_root_certificate root, const char enck, size_t enclen)
	Copy an encoded root certificate into a root certificate structure.

QSTP_EXPORT_API void	qstp_root_certificate_deserialize (qstp_root_certificate *root, const uint8_t input[QSTP_ROOT_CERTIFICATE_SIZE])
	Deserialize a root certificate from a serialized byte array.

QSTP_EXPORT_API size_t	qstp_root_certificate_encode (char enck, size_t enclen, const qstp_root_certificate root)
	Encode a root certificate into a readable string.

QSTP_EXPORT_API size_t	qstp_root_certificate_encoded_size ()
	Get the size required to encode a root certificate.

QSTP_EXPORT_API void	qstp_root_certificate_extract (qstp_root_certificate root, const qstp_root_signature_key kset)
	Extract the root certificate from a root signature key.

QSTP_EXPORT_API void	qstp_root_certificate_hash (uint8_t output[QSTP_CERTIFICATE_HASH_SIZE], const qstp_root_certificate *root)
	Compute the hash of a root certificate.

QSTP_EXPORT_API void	qstp_root_certificate_serialize (uint8_t output[QSTP_ROOT_CERTIFICATE_SIZE], const qstp_root_certificate *root)
	Serialize a root certificate into a byte array.

QSTP_EXPORT_API size_t	qstp_root_certificate_sign (qstp_server_certificate cert, const qstp_root_certificate root, const uint8_t *rsigkey)
	Sign a server certificate using the root certificate.

QSTP_EXPORT_API bool	qstp_root_certificate_verify (const qstp_root_certificate root, const qstp_server_certificate cert)
	Verify that a server certificate is signed by the root.

QSTP_EXPORT_API bool	qstp_root_certificate_to_file (const qstp_root_certificate root, const char fpath)
	Write a root certificate to a file.

QSTP_EXPORT_API bool	qstp_root_file_to_certificate (qstp_root_certificate root, const char fpath)
	Read a root certificate from a file into a root certificate structure.

QSTP_EXPORT_API bool	qstp_root_file_to_key (qstp_root_signature_key kset, const char fpath)
	Read a root signature key from a file into a root signature key structure.

QSTP_EXPORT_API void	qstp_root_get_issuer (char issuer[QSTP_CERTIFICATE_ISSUER_SIZE])
	Get the root certificate issuer name.

QSTP_EXPORT_API void	qstp_root_key_deserialize (qstp_root_signature_key *kset, const uint8_t input[QSTP_ROOT_SIGNATURE_KEY_SIZE])
	Deserialize a root signature key from an encoded array.

QSTP_EXPORT_API bool	qstp_root_key_to_file (const qstp_root_signature_key kset, const char fpath)
	Write a root signature key to a file.

QSTP_EXPORT_API void	qstp_root_key_serialize (uint8_t serk[QSTP_ROOT_SIGNATURE_KEY_SIZE], const qstp_root_signature_key *kset)
	Serialize a root signature key into an encoded array.

QSTP_EXPORT_API bool	qstp_server_certificate_compare (const qstp_server_certificate a, const qstp_server_certificate b)
	Compare two server certificates for equivalence.

QSTP_EXPORT_API void	qstp_server_certificate_deserialize (qstp_server_certificate *cert, const uint8_t input[QSTP_SERVER_CERTIFICATE_SIZE])
	Deserialize a server certificate from a serialized byte stream.

QSTP_EXPORT_API size_t	qstp_server_certificate_encode (char enck, size_t enclen, const qstp_server_certificate cert)
	Encode a public server certificate into a readable string.

QSTP_EXPORT_API size_t	qstp_server_certificate_encoded_size ()
	Get the size required to encode a server certificate.

QSTP_EXPORT_API void	qstp_server_certificate_extract (qstp_server_certificate cert, const qstp_server_signature_key kset)
	Extract the server certificate from a server signature key.

QSTP_EXPORT_API void	qstp_server_certificate_hash (uint8_t output[QSTP_CERTIFICATE_HASH_SIZE], const qstp_server_certificate *cert)
	Compute the hash of a server certificate.

QSTP_EXPORT_API void	qstp_server_root_certificate_hash (uint8_t rshash[QSTP_CERTIFICATE_HASH_SIZE], const qstp_root_certificate root, const qstp_server_certificate cert)
	Compute a combined hash of the root and server certificates.

QSTP_EXPORT_API void	qstp_server_certificate_serialize (uint8_t output[QSTP_SERVER_CERTIFICATE_SIZE], const qstp_server_certificate *cert)
	Serialize a server certificate into a byte array.

QSTP_EXPORT_API bool	qstp_server_certificate_to_file (const qstp_server_certificate cert, const char fpath)
	Write a server certificate to a file.

QSTP_EXPORT_API bool	qstp_server_file_to_certificate (qstp_server_certificate cert, const char fpath)
	Read a server certificate from a file into a server certificate structure.

QSTP_EXPORT_API bool	qstp_server_file_to_key (qstp_server_signature_key kset, const char fpath)
	Read a server signature key from a file into a server key structure.

QSTP_EXPORT_API void	qstp_server_get_issuer (char issuer[QSTP_CERTIFICATE_ISSUER_SIZE])
	Get the server certificate issuer name.

QSTP_EXPORT_API void	qstp_server_key_deserialize (qstp_server_signature_key *kset, const uint8_t input[QSTP_SERVER_SIGNATURE_KEY_SIZE])
	Deserialize a server signature key from an encoded array.

QSTP_EXPORT_API void	qstp_server_key_serialize (uint8_t output[QSTP_SERVER_SIGNATURE_KEY_SIZE], const qstp_server_signature_key *kset)
	Serialize a server signature key into a byte array.

QSTP_EXPORT_API bool	qstp_server_key_to_file (const qstp_server_signature_key kset, const char fpath)
	Write a server signature key to a file.

QSTP_EXPORT_API uint8_t	qstp_version_from_string (const char *sver, size_t sverlen)
	Convert a version string to a version number.

QSTP_EXPORT_API void	qstp_version_to_string (char *sver, uint8_t version)
	Convert a version number to a hexadecimal string.

QSTP_EXPORT_API bool	qstp_test_root_certificate_encoding (const qstp_root_certificate *root)
	Test the root certificate encoding and decoding functions.

QSTP_EXPORT_API bool	qstp_test_server_certificate_encoding (const qstp_server_certificate *cert)
	Test the server certificate encoding and decoding functions.

Detailed Description

QSTP support header.

This header file defines common parameters, macros, enumerations, type definitions, and function prototypes used by the QSTP (Quantum Secure Tunneling Protocol) client and server implementations.

QSTP is designed to provide a complete cryptographic protocol for secure tunneling by integrating post-quantum key exchange, authenticated encryption, and certificate-based authentication. The protocol utilizes various asymmetric cryptographic primitive sets (e.g., Kyber, McEliece, Dilithium, Sphincs+) which are configured in the QSC library's common.h file. For maximum security, the McEliece/SPHINCS+ set is recommended; for a balance of performance and security, the Dilithium/Kyber or Dilithium/McEliece sets are advised.

Recommended Parameter Sets:

Kyber-S1, Dilithium-S1
Kyber-S3, Dilithium-S3
Kyber-S5, Dilithium-S5
Kyber-S6, Dilithium-S5
McEliece-S1, Dilithium-S1(f,s)
McEliece-S3, Dilithium-S3(f,s)
McEliece-S5, Dilithium-S5(f,s)
McEliece-S6, Dilithium-S5(f,s)
McEliece-S1, Sphincs-S1(f,s)
McEliece-S3, Sphincs-S3(f,s)
McEliece-S5, Sphincs-S5(f,s)
McEliece-S6, Sphincs-S5(f,s)
McEliece-S7, Sphincs-S6(f,s)

Additional Notes:: When using the McEliece/SPHINCS+ options in Visual Studio, it may be necessary to increase the maximum stack size (e.g., to 200KB) to accommodate the larger key sizes.

The parameter sets used by QSTP are selected in the QSC library (via libraries/common.h) at their library defaults. A true 512-bit security level can be achieved by selecting the McEliece/SPHINCS+ parameter and configuring SPHINCS+ to one of the 512-bit options.

Macro Definition Documentation

◆ QSTP_CERTIFICATE_LINE_LENGTH [1/2]

#define QSTP_CERTIFICATE_LINE_LENGTH 64

The line length for printing the MPDC certificate.

The line length for printing the QSTP public key.

◆ QSTP_CERTIFICATE_LINE_LENGTH [2/2]

#define QSTP_CERTIFICATE_LINE_LENGTH 64

The line length for printing the MPDC certificate.

The line length for printing the QSTP public key.

◆ QSTP_CONNECTIONS_MAX

#define QSTP_CONNECTIONS_MAX 50000

The maximum number of QSTP connections.

Calculated based on approximately 5k bytes per connection (3480 for connection state + 1500 for MTU + overhead) on a system with 256GB of DRAM. Can be increased if supported by the hardware.

◆ QSTP_PACKET_TIME_THRESHOLD

#define QSTP_PACKET_TIME_THRESHOLD 60

The maximum number of seconds a packet is considered valid.

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

◆ QSTP_ROOT_CERTIFICATE_SIZE

#define QSTP_ROOT_CERTIFICATE_SIZE

Value:

    (QSTP_CERTIFICATE_HASH_SIZE + \
    QSTP_ASYMMETRIC_VERIFICATION_KEY_SIZE + \
    QSTP_CERTIFICATE_ISSUER_SIZE + \
    QSTP_CERTIFICATE_SERIAL_SIZE + \
    QSTP_CERTIFICATE_EXPIRATION_SIZE + \
    QSTP_CERTIFICATE_ALGORITHM_SIZE + \
    QSTP_CERTIFICATE_VERSION_SIZE)

The total length in bytes of the root certificate.

◆ QSTP_ROOT_SIGNATURE_KEY_SIZE

#define QSTP_ROOT_SIGNATURE_KEY_SIZE

Value:

    (QSTP_CERTIFICATE_ISSUER_SIZE + \
    QSTP_CERTIFICATE_SERIAL_SIZE + \
    QSTP_ASYMMETRIC_SIGNING_KEY_SIZE + \
    QSTP_ASYMMETRIC_VERIFICATION_KEY_SIZE + \
    QSTP_CERTIFICATE_EXPIRATION_SIZE + \
    QSTP_CERTIFICATE_ALGORITHM_SIZE + \
    QSTP_CERTIFICATE_VERSION_SIZE)

The total length in bytes of the root signature key.

◆ QSTP_SERVER_CERTIFICATE_SIZE

#define QSTP_SERVER_CERTIFICATE_SIZE

Value:

    (QSTP_CERTIFICATE_SIGNED_HASH_SIZE + \
    QSTP_ASYMMETRIC_VERIFICATION_KEY_SIZE + \
    QSTP_CERTIFICATE_ISSUER_SIZE + \
    QSTP_CERTIFICATE_SERIAL_SIZE + \
    QSTP_CERTIFICATE_SERIAL_SIZE + \
    QSTP_CERTIFICATE_EXPIRATION_SIZE + \
    QSTP_CERTIFICATE_ALGORITHM_SIZE + \
    QSTP_CERTIFICATE_DESIGNATION_SIZE + \
    QSTP_CERTIFICATE_VERSION_SIZE)

The total length in bytes of a server certificate.

◆ QSTP_SERVER_SIGNATURE_KEY_SIZE

#define QSTP_SERVER_SIGNATURE_KEY_SIZE

Value:

    (QSTP_ASYMMETRIC_SIGNING_KEY_SIZE + \
    QSTP_ASYMMETRIC_VERIFICATION_KEY_SIZE + \
    QSTP_CERTIFICATE_ISSUER_SIZE + \
    QSTP_CERTIFICATE_HASH_SIZE + \
    QSTP_CERTIFICATE_SERIAL_SIZE + \
    QSTP_CERTIFICATE_EXPIRATION_SIZE + \
    QSTP_CERTIFICATE_ALGORITHM_SIZE + \
    QSTP_CERTIFICATE_DESIGNATION_SIZE + \
    QSTP_CERTIFICATE_VERSION_SIZE)

The total length in bytes of a server signing key.

Enumeration Type Documentation

◆ qstp_configuration_sets

enum qstp_configuration_sets

The MPDC algorithm configuration sets.

Enumerator
qstp_configuration_set_none	No algorithm identifier is set
qstp_configuration_set_dilithium1_kyber1_rcs256_shake256	The Dilithium-S1/Kyber-S1/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium3_kyber3_rcs256_shake256	The Dilithium-S3/Kyber-S3/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium5_kyber5_rcs256_shake256	The Dilithium-S5/Kyber-S5/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium5_kyber6_rcs512_shake512	The Dilithium-S5/Kyber-S6/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium1_mceliece1_rcs256_shake256	The Dilithium-S1/McEliece-S1/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium3_mceliece3_rcs256_shake256	The Dilithium-S3/McEliece-S3/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium5_mceliece5_rcs256_shake256	The Dilithium-S5/McEliece-S5a/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium5_mceliece6_rcs256_shake256	The Dilithium-S5/McEliece-S6/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_dilithium5_mceliece7_rcs256_shake256	The Dilithium-S5/McEliece-S7/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus1f_mceliece1_rcs256_shake256	The SPHINCS+-S1F/McEliece-S1/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus1s_mceliece1_rcs256_shake256	The SPHINCS+-S1S/McEliece-S1/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus3f_mceliece3_rcs256_shake256	The SPHINCS+-S3F/McEliece-S3/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus3s_mceliece3_rcs256_shake256	The SPHINCS+-S3S/McEliece-S3/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus5f_mceliece5_rcs256_shake256	The SPHINCS+-S5F/McEliece-S5a/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus5s_mceliece5_rcs256_shake256	The SPHINCS+-S5S/McEliece-S5a/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus5f_mceliece6_rcs256_shake256	The SPHINCS+-S5F/McEliece-S5b/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus5s_mceliece6_rcs256_shake256	The SPHINCS+-S5S/McEliece-S5b/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus5f_mceliece7_rcs256_shake256	The SPHINCS+-S5F/McEliece-S5c/RCS-256/SHAKE-256 algorithm set
qstp_configuration_set_sphincsplus5s_mceliece7_rcs256_shake256	The SPHINCS+-S5S/McEliece-S5c/RCS-256/SHAKE-256 algorithm set

◆ qstp_errors

enum qstp_errors

The QSTP error values.

Enumerator
qstp_error_none	No error was detected
qstp_error_accept_fail	The socket accept function returned an error
qstp_error_authentication_failure	The symmetric cipher had an authentication failure
qstp_error_bad_keep_alive	The keep alive check failed
qstp_error_channel_down	The communications channel has failed
qstp_error_connection_failure	The device could not make a connection to the remote host
qstp_error_connect_failure	The transmission failed at the KEX connection phase
qstp_error_decapsulation_failure	The asymmetric cipher failed to decapsulate the shared secret
qstp_error_decryption_failure	The decryption authentication has failed
qstp_error_establish_failure	The transmission failed at the KEX establish phase
qstp_error_exchange_failure	The transmission failed at the KEX exchange phase
qstp_error_hash_invalid	The public-key hash is invalid
qstp_error_hosts_exceeded	The server has run out of socket connections
qstp_error_invalid_input	The expected input was invalid
qstp_error_invalid_request	The packet flag was unexpected
qstp_error_keepalive_expired	The keep alive has expired with no response
qstp_error_keepalive_timeout	The decryption authentication has failed
qstp_error_key_expired	The QSTP public key has expired
qstp_error_key_unrecognized	The key identity is unrecognized
qstp_error_keychain_fail	The ratchet operation has failed
qstp_error_listener_fail	The listener function failed to initialize
qstp_error_memory_allocation	The server has run out of memory
qstp_error_message_time_invalid	The packet has valid time expired
qstp_error_packet_unsequenced	The packet was received out of sequence
qstp_error_random_failure	The random generator has failed
qstp_error_receive_failure	The receiver failed at the network layer
qstp_error_signature_failure	The signing function has failed
qstp_error_transmit_failure	The transmitter failed at the network layer
qstp_error_unknown_protocol	The protocol string was not recognized
qstp_error_verify_failure	The expected data could not be verified

◆ qstp_flags

enum qstp_flags

The QSTP packet flags.

Enumerator
qstp_flag_none	No flag was specified
qstp_flag_connect_request	The QSTP key-exchange client connection request flag
qstp_flag_connect_response	The QSTP key-exchange server connection response flag
qstp_flag_connection_terminate	Indicates the connection is to be terminated
qstp_flag_encrypted_message	Indicates the packet contains an encrypted message
qstp_flag_exstart_request	The QSTP key-exchange client exstart request flag
qstp_flag_exstart_response	The QSTP key-exchange server exstart response flag
qstp_flag_exchange_request	The QSTP key-exchange client exchange request flag
qstp_flag_exchange_response	The QSTP key-exchange server exchange response flag
qstp_flag_establish_request	The QSTP key-exchange client establish request flag
qstp_flag_establish_response	The QSTP key-exchange server establish response flag
qstp_flag_keep_alive_request	The packet contains a keep alive request
qstp_flag_keep_alive_response	The packet contains a keep alive response
qstp_flag_remote_connected	Indicates that the remote host is connected
qstp_flag_remote_terminated	Indicates that the remote host has terminated the connection
qstp_flag_session_established	Indicates that the key exchange is in the established state
qstp_flag_session_establish_verify	Indicates that the key exchange is in the established verify state
qstp_flag_unrecognized_protocol	The protocol string is not recognized
qstp_flag_certificate_revoke	Indicates a certificate revocation message
qstp_flag_transfer_request	Reserved: Indicates a transfer request
qstp_flag_error_condition	Indicates that the connection experienced an error

◆ qstp_messages

enum qstp_messages

The logging message enumeration.

Enumerator
qstp_messages_none	No configuration was specified
qstp_messages_accept_fail	The socket accept failed
qstp_messages_listen_fail	The listener socket could not connect
qstp_messages_bind_fail	The listener socket could not bind to the address
qstp_messages_create_fail	The listener socket could not be created
qstp_messages_connect_success	The server connected to a host
qstp_messages_receive_fail	The socket receive function failed
qstp_messages_allocate_fail	The server memory allocation request has failed
qstp_messages_kex_fail	The key exchange has experienced a failure
qstp_messages_disconnect	The server has disconnected the client
qstp_messages_disconnect_fail	The server has disconnected the client due to an error
qstp_messages_socket_message	The server has had a socket level error
qstp_messages_queue_empty	The server has reached the maximum number of connections
qstp_messages_listener_fail	The server listener socket has failed
qstp_messages_sockalloc_fail	The server has run out of socket connections
qstp_messages_decryption_fail	The message decryption has failed
qstp_messages_keepalive_fail	The keepalive function has failed
qstp_messages_keepalive_timeout	The keepalive period has been exceeded
qstp_messages_connection_fail	The connection failed or was interrupted
qstp_messages_invalid_request	The function received an invalid request

◆ qstp_network_designations

enum qstp_network_designations

The MPDC device designations.

Enumerator
qstp_network_designation_none	No designation was selected
mpdc_network_designation_client	The device is a client
mpdc_network_designation_root	The device is the DLA (root)
mpdc_network_designation_server	The device is an inter-domain gateway (server)
mpdc_network_designation_all	All devices on the network

◆ qstp_version_sets

enum qstp_version_sets

The MPDC version sets.

Enumerator
qstp_version_set_none	No version identifier is set
qstp_version_set_one_zero	The 1.0 version identifier

Function Documentation

◆ qstp_configuration_from_string()

QSTP_EXPORT_API qstp_configuration_sets qstp_configuration_from_string ( const char * config )

Get the configuration enumerator from a string.

Parameters

config The configuration string.

Returns: The corresponding configuration set enumerator.

◆ qstp_configuration_to_string()

QSTP_EXPORT_API const char * qstp_configuration_to_string ( qstp_configuration_sets cset )

Get the configuration string from the enumerator.

Parameters

cset	The configuration set enumerator.

Returns: The configuration set string or NULL if not recognized.

◆ qstp_connection_close()

QSTP_EXPORT_API void qstp_connection_close	(	qstp_connection_state *	cns,
		qstp_errors	err,
		bool	notify )

Close the network connection between hosts.

Parameters

cns	A pointer to the QSTP connection state structure.
err	The error code.
notify	If true, notify the remote host that the connection is closing.

◆ qstp_connection_state_dispose()

QSTP_EXPORT_API void qstp_connection_state_dispose ( qstp_connection_state * cns )

Reset the connection state to zero.

Parameters

cns	A pointer to the QSTP connection state structure.

◆ qstp_decrypt_packet()

QSTP_EXPORT_API qstp_errors qstp_decrypt_packet	(	qstp_connection_state *	cns,
		uint8_t *	message,
		size_t *	msglen,
		const qstp_network_packet *	packetin )

Decrypt a message from an input packet.

Parameters

cns	A pointer to the QSTP connection state structure.
message	The output buffer for the decrypted message.
msglen	A pointer to a variable to receive the message length.
packetin	A pointer to the input QSTP network packet.

Returns: Returns the function error state.

◆ qstp_encrypt_packet()

QSTP_EXPORT_API qstp_errors qstp_encrypt_packet	(	qstp_connection_state *	cns,
		qstp_network_packet *	packetout,
		const uint8_t *	message,
		size_t	msglen )

Encrypt a message and build an output packet.

Parameters

cns	A pointer to the QSTP connection state structure.
packetout	A pointer to the output QSTP network packet.
message	The input message array.
msglen	The length of the message in bytes.

Returns: Returns the function error state.

◆ qstp_error_to_string()

QSTP_EXPORT_API const char * qstp_error_to_string ( qstp_errors error )

Return a pointer to a string description of an error code.

Parameters

error The QSTP error code.

Returns: Returns a pointer to an error string or NULL.

◆ qstp_get_error_description()

QSTP_EXPORT_API const char * qstp_get_error_description ( qstp_messages emsg )

Get the error description string for a QSTP logging message.

Parameters

emsg	The QSTP message enumeration.

Returns: Returns a pointer to the message string or NULL.

◆ qstp_header_create()

QSTP_EXPORT_API void qstp_header_create	(	qstp_network_packet *	packetout,
		qstp_flags	flag,
		uint64_t	sequence,
		uint32_t	msglen )

Populate a packet header and set its creation time.

Parameters

packetout	A pointer to the output QSTP network packet.
flag	The packet flag.
sequence	The packet sequence number.
msglen	The length of the message in bytes.

◆ qstp_header_validate()

QSTP_EXPORT_API qstp_errors qstp_header_validate	(	qstp_connection_state *	cns,
		const qstp_network_packet *	packetin,
		qstp_flags	flag,
		uint64_t	sequence,
		uint32_t	msglen )

Validate a packet header and timestamp.

Parameters

cns	A pointer to the QSTP connection state structure.
packetin	A pointer to the input QSTP network packet.
flag	The expected packet flag.
sequence	The expected packet sequence number.
msglen	The expected message length.

Returns: Returns the function error state.

◆ qstp_log_error()

QSTP_EXPORT_API void qstp_log_error	(	qstp_messages	emsg,
		qsc_socket_exceptions	err,
		const char *	msg )

Log an error with a message, socket error, and description.

Parameters

emsg	The QSTP message enumeration.
err	The socket exception enumeration.
msg	The additional descriptive message.

◆ qstp_log_message()

QSTP_EXPORT_API void qstp_log_message ( qstp_messages emsg )

Log a QSTP message.

Parameters

emsg	The QSTP message enumeration.

◆ qstp_log_write()

QSTP_EXPORT_API void qstp_log_write	(	qstp_messages	emsg,
		const char *	msg )

Log a QSTP message with an additional description.

Parameters

emsg	The QSTP message enumeration.
msg	The additional descriptive message.

◆ qstp_packet_clear()

QSTP_EXPORT_API void qstp_packet_clear ( qstp_network_packet * packet )

Clear the state of a QSTP network packet.

Parameters

packet A pointer to the QSTP network packet to clear.

◆ qstp_packet_error_message()

QSTP_EXPORT_API void qstp_packet_error_message	(	qstp_network_packet *	packet,
		qstp_errors	error )

Populate a QSTP packet with an error message.

Parameters

packet	A pointer to the QSTP network packet.
error	The QSTP error code.

◆ qstp_packet_header_deserialize()

QSTP_EXPORT_API void qstp_packet_header_deserialize	(	const uint8_t *	header,
		qstp_network_packet *	packet )

Deserialize a byte array into a QSTP packet header.

Parameters

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

◆ qstp_packet_header_serialize()

QSTP_EXPORT_API void qstp_packet_header_serialize	(	const qstp_network_packet *	packet,
		uint8_t *	header )

Serialize a QSTP packet header into a byte array.

Parameters

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

◆ qstp_packet_set_utc_time()

QSTP_EXPORT_API void qstp_packet_set_utc_time ( qstp_network_packet * packet )

Set the local UTC time (in seconds) in a QSTP packet header.

Parameters

packet A pointer to the QSTP network packet to update.

◆ qstp_packet_time_valid()

QSTP_EXPORT_API bool qstp_packet_time_valid ( const qstp_network_packet * packet )

Check if a QSTP packet was received within the valid time threshold.

Parameters

packet A pointer to the QSTP network packet.

Returns: Returns true if the packet's UTC time is within the valid threshold; otherwise, false.

◆ qstp_packet_to_stream()

QSTP_EXPORT_API size_t qstp_packet_to_stream	(	const qstp_network_packet *	packet,
		uint8_t *	pstream )

Serialize a QSTP packet into a byte array.

Parameters

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

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

◆ qstp_root_certificate_compare()

QSTP_EXPORT_API bool qstp_root_certificate_compare	(	const qstp_root_certificate *	a,
		const qstp_root_certificate *	b )

Compare two root certificates for equivalence.

Parameters

a	A pointer to the first root certificate.
b	A pointer to the second root certificate.

Returns: Returns true if the certificates are equal; otherwise, false.

◆ qstp_root_certificate_decode()

QSTP_EXPORT_API bool qstp_root_certificate_decode	(	qstp_root_certificate *	root,
		const char *	enck,
		size_t	enclen )

Copy an encoded root certificate into a root certificate structure.

Parameters

root	A pointer to the output root certificate structure.
enck	The encoded root certificate string.
enclen	The length of the encoded certificate.

Returns: Returns true on success; otherwise, false.

◆ qstp_root_certificate_deserialize()

QSTP_EXPORT_API void qstp_root_certificate_deserialize	(	qstp_root_certificate *	root,
		const uint8_t	input[QSTP_ROOT_CERTIFICATE_SIZE] )

Deserialize a root certificate from a serialized byte array.

Parameters

root	A pointer to the output root certificate.
input	A pointer to the serialized root certificate array.

◆ qstp_root_certificate_encode()

QSTP_EXPORT_API size_t qstp_root_certificate_encode	(	char *	enck,
		size_t	enclen,
		const qstp_root_certificate *	root )

Encode a root certificate into a readable string.

Parameters

enck	The output encoded certificate string.
enclen	The length of the output buffer.
root	A pointer to the root certificate.

Returns: Returns the size in bytes of the encoded certificate string.

◆ qstp_root_certificate_encoded_size()

QSTP_EXPORT_API size_t qstp_root_certificate_encoded_size ( )

Get the size required to encode a root certificate.

Returns: Returns the size in bytes of the encoded root certificate string.

◆ qstp_root_certificate_extract()

QSTP_EXPORT_API void qstp_root_certificate_extract	(	qstp_root_certificate *	root,
		const qstp_root_signature_key *	kset )

Extract the root certificate from a root signature key.

Parameters

root	The output root certificate.
kset	A pointer to the input root signature key structure.

◆ qstp_root_certificate_hash()

QSTP_EXPORT_API void qstp_root_certificate_hash	(	uint8_t	output[QSTP_CERTIFICATE_HASH_SIZE],
		const qstp_root_certificate *	root )

Compute the hash of a root certificate.

Parameters

output	The output hash array.
root	A pointer to the root certificate.

◆ qstp_root_certificate_serialize()

QSTP_EXPORT_API void qstp_root_certificate_serialize	(	uint8_t	output[QSTP_ROOT_CERTIFICATE_SIZE],
		const qstp_root_certificate *	root )

Serialize a root certificate into a byte array.

Parameters

output	The array that will receive the serialized certificate.
root	A pointer to the root certificate.

◆ qstp_root_certificate_sign()

QSTP_EXPORT_API size_t qstp_root_certificate_sign	(	qstp_server_certificate *	cert,
		const qstp_root_certificate *	root,
		const uint8_t *	rsigkey )

Sign a server certificate using the root certificate.

Parameters

cert	A pointer to the server certificate to sign.
root	A pointer to the root certificate.
rsigkey	A pointer to the root signing key (encoded).

Returns: Returns the size in bytes of the signed certificate.

◆ qstp_root_certificate_to_file()

QSTP_EXPORT_API bool qstp_root_certificate_to_file	(	const qstp_root_certificate *	root,
		const char *	fpath )

Write a root certificate to a file.

Parameters

root	A pointer to the root certificate.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_root_certificate_verify()

QSTP_EXPORT_API bool qstp_root_certificate_verify	(	const qstp_root_certificate *	root,
		const qstp_server_certificate *	cert )

Verify that a server certificate is signed by the root.

Parameters

root	A pointer to the root certificate.
cert	A pointer to the server certificate.

Returns: Returns true if the certificate is valid; otherwise, false.

◆ qstp_root_file_to_certificate()

QSTP_EXPORT_API bool qstp_root_file_to_certificate	(	qstp_root_certificate *	root,
		const char *	fpath )

Read a root certificate from a file into a root certificate structure.

Parameters

root	A pointer to the root certificate.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_root_file_to_key()

QSTP_EXPORT_API bool qstp_root_file_to_key	(	qstp_root_signature_key *	kset,
		const char *	fpath )

Read a root signature key from a file into a root signature key structure.

Parameters

kset	A pointer to the root signature key structure.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_root_get_issuer()

QSTP_EXPORT_API void qstp_root_get_issuer ( char issuer[QSTP_CERTIFICATE_ISSUER_SIZE] )

Get the root certificate issuer name.

Parameters

issuer The output buffer to receive the issuer string.

◆ qstp_root_key_deserialize()

QSTP_EXPORT_API void qstp_root_key_deserialize	(	qstp_root_signature_key *	kset,
		const uint8_t	input[QSTP_ROOT_SIGNATURE_KEY_SIZE] )

Deserialize a root signature key from an encoded array.

Parameters

kset	A pointer to the output root signature key structure.
input	The input serialized root key array.

◆ qstp_root_key_serialize()

QSTP_EXPORT_API void qstp_root_key_serialize	(	uint8_t	serk[QSTP_ROOT_SIGNATURE_KEY_SIZE],
		const qstp_root_signature_key *	kset )

Serialize a root signature key into an encoded array.

Parameters

serk	The output array for the serialized root key.
kset	A pointer to the root signature key structure.

◆ qstp_root_key_to_file()

QSTP_EXPORT_API bool qstp_root_key_to_file	(	const qstp_root_signature_key *	kset,
		const char *	fpath )

Write a root signature key to a file.

Parameters

kset	A pointer to the root signature key structure.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_server_certificate_compare()

QSTP_EXPORT_API bool qstp_server_certificate_compare	(	const qstp_server_certificate *	a,
		const qstp_server_certificate *	b )

Compare two server certificates for equivalence.

Parameters

a	A pointer to the first server certificate.
b	A pointer to the second server certificate.

Returns: Returns true if the certificates are equivalent; otherwise, false.

◆ qstp_server_certificate_deserialize()

QSTP_EXPORT_API void qstp_server_certificate_deserialize	(	qstp_server_certificate *	cert,
		const uint8_t	input[QSTP_SERVER_CERTIFICATE_SIZE] )

Deserialize a server certificate from a serialized byte stream.

Parameters

cert	A pointer to the server certificate structure to populate.
input	A pointer to the serialized certificate array.

◆ qstp_server_certificate_encode()

QSTP_EXPORT_API size_t qstp_server_certificate_encode	(	char *	enck,
		size_t	enclen,
		const qstp_server_certificate *	cert )

Encode a public server certificate into a readable string.

Parameters

enck	The output buffer for the encoded certificate string.
enclen	The length of the output buffer.
cert	A pointer to the server certificate.

Returns: Returns the size in bytes of the encoded certificate string.

◆ qstp_server_certificate_encoded_size()

QSTP_EXPORT_API size_t qstp_server_certificate_encoded_size ( )

Get the size required to encode a server certificate.

Returns: Returns the size in bytes of the encoded certificate string.

◆ qstp_server_certificate_extract()

QSTP_EXPORT_API void qstp_server_certificate_extract	(	qstp_server_certificate *	cert,
		const qstp_server_signature_key *	kset )

Extract the server certificate from a server signature key.

Parameters

cert	The output server certificate.
kset	A pointer to the server signature key structure.

◆ qstp_server_certificate_hash()

QSTP_EXPORT_API void qstp_server_certificate_hash	(	uint8_t	output[QSTP_CERTIFICATE_HASH_SIZE],
		const qstp_server_certificate *	cert )

Compute the hash of a server certificate.

Parameters

output	The output hash array.
cert	A pointer to the server certificate.

◆ qstp_server_certificate_serialize()

QSTP_EXPORT_API void qstp_server_certificate_serialize	(	uint8_t	output[QSTP_SERVER_CERTIFICATE_SIZE],
		const qstp_server_certificate *	cert )

Serialize a server certificate into a byte array.

Parameters

output	The output array for the serialized certificate.
cert	A pointer to the server certificate.

◆ qstp_server_certificate_to_file()

QSTP_EXPORT_API bool qstp_server_certificate_to_file	(	const qstp_server_certificate *	cert,
		const char *	fpath )

Write a server certificate to a file.

Parameters

cert	A pointer to the server certificate structure.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_server_file_to_certificate()

QSTP_EXPORT_API bool qstp_server_file_to_certificate	(	qstp_server_certificate *	cert,
		const char *	fpath )

Read a server certificate from a file into a server certificate structure.

Parameters

cert	A pointer to the server certificate structure.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_server_file_to_key()

QSTP_EXPORT_API bool qstp_server_file_to_key	(	qstp_server_signature_key *	kset,
		const char *	fpath )

Read a server signature key from a file into a server key structure.

Parameters

kset	A pointer to the server signature key structure.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_server_get_issuer()

QSTP_EXPORT_API void qstp_server_get_issuer ( char issuer[QSTP_CERTIFICATE_ISSUER_SIZE] )

Get the server certificate issuer name.

Parameters

issuer The output buffer for the issuer string.

◆ qstp_server_key_deserialize()

QSTP_EXPORT_API void qstp_server_key_deserialize	(	qstp_server_signature_key *	kset,
		const uint8_t	input[QSTP_SERVER_SIGNATURE_KEY_SIZE] )

Deserialize a server signature key from an encoded array.

Parameters

kset	A pointer to the output server signature key structure.
input	The input encoded server key array.

◆ qstp_server_key_serialize()

QSTP_EXPORT_API void qstp_server_key_serialize	(	uint8_t	output[QSTP_SERVER_SIGNATURE_KEY_SIZE],
		const qstp_server_signature_key *	kset )

Serialize a server signature key into a byte array.

Parameters

output	The output array for the serialized key.
kset	A pointer to the server signature key structure.

◆ qstp_server_key_to_file()

QSTP_EXPORT_API bool qstp_server_key_to_file	(	const qstp_server_signature_key *	kset,
		const char *	fpath )

Write a server signature key to a file.

Parameters

kset	A pointer to the server signature key structure.
fpath	The file path.

Returns: Returns true on success; otherwise, false.

◆ qstp_server_root_certificate_hash()

QSTP_EXPORT_API void qstp_server_root_certificate_hash	(	uint8_t	rshash[QSTP_CERTIFICATE_HASH_SIZE],
		const qstp_root_certificate *	root,
		const qstp_server_certificate *	cert )

Compute a combined hash of the root and server certificates.

Parameters

rshash	The output hash array.
root	A pointer to the root certificate.
cert	A pointer to the server certificate.

◆ qstp_test_root_certificate_encoding()

QSTP_EXPORT_API bool qstp_test_root_certificate_encoding ( const qstp_root_certificate * root )

Test the root certificate encoding and decoding functions.

Returns: Returns true if the encoding tests succeed

◆ qstp_test_server_certificate_encoding()

QSTP_EXPORT_API bool qstp_test_server_certificate_encoding ( const qstp_server_certificate * cert )

Test the server certificate encoding and decoding functions.

Returns: Returns true if the encoding tests succeed

◆ qstp_version_from_string()

QSTP_EXPORT_API uint8_t qstp_version_from_string	(	const char *	sver,
		size_t	sverlen )

Convert a version string to a version number.

Parameters

sver	The input version string.
sverlen	The length of the version string.

Returns: Returns the version number as an 8-bit value.

◆ qstp_version_to_string()

QSTP_EXPORT_API void qstp_version_to_string	(	char *	sver,
		uint8_t	version )

Convert a version number to a hexadecimal string.

Parameters

sver	The output version string.
version	The version number.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ QSTP_CERTIFICATE_LINE_LENGTH [1/2]

◆ QSTP_CERTIFICATE_LINE_LENGTH [2/2]

◆ QSTP_CONNECTIONS_MAX

◆ QSTP_PACKET_TIME_THRESHOLD

◆ QSTP_ROOT_CERTIFICATE_SIZE

◆ QSTP_ROOT_SIGNATURE_KEY_SIZE

◆ QSTP_SERVER_CERTIFICATE_SIZE

◆ QSTP_SERVER_SIGNATURE_KEY_SIZE

Enumeration Type Documentation

◆ qstp_configuration_sets

◆ qstp_errors

◆ qstp_flags

◆ qstp_messages

◆ qstp_network_designations

◆ qstp_version_sets

Function Documentation

◆ qstp_configuration_from_string()

◆ qstp_configuration_to_string()

◆ qstp_connection_close()

◆ qstp_connection_state_dispose()

◆ qstp_decrypt_packet()

◆ qstp_encrypt_packet()

◆ qstp_error_to_string()

◆ qstp_get_error_description()

◆ qstp_header_create()

◆ qstp_header_validate()

◆ qstp_log_error()

◆ qstp_log_message()

◆ qstp_log_write()

◆ qstp_packet_clear()

◆ qstp_packet_error_message()

◆ qstp_packet_header_deserialize()

◆ qstp_packet_header_serialize()

◆ qstp_packet_set_utc_time()

◆ qstp_packet_time_valid()

◆ qstp_packet_to_stream()

◆ qstp_root_certificate_compare()

◆ qstp_root_certificate_decode()

◆ qstp_root_certificate_deserialize()

◆ qstp_root_certificate_encode()

◆ qstp_root_certificate_encoded_size()

◆ qstp_root_certificate_extract()

◆ qstp_root_certificate_hash()

◆ qstp_root_certificate_serialize()

◆ qstp_root_certificate_sign()

◆ qstp_root_certificate_to_file()

◆ qstp_root_certificate_verify()

◆ qstp_root_file_to_certificate()

◆ qstp_root_file_to_key()

◆ qstp_root_get_issuer()

◆ qstp_root_key_deserialize()

◆ qstp_root_key_serialize()

◆ qstp_root_key_to_file()

◆ qstp_server_certificate_compare()

◆ qstp_server_certificate_deserialize()

◆ qstp_server_certificate_encode()

◆ qstp_server_certificate_encoded_size()

◆ qstp_server_certificate_extract()

◆ qstp_server_certificate_hash()

◆ qstp_server_certificate_serialize()

◆ qstp_server_certificate_to_file()

◆ qstp_server_file_to_certificate()

◆ qstp_server_file_to_key()

◆ qstp_server_get_issuer()

◆ qstp_server_key_deserialize()

◆ qstp_server_key_serialize()

◆ qstp_server_key_to_file()

◆ qstp_server_root_certificate_hash()

◆ qstp_test_root_certificate_encoding()

◆ qstp_test_server_certificate_encoding()

◆ qstp_version_from_string()

◆ qstp_version_to_string()