QSMP support header Common defined parameters and functions of the qsmp client and server implementations. More...

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

Data Structures
struct	qsmp_asymmetric_cipher_keypair
	The QSMP asymmetric cipher key container. More...

struct	qsmp_asymmetric_signature_keypair
	The QSMP asymmetric signature key container. More...

struct	qsmp_network_packet
	The QSMP packet structure. More...

struct	qsmp_client_verification_key
	The QSMP client key structure. More...

struct	qsmp_server_signature_key
	The QSMP server key structure. More...

struct	qsmp_keep_alive_state
	The QSMP keep alive state structure. More...

struct	qsmp_connection_state
	The QSMP socket connection state structure. More...

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

#define	QSMP_CONFIG_SIZE 48
	The size of the protocol configuration string.

#define	QSMP_SIMPLEX_HASH_SIZE 32
	The Simplex 256-bit hash function output size.

#define	QSMP_SIMPLEX_MACKEY_SIZE 32
	The Simplex 256-bit mac key size.

#define	QSMP_SIMPLEX_MACTAG_SIZE 32
	The Simplex 256-bit mac key size.

#define	QSMP_SIMPLEX_SYMMETRIC_KEY_SIZE 32
	The Simplex 256-bit symmetric cipher key size.

#define	QSMP_SIMPLEX_SCHASH_SIZE 32
	The Simplex 256-bit session token hash size.

#define	QSMP_DUPLEX_HASH_SIZE 64
	The Duplex 512-bit hash function size.

#define	QSMP_DUPLEX_MACKEY_SIZE 64
	The Duplex 512-bit mac key size.

#define	QSMP_DUPLEX_MACTAG_SIZE 64
	The Duplex 512-bit mac key size.

#define	QSMP_DUPLEX_SYMMETRIC_KEY_SIZE 64
	TheDuplex 512-bit symmetric cipher key size.

#define	QSMP_DUPLEX_SCHASH_SIZE 64
	The Duplex session token 512-bit hash size.

#define	QSMP_ASYMMETRIC_KEYCHAIN_COUNT 10
	The key-chain asymmetric key count.

#define	QSMP_CLIENT_PORT 31118
	The default client port address.

#define	QSMP_CONNECTIONS_INIT 1000
	The intitial QSMP connections queue size.

#define	QSMP_CONNECTIONS_MAX 50000
	The maximum number of connections Calculated given approx 5k (3480 connection state + 1500 mtu + overhead), per connection on 256GB of DRAM. Can be scaled to a greater number provided the hardware can support it.

#define	QSMP_CONNECTION_MTU 1500
	The QSMP packet buffer size.

#define	QSMP_ERROR_SEQUENCE 0xFF00000000000000ULL
	The packet error sequence number.

#define	QSMP_ERROR_MESSAGE_SIZE 1
	The packet error message size.

#define	QSMP_FLAG_SIZE 1
	The packet flag size.

#define	QSMP_HEADER_SIZE 21
	The QSMP packet header size.

#define	QSMP_KEEPALIVE_STRING 20
	The keep alive string size.

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

#define	QSMP_KEYID_SIZE 16
	The QSMP key identity size.

#define	QSMP_MSGLEN_SIZE 4
	The size of the packet message length.

#define	QSMP_NETWORK_MTU_SIZE 1500
	The size of the packet MTU length.

#define	QSMP_NONCE_SIZE 32
	The size of the symmetric cipher nonce.

#define	QSMP_RTOK_SIZE 32
	The size of the ratchet token.

#define	QSMP_SERVER_PORT 31119
	The default server port address.

#define	QSMP_PACKET_TIME_THRESHOLD 60
	The maximum number of seconds a packet is valid Note: On interior networks with a shared (NTP) time source, this could be set at 1 second, depending on network and device traffic conditions. For exterior networks, this time needs to be adjusted to account for clock-time differences, between 30-100 seconds.

#define	QSMP_POLLING_INTERVAL (120 * 1000)
	The polling interval in milliseconds (2 minutes)

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

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

#define	QSMP_PUBKEY_LINE_LENGTH 64
	The line length of the printed QSMP public key.

#define	QSMP_SECRET_SIZE 32
	The size of the shared secret for each channel.

#define	QSMP_SEQUENCE_SIZE 8
	The size of the packet sequence number.

#define	QSMP_SEQUENCE_TERMINATOR 0xFFFFFFFFUL
	The sequence number of a packet that closes a connection.

#define	QSMP_SRVID_SIZE 8
	The QSMP server identity size.

#define	QSMP_STOKEN_SIZE 64
	The session token size.

#define	QSMP_TIMESTAMP_SIZE 8
	The key expiration timestamp size.

#define	QSMP_TIMESTAMP_STRING_SIZE 20
	The key expiration timestamp string size.

#define	QSMP_MESSAGE_MAX 0x3D090000
	The maximum message size used during the key exchange (1 GB)

#define	qsmp_cipher_generate_keypair qsc_kyber_generate_keypair
	Generate an asymmetric cipher key-pair.

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

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

#define	qsmp_signature_generate_keypair qsc_dilithium_generate_keypair
	Generate an asymmetric signature key-pair.

#define	qsmp_signature_sign qsc_dilithium_sign
	Sign a message with the asymmetric signature scheme.

#define	qsmp_signature_verify qsc_dilithium_verify
	Verify a message with the asymmetric signature scheme.

#define	QSMP_ASYMMETRIC_CIPHER_TEXT_SIZE (QSC_KYBER_CIPHERTEXT_SIZE)
	The byte size of the asymmetric cipher-text array.

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

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

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

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

#define	QSMP_ASYMMETRIC_SIGNATURE_SIZE (QSC_DILITHIUM_SIGNATURE_SIZE)
	The byte size of the asymmetric signature array.

#define	QSMP_SIGKEY_ENCODED_SIZE (QSMP_KEYID_SIZE + QSMP_TIMESTAMP_SIZE + QSMP_CONFIG_SIZE + QSMP_ASYMMETRIC_SIGNING_KEY_SIZE + QSMP_ASYMMETRIC_VERIFY_KEY_SIZE)
	The secret signature key size.

#define	QSMP_PUBKEY_HEADER_SIZE 40
	The size of the QSMP public key header.

#define	QSMP_PUBKEY_VERSION_SIZE 19
	The size of the QSMP public key version string.

#define	QSMP_PUBKEY_CONFIG_SIZE 16
	The size of the QSMP public key configuration prefix.

#define	QSMP_PUBKEY_KEYID_SIZE 10
	The size of the QSMP public key identifier prefix.

#define	QSMP_PUBKEY_EXPIRATION_SIZE 13
	The size of the QSMP public key expiration prefix.

#define	QSMP_PUBKEY_FOOTER_SIZE 38
	The size of the QSMP public key footer.

#define	QSMP_ERROR_STRING_DEPTH 29
	The depth of the QSMP error string array.

#define	QSMP_ERROR_STRING_WIDTH 128
	The width of each QSMP error string.

#define	QSMP_MESSAGE_STRING_DEPTH 22
	The depth of the QSMP message string array.

#define	QSMP_MESSAGE_STRING_WIDTH 128
	The width of each QSMP message string.

Typedefs
typedef QSMP_EXPORT_API enum qsmp_configuration	qsmp_configuration

typedef QSMP_EXPORT_API enum qsmp_messages	qsmp_messages

typedef QSMP_EXPORT_API enum qsmp_errors	qsmp_errors

typedef QSMP_EXPORT_API enum qsmp_flags	qsmp_flags

typedef QSMP_EXPORT_API enum qsmp_mode	qsmp_mode

typedef QSMP_EXPORT_API struct qsmp_asymmetric_cipher_keypair	qsmp_asymmetric_cipher_keypair

typedef QSMP_EXPORT_API struct qsmp_asymmetric_signature_keypair	qsmp_asymmetric_signature_keypair

typedef QSMP_EXPORT_API struct qsmp_network_packet	qsmp_network_packet

typedef QSMP_EXPORT_API struct qsmp_client_verification_key	qsmp_client_verification_key

typedef QSMP_EXPORT_API struct qsmp_server_signature_key	qsmp_server_signature_key

typedef QSMP_EXPORT_API struct qsmp_keep_alive_state	qsmp_keep_alive_state

typedef QSMP_EXPORT_API struct qsmp_connection_state	qsmp_connection_state

Enumerations
enum	qsmp_configuration { qsmp_configuration_none = 0x00 , qsmp_configuration_sphincs_mceliece = 0x01 , qsmp_configuration_dilithium_kyber = 0x02 , qsmp_configuration_dilithium_mceliece = 0x03 , qsmp_configuration_dilithium_ntru = 0x04 , qsmp_configuration_falcon_kyber = 0x05 , qsmp_configuration_falcon_mceliece = 0x06 , qsmp_configuration_falcon_ntru = 0x07 }
	The asymmetric cryptographic primitive configuration. More...

enum	qsmp_messages { qsmp_messages_none = 0x00 , qsmp_messages_accept_fail = 0x01 , qsmp_messages_listen_fail = 0x02 , qsmp_messages_bind_fail = 0x03 , qsmp_messages_create_fail = 0x04 , qsmp_messages_connect_success = 0x05 , qsmp_messages_receive_fail = 0x06 , qsmp_messages_allocate_fail = 0x07 , qsmp_messages_kex_fail = 0x08 , qsmp_messages_disconnect = 0x09 , qsmp_messages_disconnect_fail = 0x0A , qsmp_messages_socket_message = 0x0B , qsmp_messages_queue_empty = 0x0C , qsmp_messages_listener_fail = 0x0D , qsmp_messages_sockalloc_fail = 0x0E , qsmp_messages_decryption_fail = 0x0F , qsmp_messages_keepalive_fail = 0x10 , qsmp_messages_keepalive_timeout = 0x11 , qsmp_messages_connection_fail = 0x12 , qsmp_messages_invalid_request = 0x13 }
	The logging message enumeration. More...

enum	qsmp_errors { qsmp_error_none = 0x00 , qsmp_error_accept_fail = 0x01 , qsmp_error_authentication_failure = 0x02 , qsmp_error_bad_keep_alive = 0x03 , qsmp_error_channel_down = 0x04 , qsmp_error_connection_failure = 0x05 , qsmp_error_connect_failure = 0x06 , qsmp_error_decapsulation_failure = 0x07 , qsmp_error_decryption_failure = 0x08 , qsmp_error_establish_failure = 0x09 , qsmp_error_exchange_failure = 0x0A , qsmp_error_hash_invalid = 0x0B , qsmp_error_hosts_exceeded = 0x0C , qsmp_error_invalid_input = 0x0D , qsmp_error_invalid_request = 0x0E , qsmp_error_keepalive_expired = 0x0F , qsmp_error_keepalive_timeout = 0x10 , qsmp_error_key_expired = 0x11 , qsmp_error_key_unrecognized = 0x12 , qsmp_error_keychain_fail = 0x13 , qsmp_error_listener_fail = 0x14 , qsmp_error_memory_allocation = 0x15 , qsmp_error_message_time_invalid = 0x06 , qsmp_error_packet_unsequenced = 0x17 , qsmp_error_random_failure = 0x18 , qsmp_error_receive_failure = 0x19 , qsmp_error_transmit_failure = 0x1A , qsmp_error_unknown_protocol = 0x1B , qsmp_error_verify_failure = 0x1C }
	The QSMP error values. More...

enum	qsmp_flags { qsmp_flag_none = 0x00 , qsmp_flag_connect_request = 0x01 , qsmp_flag_connect_response = 0x02 , qsmp_flag_connection_terminate = 0x03 , qsmp_flag_encrypted_message = 0x04 , qsmp_flag_exstart_request = 0x05 , qsmp_flag_exstart_response = 0x06 , qsmp_flag_exchange_request = 0x07 , qsmp_flag_exchange_response = 0x08 , qsmp_flag_establish_request = 0x09 , qsmp_flag_establish_response = 0x0A , qsmp_flag_keep_alive_request = 0x0B , qsmp_flag_keep_alive_response = 0x0C , qsmp_flag_remote_connected = 0x0D , qsmp_flag_remote_terminated = 0x0E , qsmp_flag_session_established = 0x0F , qsmp_flag_session_establish_verify = 0x10 , qsmp_flag_unrecognized_protocol = 0x11 , qsmp_flag_asymmetric_ratchet_request = 0x12 , qsmp_flag_asymmetric_ratchet_response = 0x13 , qsmp_flag_symmetric_ratchet_request = 0x14 , qsmp_flag_transfer_request = 0x15 , qsmp_flag_error_condition = 0xFF }
	The QSMP packet flags. More...

enum	qsmp_mode { qsmp_mode_simplex = 0x00 , qsmp_mode_duplex = 0x01 }
	The QSMP mode enumeration.

Functions
QSMP_EXPORT_API void	qsmp_asymmetric_cipher_keypair_dispose (qsmp_asymmetric_cipher_keypair *keypair)
	Dispose of an asymmetric cipher keypair.

QSMP_EXPORT_API qsmp_asymmetric_cipher_keypair *	qsmp_asymmetric_cipher_keypair_initialize ()
	Initialize an asymmetric cipher keypair.

QSMP_EXPORT_API void	qsmp_asymmetric_signature_keypair_dispose (qsmp_asymmetric_signature_keypair *keypair)
	Dispose of an asymmetric signature keypair.

QSMP_EXPORT_API qsmp_asymmetric_signature_keypair *	qsmp_asymmetric_signature_keypair_initialize ()
	Initialize an asymmetric signature keypair.

QSMP_EXPORT_API void	qsmp_connection_close (qsmp_connection_state *cns, qsmp_errors err, bool notify)
	Close the network connection between hosts.

QSMP_EXPORT_API void	qsmp_connection_state_dispose (qsmp_connection_state *cns)
	Reset the connection state.

QSMP_EXPORT_API const char *	qsmp_error_to_string (qsmp_errors error)
	Return a pointer to a string description of an error code.

QSMP_EXPORT_API void	qsmp_header_create (qsmp_network_packet *packetout, qsmp_flags flag, uint64_t sequence, uint32_t msglen)
	Populate a packet header and set the creation time.

QSMP_EXPORT_API qsmp_errors	qsmp_header_validate (qsmp_connection_state cns, const qsmp_network_packet packetin, qsmp_flags kexflag, qsmp_flags pktflag, uint64_t sequence, uint32_t msglen)
	Validate a packet header and timestamp.

QSMP_EXPORT_API void	qsmp_generate_keypair (qsmp_client_verification_key pubkey, qsmp_server_signature_key prikey, const uint8_t keyid[QSMP_KEYID_SIZE])
	Generate a QSMP key-pair; generates the public and private asymmetric signature keys.

QSMP_EXPORT_API const char *	qsmp_get_error_description (qsmp_messages emsg)
	Get the error string description.

QSMP_EXPORT_API void	qsmp_log_error (qsmp_messages emsg, qsc_socket_exceptions err, const char *msg)
	Log the message, socket error, and string description.

QSMP_EXPORT_API void	qsmp_log_message (qsmp_messages emsg)
	Log a message.

QSMP_EXPORT_API void	qsmp_log_write (qsmp_messages emsg, const char *msg)
	Log a message and description.

QSMP_EXPORT_API void	qsmp_packet_clear (qsmp_network_packet *packet)
	Clear a packet's state.

QSMP_EXPORT_API qsmp_errors	qsmp_packet_decrypt (qsmp_connection_state cns, uint8_t message, size_t msglen, const qsmp_network_packet packetin)
	Decrypt a message and copy it to the message output.

QSMP_EXPORT_API qsmp_errors	qsmp_packet_encrypt (qsmp_connection_state cns, qsmp_network_packet packetout, const uint8_t *message, size_t msglen)
	Encrypt a message and build an output packet.

QSMP_EXPORT_API void	qsmp_packet_error_message (qsmp_network_packet *packet, qsmp_errors error)
	Populate a packet structure with an error message.

QSMP_EXPORT_API void	qsmp_packet_header_deserialize (const uint8_t header, qsmp_network_packet packet)
	Deserialize a byte array to a packet header.

QSMP_EXPORT_API void	qsmp_packet_header_serialize (const qsmp_network_packet packet, uint8_t header)
	Serialize a packet header to a byte array.

QSMP_EXPORT_API void	qsmp_packet_set_utc_time (qsmp_network_packet *packet)
	Sets the local UTC seconds time in the packet header.

QSMP_EXPORT_API bool	qsmp_packet_time_valid (const qsmp_network_packet *packet)
	Checks the local UTC seconds time against the packet sent time for validity within the packet time threshold.

QSMP_EXPORT_API size_t	qsmp_packet_to_stream (const qsmp_network_packet packet, uint8_t pstream)
	Serialize a packet to a byte array.

QSMP_EXPORT_API bool	qsmp_public_key_compare (const qsmp_client_verification_key a, const qsmp_client_verification_key b)
	Compares two public keys for equality.

QSMP_EXPORT_API bool	qsmp_public_key_decode (qsmp_client_verification_key pubk, const char enck, size_t enclen)
	Decode a public key string and populate a client key structure.

QSMP_EXPORT_API size_t	qsmp_public_key_encode (char enck, size_t enclen, const qsmp_client_verification_key pubk)
	Encode a public key structure and copy to a string.

QSMP_EXPORT_API size_t	qsmp_public_key_encoding_size ()
	Get the key encoding string size.

QSMP_EXPORT_API void	qsmp_signature_key_deserialize (qsmp_server_signature_key *kset, const uint8_t serk[QSMP_SIGKEY_ENCODED_SIZE])
	Decode a secret signature key structure and copy to an array.

QSMP_EXPORT_API void	qsmp_signature_key_serialize (uint8_t serk[QSMP_SIGKEY_ENCODED_SIZE], const qsmp_server_signature_key *kset)
	Encode a secret key structure and copy to a string.

QSMP_EXPORT_API void	qsmp_stream_to_packet (const uint8_t pstream, qsmp_network_packet packet)
	Deserialize a byte array to a packet.

QSMP_EXPORT_API bool	qsmp_certificate_encoding_test ()
	Test the certificate encoding and decoding functions.

Detailed Description

QSMP support header Common defined parameters and functions of the qsmp client and server implementations.

Note: These definitions determine the asymmetric protocol set used by QSMP. The individual parameter sets for each cipher and signature scheme, can be configured in the QSC libraries common.h file. For maximum security, I recommend the McElice/SPHINCS+ set. For a balance of performance and security, the Dilithium/Kyber, or Dilithium/McEliece sets are recommended.

Parameter Sets: Kyber-S1, Dilithium-S1 Kyber-S3, Dilithium-S3 Kyber-S5, Dilithium-S5 Kyber-S6, Dilithium-S5 McEliece-S1, Dilithium-S1 McEliece-S3, Dilithium-S3 McEliece-S5, Dilithium-S5 McEliece-S6, Dilithium-S5 McEliece-S7, Dilithium-S5 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)

Recommended: Kyber-S5, Dilithium-S5 Kyber-S6, Dilithium-S5 McEliece-S5, Dilithium-S5 McEliece-S5, Sphincs-S5(f,s)

The parameter sets used by QSMP are selected in the QSC library in the libraries common.h file. Settings are at library defaults, however, a true 512-bit security system can be acheived by selecting the McEliece/SPHINCS+ parameter in QSMP and setting SPHINCS+ to one of the 512-bit options in the QSC library.

Enumeration Type Documentation

◆ qsmp_configuration

enum qsmp_configuration

The asymmetric cryptographic primitive configuration.

Enumerator
qsmp_configuration_none	No configuration was specified
qsmp_configuration_sphincs_mceliece	The Sphincs+ and McEliece configuration
qsmp_configuration_dilithium_kyber	The Dilithium and Kyber configuration
qsmp_configuration_dilithium_mceliece	The Dilithium and Kyber configuration
qsmp_configuration_dilithium_ntru	The Dilithium and NTRU configuration
qsmp_configuration_falcon_kyber	The Falcon and Kyber configuration
qsmp_configuration_falcon_mceliece	The Falcon and McEliece configuration
qsmp_configuration_falcon_ntru	The Falcon and NTRU configuration

◆ qsmp_errors

enum qsmp_errors

The QSMP error values.

Enumerator
qsmp_error_none	No error was detected
qsmp_error_accept_fail	The socket accept function returned an error
qsmp_error_authentication_failure	The symmetric cipher had an authentication failure
qsmp_error_bad_keep_alive	The keep alive check failed
qsmp_error_channel_down	The communications channel has failed
qsmp_error_connection_failure	The device could not make a connection to the remote host
qsmp_error_connect_failure	The transmission failed at the KEX connection phase
qsmp_error_decapsulation_failure	The asymmetric cipher failed to decapsulate the shared secret
qsmp_error_decryption_failure	The decryption authentication has failed
qsmp_error_establish_failure	The transmission failed at the KEX establish phase
qsmp_error_exchange_failure	The transmission failed at the KEX exchange phase
qsmp_error_hash_invalid	The public-key hash is invalid
qsmp_error_hosts_exceeded	The server has run out of socket connections
qsmp_error_invalid_input	The expected input was invalid
qsmp_error_invalid_request	The packet flag was unexpected
qsmp_error_keepalive_expired	The keep alive has expired with no response
qsmp_error_keepalive_timeout	The decryption authentication has failed
qsmp_error_key_expired	The QSMP public key has expired
qsmp_error_key_unrecognized	The key identity is unrecognized
qsmp_error_keychain_fail	The ratchet operation has failed
qsmp_error_listener_fail	The listener function failed to initialize
qsmp_error_memory_allocation	The server has run out of memory
qsmp_error_message_time_invalid	The packet has valid time expired
qsmp_error_packet_unsequenced	The packet was received out of sequence
qsmp_error_random_failure	The random generator has failed
qsmp_error_receive_failure	The receiver failed at the network layer
qsmp_error_transmit_failure	The transmitter failed at the network layer
qsmp_error_unknown_protocol	The protocol string was not recognized
qsmp_error_verify_failure	The expected data could not be verified

◆ qsmp_flags

enum qsmp_flags

The QSMP packet flags.

Enumerator
qsmp_flag_none	No flag was specified
qsmp_flag_connect_request	The QSMP key-exchange client connection request flag
qsmp_flag_connect_response	The QSMP key-exchange server connection response flag
qsmp_flag_connection_terminate	The connection is to be terminated
qsmp_flag_encrypted_message	The message has been encrypted flag
qsmp_flag_exstart_request	The QSMP key-exchange client exstart request flag
qsmp_flag_exstart_response	The QSMP key-exchange server exstart response flag
qsmp_flag_exchange_request	The QSMP key-exchange client exchange request flag
qsmp_flag_exchange_response	The QSMP key-exchange server exchange response flag
qsmp_flag_establish_request	The QSMP key-exchange client establish request flag
qsmp_flag_establish_response	The QSMP key-exchange server establish response flag
qsmp_flag_keep_alive_request	The packet contains a keep alive request
qsmp_flag_keep_alive_response	The packet contains a keep alive response
qsmp_flag_remote_connected	The remote host is connected flag
qsmp_flag_remote_terminated	The remote host has terminated the connection
qsmp_flag_session_established	The exchange is in the established state
qsmp_flag_session_establish_verify	The exchange is in the established verify state
qsmp_flag_unrecognized_protocol	The protocol string is not recognized
qsmp_flag_asymmetric_ratchet_request	The host has received a asymmetric key ratchet request
qsmp_flag_asymmetric_ratchet_response	The host has received a asymmetric key ratchet request
qsmp_flag_symmetric_ratchet_request	The host has received a symmetric key ratchet request
qsmp_flag_transfer_request	Reserved - The host has received a transfer request
qsmp_flag_error_condition	The connection experienced an error

◆ qsmp_messages

enum qsmp_messages

The logging message enumeration.

Enumerator
qsmp_messages_none	No configuration was specified
qsmp_messages_accept_fail	The socket accept failed
qsmp_messages_listen_fail	The listener socket could not connect
qsmp_messages_bind_fail	The listener socket could not bind to the address
qsmp_messages_create_fail	The listener socket could not be created
qsmp_messages_connect_success	The server connected to a host
qsmp_messages_receive_fail	The socket receive function failed
qsmp_messages_allocate_fail	The server memory allocation request has failed
qsmp_messages_kex_fail	The key exchange has experienced a failure
qsmp_messages_disconnect	The server has disconnected the client
qsmp_messages_disconnect_fail	The server has disconnected the client due to an error
qsmp_messages_socket_message	The server has had a socket level error
qsmp_messages_queue_empty	The server has reached the maximum number of connections
qsmp_messages_listener_fail	The server listener socket has failed
qsmp_messages_sockalloc_fail	The server has run out of socket connections
qsmp_messages_decryption_fail	The message decryption has failed
qsmp_messages_keepalive_fail	The keepalive function has failed
qsmp_messages_keepalive_timeout	The keepalive period has been exceeded
qsmp_messages_connection_fail	The connection failed or was interrupted
qsmp_messages_invalid_request	The function received an invalid request

Function Documentation

◆ qsmp_asymmetric_cipher_keypair_dispose()

QSMP_EXPORT_API void qsmp_asymmetric_cipher_keypair_dispose ( qsmp_asymmetric_cipher_keypair * keypair )

Dispose of an asymmetric cipher keypair.

Parameters

keypair A pointer to the cipher keypair

◆ qsmp_asymmetric_cipher_keypair_initialize()

QSMP_EXPORT_API qsmp_asymmetric_cipher_keypair * qsmp_asymmetric_cipher_keypair_initialize ( )

Initialize an asymmetric cipher keypair.

Returns: Returns a pointer to an asymmetric cipher keypair

◆ qsmp_asymmetric_signature_keypair_dispose()

QSMP_EXPORT_API void qsmp_asymmetric_signature_keypair_dispose ( qsmp_asymmetric_signature_keypair * keypair )

Dispose of an asymmetric signature keypair.

Parameters

keypair A pointer to the signature keypair

◆ qsmp_asymmetric_signature_keypair_initialize()

QSMP_EXPORT_API qsmp_asymmetric_signature_keypair * qsmp_asymmetric_signature_keypair_initialize ( )

Initialize an asymmetric signature keypair.

Returns: Returns a pointer to an asymmetric signature keypair

◆ qsmp_certificate_encoding_test()

QSMP_EXPORT_API bool qsmp_certificate_encoding_test ( )

Test the certificate encoding and decoding functions.

Returns: Returns true if the encoding tests succeed

◆ qsmp_connection_close()

QSMP_EXPORT_API void qsmp_connection_close	(	qsmp_connection_state *	cns,
		qsmp_errors	err,
		bool	notify )

Close the network connection between hosts.

Parameters

cns	A pointer to the connection state structure
err	The error message
notify	Notify the remote host connection is closing

◆ qsmp_connection_state_dispose()

QSMP_EXPORT_API void qsmp_connection_state_dispose ( qsmp_connection_state * cns )

Reset the connection state.

Parameters

cns	A pointer to the connection state structure

◆ qsmp_error_to_string()

QSMP_EXPORT_API const char * qsmp_error_to_string ( qsmp_errors error )

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

Parameters

error The error type

Returns: Returns a pointer to an error string or NULL

◆ qsmp_generate_keypair()

QSMP_EXPORT_API void qsmp_generate_keypair	(	qsmp_client_verification_key *	pubkey,
		qsmp_server_signature_key *	prikey,
		const uint8_t	keyid[QSMP_KEYID_SIZE] )

Generate a QSMP key-pair; generates the public and private asymmetric signature keys.

Parameters

pubkey	The public key, distributed to clients
prikey	The private key, a secret key known only by the server
keyid	[const] The key identity string

◆ qsmp_get_error_description()

QSMP_EXPORT_API const char * qsmp_get_error_description ( qsmp_messages emsg )

Get the error string description.

Parameters

emsg	The message enumeration

Returns: Returns a pointer to the message string or NULL

◆ qsmp_header_create()

QSMP_EXPORT_API void qsmp_header_create	(	qsmp_network_packet *	packetout,
		qsmp_flags	flag,
		uint64_t	sequence,
		uint32_t	msglen )

Populate a packet header and set the creation time.

Parameters

packetout	A pointer to the output packet structure
flag	The packet flag
sequence	The packet sequence number
msglen	The length of the message array

◆ qsmp_header_validate()

QSMP_EXPORT_API qsmp_errors qsmp_header_validate	(	qsmp_connection_state *	cns,
		const qsmp_network_packet *	packetin,
		qsmp_flags	kexflag,
		qsmp_flags	pktflag,
		uint64_t	sequence,
		uint32_t	msglen )

Validate a packet header and timestamp.

Parameters

cns	A pointer to the connection state structure
packetin	A pointer to the input packet structure
kexflag	The packet flag
pktflag	The packet flag
sequence	The packet sequence number
msglen	The length of the message array

Returns: : Returns the function error state

◆ qsmp_log_error()

QSMP_EXPORT_API void qsmp_log_error	(	qsmp_messages	emsg,
		qsc_socket_exceptions	err,
		const char *	msg )

Log the message, socket error, and string description.

Parameters

emsg	The message enumeration
err	The socket exception enumeration
msg	[const] The message string

◆ qsmp_log_message()

QSMP_EXPORT_API void qsmp_log_message ( qsmp_messages emsg )

Log a message.

Parameters

emsg	The message enumeration

◆ qsmp_log_write()

QSMP_EXPORT_API void qsmp_log_write	(	qsmp_messages	emsg,
		const char *	msg )

Log a message and description.

Parameters

emsg	The message enumeration
msg	[const] The message string

◆ qsmp_packet_clear()

QSMP_EXPORT_API void qsmp_packet_clear ( qsmp_network_packet * packet )

Clear a packet's state.

Parameters

packet A pointer to the packet structure

◆ qsmp_packet_decrypt()

QSMP_EXPORT_API qsmp_errors qsmp_packet_decrypt	(	qsmp_connection_state *	cns,
		uint8_t *	message,
		size_t *	msglen,
		const qsmp_network_packet *	packetin )

Decrypt a message and copy it to the message output.

Parameters

cns	A pointer to the connection state structure
message	The message output array
msglen	A pointer receiving the message length
packetin	[const] A pointer to the input packet structure

Returns: : Returns the function error state

◆ qsmp_packet_encrypt()

QSMP_EXPORT_API qsmp_errors qsmp_packet_encrypt	(	qsmp_connection_state *	cns,
		qsmp_network_packet *	packetout,
		const uint8_t *	message,
		size_t	msglen )

Encrypt a message and build an output packet.

Parameters

cns	A pointer to the connection state structure
packetout	A pointer to the output packet structure
message	[const] The input message array
msglen	The length of the message array

Returns: : Returns the function error state

◆ qsmp_packet_error_message()

QSMP_EXPORT_API void qsmp_packet_error_message	(	qsmp_network_packet *	packet,
		qsmp_errors	error )

Populate a packet structure with an error message.

Parameters

packet	A pointer to the packet structure
error	The error type

◆ qsmp_packet_header_deserialize()

QSMP_EXPORT_API void qsmp_packet_header_deserialize	(	const uint8_t *	header,
		qsmp_network_packet *	packet )

Deserialize a byte array to a packet header.

Parameters

packet	[const] The header byte array to deserialize
header	A pointer to the packet structure

◆ qsmp_packet_header_serialize()

QSMP_EXPORT_API void qsmp_packet_header_serialize	(	const qsmp_network_packet *	packet,
		uint8_t *	header )

Serialize a packet header to a byte array.

Parameters

packet	[const] A pointer to the packet structure to serialize
header	The header byte array

◆ qsmp_packet_set_utc_time()

QSMP_EXPORT_API void qsmp_packet_set_utc_time ( qsmp_network_packet * packet )

Sets the local UTC seconds time in the packet header.

Parameters

packet A pointer to a network packet

◆ qsmp_packet_time_valid()

QSMP_EXPORT_API bool qsmp_packet_time_valid ( const qsmp_network_packet * packet )

Checks the local UTC seconds time against the packet sent time for validity within the packet time threshold.

Parameters

packet [const] A pointer to a network packet

Returns: Returns true if the packet was received within the valid-time threhold

◆ qsmp_packet_to_stream()

QSMP_EXPORT_API size_t qsmp_packet_to_stream	(	const qsmp_network_packet *	packet,
		uint8_t *	pstream )

Serialize a packet to a byte array.

Parameters

packet	[const] The header byte array to deserialize
pstream	A pointer to the packet structure

Returns: Returns the size of the byte stream

◆ qsmp_public_key_compare()

QSMP_EXPORT_API bool qsmp_public_key_compare	(	const qsmp_client_verification_key *	a,
		const qsmp_client_verification_key *	b )

Compares two public keys for equality.

Parameters

a	[const] The first public key
b	[const] The second public key

Returns: Returns true if the certificates are identical

◆ qsmp_public_key_decode()

QSMP_EXPORT_API bool qsmp_public_key_decode	(	qsmp_client_verification_key *	pubk,
		const char *	enck,
		size_t	enclen )

Decode a public key string and populate a client key structure.

Parameters

pubk	A pointer to the output client key
enck	[const] The input encoded key

Returns: : Returns true for success

◆ qsmp_public_key_encode()

QSMP_EXPORT_API size_t qsmp_public_key_encode	(	char *	enck,
		size_t	enclen,
		const qsmp_client_verification_key *	pubk )

Encode a public key structure and copy to a string.

Parameters

enck	The output encoded public key string
enclen	The length of the encoding array
pubk	[const] A pointer to the public key structure

Returns: : Returns the encoded string length

◆ qsmp_public_key_encoding_size()

QSMP_EXPORT_API size_t qsmp_public_key_encoding_size ( )

Get the key encoding string size.

Returns: Returns the size of the encoded string

◆ qsmp_signature_key_deserialize()

QSMP_EXPORT_API void qsmp_signature_key_deserialize	(	qsmp_server_signature_key *	kset,
		const uint8_t	serk[QSMP_SIGKEY_ENCODED_SIZE] )

Decode a secret signature key structure and copy to an array.

Parameters

kset	A pointer to the output server key structure
serk	[const] The input encoded secret key string

◆ qsmp_signature_key_serialize()

QSMP_EXPORT_API void qsmp_signature_key_serialize	(	uint8_t	serk[QSMP_SIGKEY_ENCODED_SIZE],
		const qsmp_server_signature_key *	kset )

Encode a secret key structure and copy to a string.

Parameters

serk	The output encoded public key string
kset	[const] A pointer to the secret server key structure

◆ qsmp_stream_to_packet()

QSMP_EXPORT_API void qsmp_stream_to_packet	(	const uint8_t *	pstream,
		qsmp_network_packet *	packet )

Deserialize a byte array to a packet.

Parameters

pstream	[const] The header byte array to deserialize
packet	A pointer to the packet structure

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ qsmp_configuration

◆ qsmp_errors

◆ qsmp_flags

◆ qsmp_messages

Function Documentation

◆ qsmp_asymmetric_cipher_keypair_dispose()

◆ qsmp_asymmetric_cipher_keypair_initialize()

◆ qsmp_asymmetric_signature_keypair_dispose()

◆ qsmp_asymmetric_signature_keypair_initialize()

◆ qsmp_certificate_encoding_test()

◆ qsmp_connection_close()

◆ qsmp_connection_state_dispose()

◆ qsmp_error_to_string()

◆ qsmp_generate_keypair()

◆ qsmp_get_error_description()

◆ qsmp_header_create()

◆ qsmp_header_validate()

◆ qsmp_log_error()

◆ qsmp_log_message()

◆ qsmp_log_write()

◆ qsmp_packet_clear()

◆ qsmp_packet_decrypt()

◆ qsmp_packet_encrypt()

◆ qsmp_packet_error_message()

◆ qsmp_packet_header_deserialize()

◆ qsmp_packet_header_serialize()

◆ qsmp_packet_set_utc_time()

◆ qsmp_packet_time_valid()

◆ qsmp_packet_to_stream()

◆ qsmp_public_key_compare()

◆ qsmp_public_key_decode()

◆ qsmp_public_key_encode()

◆ qsmp_public_key_encoding_size()

◆ qsmp_signature_key_deserialize()

◆ qsmp_signature_key_serialize()

◆ qsmp_stream_to_packet()