pqs.h

Go to the documentation of this file.

/* 2025 Quantum Resistant Cryptographic Solutions Corporation
 * All Rights Reserved.
 *
 * NOTICE: This software and all accompanying materials are the exclusive 
 * property of Quantum Resistant Cryptographic Solutions Corporation (QRCS).
 * The intellectual and technical concepts contained within this implementation 
 * are proprietary to QRCS and its authorized licensors and are protected under 
 * applicable U.S. and international copyright, patent, and trade secret laws.
 *
 * CRYPTOGRAPHIC STANDARDS:
 * - This software includes implementations of cryptographic algorithms such as 
 *   SHA3, AES, and others. These algorithms are public domain or standardized 
 *   by organizations such as NIST and are NOT the property of QRCS.
 * - However, all source code, optimizations, and implementations in this library 
 *   are original works of QRCS and are protected under this license.
 *
 * RESTRICTIONS:
 * - Redistribution, modification, or unauthorized distribution of this software, 
 *   in whole or in part, is strictly prohibited.
 * - This software is provided for non-commercial, educational, and research 
 *   purposes only. Commercial use in any form is expressly forbidden.
 * - Licensing and authorized distribution are solely at the discretion of QRCS.
 * - Any use of this software implies acceptance of these restrictions.
 *
 * DISCLAIMER:
 * This software is provided "as is," without warranty of any kind, express or 
 * implied, including but not limited to warranties of merchantability or fitness 
 * for a particular purpose. QRCS disclaims all liability for any direct, indirect, 
 * incidental, or consequential damages resulting from the use or misuse of this software.
 *
 * FULL LICENSE:
 * This software is subject to the **Quantum Resistant Cryptographic Solutions 
 * Proprietary License (QRCS-PL)**. The complete license terms are included 
 * in the LICENSE.txt file distributed with this software.
 *
 * Written by: John G. Underhill
 * Contact: john.underhill@protonmail.com
 */
 
#ifndef PQS_H
#define PQS_H
 
#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"

 
/*=============================================================================
                              Macros and Constants
=============================================================================*/

#define PQS_CONFIG_SIZE 48

#if defined(QSC_DILITHIUM_S1P2544)
#   if defined(QSC_KYBER_S1P1632)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s1_kyber-s1_sha3_rcs";
#   elif defined(QSC_KYBER_S3P2400)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s1_kyber-s3_sha3_rcs";
#   elif defined(QSC_KYBER_S5P3168)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s1_kyber-s5_sha3_rcs";
#   elif defined(QSC_KYBER_S6P3936)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s1_kyber-s6_sha3_rcs";
#   else
#       error Invalid parameter set!
#   endif
#elif defined(QSC_DILITHIUM_S3P4016)
#   if defined(QSC_KYBER_S1P1632)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s3_kyber-s1_sha3_rcs";
#   elif defined(QSC_KYBER_S3P2400)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s3_kyber-s3_sha3_rcs";
#   elif defined(QSC_KYBER_S5P3168)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s3_kyber-s5_sha3_rcs";
#   elif defined(QSC_KYBER_S6P3936)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s3_kyber-s6_sha3_rcs";
#   else
#       error Invalid parameter set!
#   endif
#elif defined(QSC_DILITHIUM_S5P4880)
#   if defined(QSC_KYBER_S1P1632)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s5_kyber-s1_sha3_rcs";
#   elif defined(QSC_KYBER_S3P2400)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s5_kyber-s3_sha3_rcs";
#   elif defined(QSC_KYBER_S5P3168)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s5_kyber-s5_sha3_rcs";
#   elif defined(QSC_KYBER_S6P3936)
static const char PQS_CONFIG_STRING[PQS_CONFIG_SIZE] = "dilithium-s5_kyber-s6_sha3_rcs";
#   else
#       error Invalid parameter set!
#   endif
#else
#   error Invalid parameter set!
#endif

#define PQS_ASYMMETRIC_CIPHER_TEXT_SIZE (QSC_KYBER_CIPHERTEXT_SIZE)

#define PQS_ASYMMETRIC_PRIVATE_KEY_SIZE (QSC_KYBER_PRIVATEKEY_SIZE)

#define PQS_ASYMMETRIC_PUBLIC_KEY_SIZE (QSC_KYBER_PUBLICKEY_SIZE)

#define PQS_ASYMMETRIC_SIGNING_KEY_SIZE (QSC_DILITHIUM_PRIVATEKEY_SIZE)

#define PQS_ASYMMETRIC_VERIFY_KEY_SIZE (QSC_DILITHIUM_PUBLICKEY_SIZE)

#define PQS_ASYMMETRIC_SIGNATURE_SIZE (QSC_DILITHIUM_SIGNATURE_SIZE)

#if defined(QSC_DILITHIUM_S1P2544)
#   define PQS_PUBKEY_ENCODING_SIZE 1752
#elif defined(QSC_DILITHIUM_S3P4016)
#   define PQS_PUBKEY_ENCODING_SIZE 2604
#elif defined(QSC_DILITHIUM_S5P4880)
#   define PQS_PUBKEY_ENCODING_SIZE 3456
#else
#   error invalid dilithium parameter!
#endif

#if defined(QSC_DILITHIUM_S1P2544)
#   define PQS_PUBKEY_STRING_SIZE 2014
#elif defined(QSC_DILITHIUM_S3P4016)
#   define PQS_PUBKEY_STRING_SIZE 2879
#elif defined(QSC_DILITHIUM_S5P4880)
#   define PQS_PUBKEY_STRING_SIZE 3745
#else
#   error invalid dilithium parameter!
#endif

#define PQS_CLIENT_PORT 33118

#define PQS_CONNECTIONS_INIT 1000

#define PQS_CONNECTIONS_MAX 50000

#define PQS_CONNECTION_MTU 1500

#define PQS_ERROR_SEQUENCE 0xFF00000000000000ULL

#define PQS_ERROR_MESSAGE_SIZE 1

#define PQS_FLAG_SIZE 1

#define PQS_HASH_SIZE 32

#define PQS_HEADER_SIZE 21

#define PQS_KEEPALIVE_TIMEOUT (120 * 1000)

#define PQS_KEYID_SIZE 16

#define PQS_MACTAG_SIZE 32

#define PQS_MESSAGE_MAX 0x3D090000

#define PQS_MSGLEN_SIZE 4

#define PQS_NONCE_SIZE 32

#define PQS_NETWORK_BUFFER_SIZE 1280

#define PQS_PACKET_TIME_THRESHOLD 60

#define PQS_PUBKEY_DURATION_DAYS 365

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

#define PQS_PUBKEY_LINE_LENGTH 64

#define PQS_SCHASH_SIZE 32

#define PQS_SECRET_SIZE 32

#define PQS_SEQUENCE_SIZE 8

#define PQS_SEQUENCE_TERMINATOR 0xFFFFFFFFUL

#define PQS_SERVER_LISTEN_BACKLOG 0

#define PQS_SERVER_PORT 3119

#define PQS_SYMMETRIC_KEY_SIZE 32

#define PQS_TIMESTAMP_SIZE 8

#define PQS_SIGKEY_ENCODED_SIZE (PQS_KEYID_SIZE + PQS_TIMESTAMP_SIZE + PQS_CONFIG_SIZE + \
    PQS_HASH_SIZE + PQS_ASYMMETRIC_SIGNING_KEY_SIZE + PQS_ASYMMETRIC_VERIFY_KEY_SIZE)
 
/*----------------------------------------------------------------------------
   PQS algorithm function aliases
   These macros provide aliases to the underlying QSC library functions.
-----------------------------------------------------------------------------*/
#define pqs_cipher_generate_keypair qsc_kyber_generate_keypair
#define pqs_cipher_decapsulate qsc_kyber_decapsulate
#define pqs_cipher_encapsulate qsc_kyber_encapsulate
#define pqs_signature_generate_keypair qsc_dilithium_generate_keypair
#define pqs_signature_sign qsc_dilithium_sign
#define pqs_signature_verify qsc_dilithium_verify
 
/*----------------------------------------------------------------------------
   Public key encoding constants
   These constants are used to format the textual representation of the PQS public key.
-----------------------------------------------------------------------------*/
static const char PQS_PUBKEY_HEADER[] = "------BEGIN PQS PUBLIC KEY BLOCK------";
static const char PQS_PUBKEY_VERSION[] = "Version: PQS v1.0";
static const char PQS_PUBKEY_CONFIG_PREFIX[] = "Configuration: ";
static const char PQS_PUBKEY_KEYID_PREFIX[] = "Host ID: ";
static const char PQS_PUBKEY_EXPIRATION_PREFIX[] = "Expiration: ";
static const char PQS_PUBKEY_FOOTER[] = "------END PQS PUBLIC KEY BLOCK------";

#define PQS_ERROR_STRING_DEPTH 32
#define PQS_ERROR_STRING_WIDTH 128
#define PQS_MESSAGE_STRING_DEPTH 21
#define PQS_MESSAGE_STRING_WIDTH 128

static const char PQS_MESSAGE_STRINGS[PQS_ERROR_STRING_DEPTH][PQS_ERROR_STRING_WIDTH] =
{
    "The operation completed succesfully.",
    "The socket server accept function failed.",
    "The listener socket listener could not connect.",
    "The listener socket could not bind to the address.",
    "The listener socket could not be created.",
    "The server is connected to remote host - ",
    "The socket receive function failed - ",
    "The server had a memory allocation failure.",
    "The key exchange has experienced a failure.",
    "The server has disconnected from the remote host - ",
    "The server has disconnected the client due to an error - ",
    "The server has had a socket level error.",
    "The server has reached the maximum number of connections",
    "The server listener socket has failed.",
    "The server has run out of socket connections",
    "The message decryption has failed - ",
    "The keepalive function has failed - ",
    "The keepalive period has been exceeded",
    "The connection failed or was interrupted - ",
    "The function received an invalid request - ",
    "The remote host is busy and refused the connection - "
};
 
static const char PQS_ERROR_STRINGS[PQS_ERROR_STRING_DEPTH][PQS_ERROR_STRING_WIDTH] =
{
    "No error was detected",
    "The socket accept function returned an error",
    "The symmetric cipher had an authentication failure",
    "The keep alive check failed",
    "The communications channel has failed",
    "The device could not make a connection to the remote host",
    "The transmission failed at the KEX connection phase",
    "The asymmetric cipher failed to decapsulate the shared secret",
    "The decryption authentication has failed",
    "The transmission failed at the KEX establish phase",
    "The transmission failed at the KEX exchange phase",
    "The public - key hash is invalid",
    "The server has run out of socket connections",
    "The expected input was invalid",
    "The packet flag was unexpected",
    "The keep alive has expired with no response",
    "The decryption authentication has failed",
    "The PQS public key has expired ",
    "The key identity is unrecognized",
    "The ratchet operation has failed",
    "The listener function failed to initialize",
    "The server has run out of memory",
    "The packet was received out of sequence",
    "The random generator has failed",
    "The receiver failed at the network layer",
    "The transmitter failed at the network layer",
    "The protocol string was not recognized",
    "The expected data could not be verified",
    "The client received an authentication failure response",
    "The client received an authentication success response",
    "The packet valid time has expired",
    "The connection was refused by the remote server"
};
 
/*=============================================================================
                              Enumerations
=============================================================================*/

PQS_EXPORT_API typedef enum pqs_client_commands
{
    pqs_client_command_none = 0x00,         
    pqs_client_command_cprint = 0x01,       
    pqs_client_command_execute = 0x02,      
    pqs_client_command_quit = 0x03,         
} pqs_client_commands;

PQS_EXPORT_API typedef 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,    
} pqs_errors;

PQS_EXPORT_API typedef 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,                
} pqs_flags;

PQS_EXPORT_API typedef 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, 
} pqs_messages;
 
/*=============================================================================
                              Structures
=============================================================================*/

PQS_EXPORT_API typedef struct pqs_asymmetric_cipher_keypair
{
    uint8_t prikey[PQS_ASYMMETRIC_PRIVATE_KEY_SIZE];  
    uint8_t pubkey[PQS_ASYMMETRIC_PUBLIC_KEY_SIZE];     
} pqs_asymmetric_cipher_keypair;

PQS_EXPORT_API typedef struct pqs_asymmetric_signature_keypair
{
    uint8_t sigkey[PQS_ASYMMETRIC_SIGNING_KEY_SIZE];    
    uint8_t verkey[PQS_ASYMMETRIC_VERIFY_KEY_SIZE];       
} pqs_asymmetric_signature_keypair;

PQS_EXPORT_API typedef struct pqs_network_packet
{
    uint8_t flag;         
    uint32_t msglen;      
    uint64_t sequence;    
    uint64_t utctime;     
    uint8_t* pmessage;    
} pqs_network_packet;

PQS_EXPORT_API typedef struct pqs_client_verification_key
{
    uint64_t expiration;                           
    uint8_t config[PQS_CONFIG_SIZE];               
    uint8_t keyid[PQS_KEYID_SIZE];                 
    uint8_t verkey[PQS_ASYMMETRIC_VERIFY_KEY_SIZE];  
} pqs_client_verification_key;

PQS_EXPORT_API typedef struct pqs_server_signature_key
{
    uint64_t expiration;                             
    uint8_t config[PQS_CONFIG_SIZE];                 
    uint8_t keyid[PQS_KEYID_SIZE];                   
    uint8_t sigkey[PQS_ASYMMETRIC_SIGNING_KEY_SIZE];   
    uint8_t verkey[PQS_ASYMMETRIC_VERIFY_KEY_SIZE];    
    uint8_t rkhash[PQS_HASH_SIZE];                   
} pqs_server_signature_key;

PQS_EXPORT_API typedef struct pqs_keep_alive_state
{
    qsc_socket target;  
    uint64_t etime;     
    uint64_t seqctr;    
    bool recd;          
} pqs_keep_alive_state;

PQS_EXPORT_API typedef struct pqs_connection_state
{
    qsc_socket target;       
    qsc_rcs_state rxcpr;     
    qsc_rcs_state txcpr;     
    uint64_t rxseq;          
    uint64_t txseq;          
    uint32_t cid;            
    pqs_flags exflag;        
    bool receiver;           
} pqs_connection_state;
 
/*=============================================================================
                              Function Prototypes
=============================================================================*/

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

PQS_EXPORT_API void pqs_connection_state_dispose(pqs_connection_state* cns);

PQS_EXPORT_API const char* pqs_error_description(pqs_messages emsg);

PQS_EXPORT_API const char* pqs_error_to_string(pqs_errors error);

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

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

PQS_EXPORT_API void pqs_log_message(pqs_messages emsg);

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

PQS_EXPORT_API void pqs_packet_clear(pqs_network_packet* packet);

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

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

PQS_EXPORT_API void pqs_packet_error_message(pqs_network_packet* packet, pqs_errors error);

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

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

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

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);

PQS_EXPORT_API void pqs_packet_time_set(pqs_network_packet* packet);

PQS_EXPORT_API bool pqs_packet_time_validate(const pqs_network_packet* packet);

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

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

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

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

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

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

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