satp.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: contact@qrcscorp.ca
 */
 
#ifndef SATP_H
#define SATP_H
 
#include "satpcommon.h"
#include "sha3.h"
#include "socket.h"
#include "socketclient.h"


#define SATP_USE_RCS_ENCRYPTION
 
#if defined(SATP_USE_RCS_ENCRYPTION)
#   include "rcs.h"
#   define satp_cipher_state qsc_rcs_state
#   define satp_cipher_dispose qsc_rcs_dispose
#   define satp_cipher_initialize qsc_rcs_initialize
#   define satp_cipher_keyparams qsc_rcs_keyparams
#   define satp_cipher_set_associated qsc_rcs_set_associated
#   define satp_cipher_transform qsc_rcs_transform
#else
#   include "aes.h"
#   define satp_cipher_state qsc_aes_gcm256_state
#   define satp_cipher_dispose qsc_aes_gcm256_dispose
#   define satp_cipher_initialize qsc_aes_gcm256_initialize
#   define satp_cipher_keyparams qsc_aes_keyparams
#   define satp_cipher_set_associated qsc_aes_gcm256_set_associated
#   define satp_cipher_transform qsc_aes_gcm256_transform
#endif


#define SATP_CLIENT_PASSWORD_MAX 256U

#define SATP_CLIENT_USERNAME_MAX 256U

#define SATP_CONNECTIONS_INIT 1000U

#define SATP_CONNECTIONS_MAX 50000U

#define SATP_CONFIG_SIZE 25U

#define SATP_ERROR_SIZE 1U

#define SATP_EXPIRATION_SIZE 8U

#define SATP_HASH_SIZE 32U

#define SATP_HEADER_SIZE 21U

#define SATP_KEEPALIVE_MESSAGE 8U

#define SATP_KEEPALIVE_STRING 20U

#define SATP_KEEPALIVE_TIMEOUT (300U * 1000U)

#define SATP_KEY_TREE_COUNT 1024

#if defined(SATP_USE_RCS_ENCRYPTION)
#   define SATP_MACTAG_SIZE 32U
#else
#   define SATP_MACTAG_SIZE 16U
#endif

#define SATP_MESSAGE_SIZE 1024U

#define SATP_MESSAGE_MAX (SATP_MESSAGE_SIZE + SATP_HEADER_SIZE)

#define SATP_CONNECTION_MTU 1500U

#if defined(SATP_USE_RCS_ENCRYPTION)
#   define SATP_NONCE_SIZE 32U
#else
#   define SATP_NONCE_SIZE 16U
#endif

#define SATP_SALT_SIZE 32U

#define SATP_SERVER_PORT 2701U

#define SATP_SEQUENCE_TERMINATOR 0xFFFFFFFFUL

#if defined(SATP_USE_RCS_ENCRYPTION)
    static const char SATP_CONFIG_STRING[SATP_CONFIG_SIZE + 1U] = "r01-satp-rcs256-keccak256";
#else
    static const char SATP_CONFIG_STRING[SATP_CONFIG_SIZE + 1U] = "r02-satp-aes256-keccak256";
#endif
 
/* Exchange thresholds */

#define SATP_KEY_DURATION_DAYS 365U

#define SATP_PACKET_TIME_THRESHOLD 60U

#define SATP_KEY_DURATION_SECONDS (SATP_KEY_DURATION_DAYS * 24U * 60U * 60U)
 
/* Key identity elements */

#define SATP_BRANCH_ID_SIZE 2U

#define SATP_DOMAIN_ID_SIZE 2U

#define SATP_DEVICE_ID_SIZE 4U

#define SATP_EPOCH_SIZE 2U

#define SATP_ERROR_MESSAGE_SIZE 1U

#define SATP_ERROR_SEQUENCE 0xFF00000000000000ULL

#define SATP_FLAG_SIZE 1

#define SATP_KEY_ID_SIZE 4U

#define SATP_SERVICE_ID_SIZE 2U

#define SATP_DID_SIZE (SATP_DOMAIN_ID_SIZE + SATP_BRANCH_ID_SIZE + SATP_EPOCH_SIZE + SATP_SERVICE_ID_SIZE + SATP_DEVICE_ID_SIZE)

#define SATP_MID_SIZE (SATP_DOMAIN_ID_SIZE)

#define SATP_SID_SIZE (SATP_DOMAIN_ID_SIZE + SATP_BRANCH_ID_SIZE)

#define SATP_KID_SIZE (SATP_DID_SIZE + SATP_KEY_ID_SIZE)
 
/* key sizes */

#define SATP_DKEY_SIZE 32U

#define SATP_MKEY_SIZE 32U

#define SATP_SKEY_SIZE 32U

#define SATP_KTREE_SIZE (SATP_DKEY_SIZE * SATP_KEY_TREE_COUNT)

#define SATP_DKEY_ENCODED_SIZE (SATP_KID_SIZE + SATP_SKEY_SIZE + SATP_EXPIRATION_SIZE + (SATP_DKEY_SIZE * SATP_KEY_TREE_COUNT))

#define SATP_MKEY_ENCODED_SIZE (SATP_MKEY_SIZE + SATP_MID_SIZE + SATP_EXPIRATION_SIZE)

#define SATP_SKEY_ENCODED_SIZE (SATP_SKEY_SIZE + SATP_SKEY_SIZE + SATP_SID_SIZE + SATP_EXPIRATION_SIZE)

#define SATP_STOK_SIZE 32U
 
/* error code strings */

#define SATP_ERROR_STRING_DEPTH 22U
#define SATP_ERROR_STRING_WIDTH 128U
 
static const char SATP_ERROR_STRINGS[SATP_ERROR_STRING_DEPTH][SATP_ERROR_STRING_WIDTH] =
{
    "No error was detected",
    "The keep alive check failed",
    "The cipher authentication has failed",
    "The communications channel has failed",
    "The device could not make a connection to the remote host",
    "The decryption authentication has failed",
    "The device identity is unrecognized",
    "The transmission failed at the key exchange establish phase",
    "The input provided is invalid",
    "The keep alive has expired with no response",
    "The key exchange authentication has failed",
    "The SATP public key has expired",
    "The key identity is not recognized",
    "The packet keep alive is invalid",
    "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 packets sequence number is out of sync",
    "The expected data could not be verified",
    "A general failure occurred",
};

SATP_EXPORT_API typedef enum satp_errors
{
    satp_error_none = 0x00U,                 
    satp_error_accept_fail = 0x01,                
    satp_error_authentication_failure = 0x02U, 
    satp_error_authentication_success = 0x03U, 
    satp_erroe_listen_fail = 0x04U,               
    satp_error_allocation_failure = 0x05U,     
    satp_error_bad_keep_alive = 0x06U,         
    satp_error_cipher_auth_failure = 0x07U,       
    satp_error_channel_down = 0x08U,         
    satp_error_connection_failure = 0x09U,     
    satp_error_decryption_failure = 0x0AU,     
    satp_error_device_unrecognized = 0x0BU,       
    satp_error_establish_failure = 0x0CU,       
    satp_error_hosts_exceeded = 0x0DU,         
    satp_error_invalid_input = 0x0EU,           
    satp_error_invalid_request = 0x0FU,           
    satp_error_keep_alive_expired = 0x10U,     
    satp_error_kex_auth_failure = 0x11U,     
    satp_error_key_expired = 0x12U,               
    satp_error_key_not_recognized = 0x13U,     
    satp_error_listener_fail = 0x14U,           
    satp_error_message_time_invalid = 0x15U, 
    satp_error_packet_expired = 0x16U,         
    satp_error_packet_unsequenced = 0x17U,     
    satp_error_random_failure = 0x18U,         
    satp_error_receive_failure = 0x19U,           
    satp_error_transmit_failure = 0x1AU,     
    satp_error_unknown_protocol = 0x1BU,     
    satp_error_unsequenced = 0x1CU,               
    satp_error_verify_failure = 0x1DU,         
    satp_error_general_failure = 0xFFU            
} satp_errors;

SATP_EXPORT_API typedef enum satp_flags
{
    satp_flag_none = 0x00U,                       
    satp_flag_connect_request = 0x01U,         
    satp_flag_connect_response = 0x02U,           
    satp_flag_connection_terminate = 0x03U,       
    satp_flag_encrypted_message = 0x04U,     
    satp_flag_authentication_request = 0x05U,   
    satp_flag_authentication_response = 0x06U, 
    satp_flag_auth_verify = 0x08U,             
    satp_flag_keepalive_request = 0x09U,     
    satp_flag_session_established = 0x0AU,     
    satp_flag_error_condition = 0xFFU,         
} satp_flags;

SATP_EXPORT_API typedef struct satp_connection_state
{
    qsc_socket target;                            
    qsc_rcs_state rxcpr;                       
    qsc_rcs_state txcpr;                       
    uint64_t rxseq;                                
    uint64_t txseq;                                
    uint32_t cid;                                
    satp_flags exflag;                          
    bool receiver;                              
} satp_connection_state;

SATP_EXPORT_API typedef struct satp_device_key
{
    QSC_SIMD_ALIGN uint8_t ktree[SATP_DKEY_SIZE * SATP_KEY_TREE_COUNT];   
    QSC_SIMD_ALIGN uint8_t kid[SATP_KID_SIZE];  
    QSC_SIMD_ALIGN uint8_t stc[SATP_SKEY_SIZE]; 
    uint64_t expiration;                      
    uint8_t* spass;                                
} satp_device_key;

SATP_EXPORT_API typedef struct satp_master_key
{
    QSC_SIMD_ALIGN uint8_t mdk[SATP_MKEY_SIZE];    
    QSC_SIMD_ALIGN uint8_t mid[SATP_MID_SIZE];  
    uint64_t expiration;                      
} satp_master_key;

SATP_EXPORT_API typedef struct satp_server_key
{
    QSC_SIMD_ALIGN uint8_t sdk[SATP_SKEY_SIZE]; 
    QSC_SIMD_ALIGN uint8_t sid[SATP_SID_SIZE];  
    QSC_SIMD_ALIGN uint8_t stc[SATP_SKEY_SIZE]; 
    uint64_t expiration;                      
} satp_server_key;

SATP_EXPORT_API typedef struct qsmp_keep_alive_state
{
    uint64_t etime;                                
    uint64_t seqctr;                          
    bool recd;                                  
} satp_keep_alive_state;

SATP_EXPORT_API typedef struct satp_network_packet
{
    uint8_t flag;                               
    uint32_t msglen;                          
    uint64_t sequence;                          
    uint64_t utctime;                            
    uint8_t* pmessage;                          
} satp_network_packet;

SATP_EXPORT_API void satp_connection_close(satp_connection_state* cns, satp_errors err, bool notify);

SATP_EXPORT_API void satp_connection_dispose(satp_connection_state* cns);

SATP_EXPORT_API satp_errors satp_decrypt_error_message(satp_connection_state* cns, uint8_t* message);

SATP_EXPORT_API satp_errors satp_decrypt_packet(satp_connection_state* cns, const satp_network_packet* packetin, uint8_t* message, size_t* msglen);

SATP_EXPORT_API satp_errors satp_encrypt_packet(satp_connection_state* cns, const uint8_t* message, size_t msglen, satp_network_packet* packetout);

SATP_EXPORT_API void satp_deserialize_device_key(satp_device_key* dkey, const uint8_t* input);

SATP_EXPORT_API void satp_serialize_device_key(uint8_t* output, const satp_device_key* dkey);

SATP_EXPORT_API const char* satp_error_to_string(satp_errors error);

SATP_EXPORT_API bool satp_extract_device_key(uint8_t* dk, const uint8_t* sk, const uint8_t* kid);

SATP_EXPORT_API void satp_packet_error_message(satp_network_packet* packet, satp_errors error);

SATP_EXPORT_API void satp_deserialize_master_key(satp_master_key* mkey, const uint8_t* input);

SATP_EXPORT_API void satp_serialize_master_key(uint8_t* output, const satp_master_key* mkey);

SATP_EXPORT_API void satp_deserialize_server_key(satp_server_key* skey, const uint8_t* input);

SATP_EXPORT_API void satp_serialize_server_key(uint8_t* output, const satp_server_key* skey);

SATP_EXPORT_API void satp_increment_device_key(uint8_t* sdkey);

SATP_EXPORT_API bool satp_generate_master_key(satp_master_key* mkey, const uint8_t* mid);

SATP_EXPORT_API bool satp_generate_server_key(satp_server_key* skey, const satp_master_key* mkey, const uint8_t* sid);

SATP_EXPORT_API void satp_generate_device_key(satp_device_key* dkey, const satp_server_key* skey, const uint8_t* did);

SATP_EXPORT_API void satp_packet_clear(satp_network_packet* packet);

SATP_EXPORT_API void satp_packet_header_create(satp_network_packet* packetout, satp_flags flag, uint64_t sequence, uint32_t msglen);

SATP_EXPORT_API void satp_packet_header_deserialize(const uint8_t* header, satp_network_packet* packet);

SATP_EXPORT_API void satp_packet_header_serialize(const satp_network_packet* packet, uint8_t* header);

SATP_EXPORT_API satp_errors satp_packet_header_validate(const satp_network_packet* packetin, satp_flags pktflag, uint64_t sequence, uint32_t msglen);

SATP_EXPORT_API void satp_packet_set_utc_time(satp_network_packet* packet);

SATP_EXPORT_API bool satp_packet_time_valid(const satp_network_packet* packet);

SATP_EXPORT_API size_t satp_packet_to_stream(const satp_network_packet* packet, uint8_t* pstream);

SATP_EXPORT_API void satp_send_network_error(const qsc_socket* sock, satp_errors error);

SATP_EXPORT_API void satp_stream_to_packet(const uint8_t* pstream, satp_network_packet* packet);
 
#endif