tlssocket.h

Go to the documentation of this file.

/* 2020-2026 Quantum Resistant Cryptographic Solutions Corporation
 * All Rights Reserved.
 *
 * Written by: John G. Underhill
 * Contact: contact@qrcscorp.ca
 */
 
#ifndef QSC_TLS_SOCKET_H
#define QSC_TLS_SOCKET_H
 
#include "qsccommon.h"
#include "async.h"
#include "tlsengine.h"
#include "tlssignerdefault.h"
#include "tlsio.h"
#include "socketbase.h"
#include "socketclient.h"
#include "socketserver.h"
#include "x509wrap.h"
#include "x509types.h"
 
QSC_CPLUSPLUS_ENABLED_START


#define QSC_TLS_SOCKET_CIPHER_SUITE_MAX 8U

#define QSC_TLS_SOCKET_GROUP_MAX 16U

#define QSC_TLS_SOCKET_SIGNATURE_SCHEME_MAX 16U

#define QSC_TLS_SOCKET_SERVER_IDENTITY_MAX QSC_TLS_MAX_SERVER_IDENTITIES

#define QSC_TLS_SOCKET_ALPN_PROTOCOL_MAX QSC_TLS_MAX_ALPN_PROTOCOLS

#define QSC_TLS_SOCKET_ALPN_SIZE_MAX QSC_TLS_MAX_ALPN_SIZE

#define QSC_TLS_SOCKET_SERVER_BUFFER_SIZE 16384U

#define QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX 64U

#define QSC_TLS_SOCKET_FRAME_HEADER_SIZE 4U

#define QSC_TLS_SOCKET_FRAME_SIZE_MAX 16777216U

#define QSC_TLS_SOCKET_TICKET_LIFETIME_MAX 604800U

typedef enum qsc_tls_socket_log_level
{
    qsc_tls_socket_log_level_none = 0,    
    qsc_tls_socket_log_level_error = 1,   
    qsc_tls_socket_log_level_warning = 2, 
    qsc_tls_socket_log_level_info = 3,    
    qsc_tls_socket_log_level_debug = 4    
} qsc_tls_socket_log_level;

typedef enum qsc_tls_socket_event
{
    qsc_tls_socket_event_none = 0,                 
    qsc_tls_socket_event_context_configured = 1,   
    qsc_tls_socket_event_socket_options = 2,       
    qsc_tls_socket_event_connect = 3,              
    qsc_tls_socket_event_accept = 4,               
    qsc_tls_socket_event_handshake_start = 5,      
    qsc_tls_socket_event_handshake_complete = 6,   
    qsc_tls_socket_event_send = 7,                 
    qsc_tls_socket_event_receive = 8,              
    qsc_tls_socket_event_frame_send = 9,           
    qsc_tls_socket_event_frame_receive = 10,       
    qsc_tls_socket_event_ticket = 11,              
    qsc_tls_socket_event_key_update = 12,          
    qsc_tls_socket_event_shutdown = 13,            
    qsc_tls_socket_event_worker_start = 14,        
    qsc_tls_socket_event_worker_stop = 15,         
    qsc_tls_socket_event_error = 16                
} qsc_tls_socket_event;

typedef struct qsc_tls_socket_options
{
    uint32_t connect_timeout_ms;   
    uint32_t handshake_timeout_ms; 
    uint32_t receive_timeout_ms;   
    uint32_t send_timeout_ms;      
    uint32_t idle_timeout_ms;      
    size_t receive_buffer_size;    
    size_t send_buffer_size;       
    bool reuse_address;            
    bool no_delay;                 
    bool keep_alive;               
    bool dual_stack;               
    bool blocking;                 
} qsc_tls_socket_options;

typedef struct qsc_tls_socket_ticket_policy
{
    bool enabled;                       
    bool allow_early_data;              
    bool auto_send_server_ticket;       
    uint32_t lifetime_seconds;          
    uint32_t renewal_interval_seconds;  
} qsc_tls_socket_ticket_policy;

typedef enum qsc_tls_socket_status
{
    qsc_tls_socket_status_success = 0,                      
    qsc_tls_socket_status_invalid_input = 1,                
    qsc_tls_socket_status_not_initialized = 2,              
    qsc_tls_socket_status_socket_start_failed = 3,          
    qsc_tls_socket_status_socket_connect_failed = 4,        
    qsc_tls_socket_status_socket_bind_failed = 5,           
    qsc_tls_socket_status_socket_listen_failed = 6,         
    qsc_tls_socket_status_socket_accept_failed = 7,         
    qsc_tls_socket_status_tls_initialize_failed = 8,        
    qsc_tls_socket_status_tls_handshake_failed = 9,         
    qsc_tls_socket_status_certificate_load_failed = 10,     
    qsc_tls_socket_status_certificate_verify_failed = 11,   
    qsc_tls_socket_status_private_key_invalid = 12,         
    qsc_tls_socket_status_policy_rejected = 13,             
    qsc_tls_socket_status_io_failed = 14,                   
    qsc_tls_socket_status_closed = 15,                      
    qsc_tls_socket_status_internal_error = 16               
} qsc_tls_socket_status;

typedef struct qsc_tls_socket_result
{
    qsc_tls_socket_status status;        
    qsc_tls_status tlsstatus;            
    qsc_socket_exceptions socketstatus;  
    qsc_x509w_status x509status;         
    qsc_x509_verify_status verifystatus; 
    qsc_tls_alert_description alert;     
} qsc_tls_socket_result;

typedef void (*qsc_tls_socket_log_callback)(qsc_tls_socket_log_level level, qsc_tls_socket_event event, const qsc_tls_socket_result* result, const char* message, void* state);

typedef struct qsc_tls_socket_peer_info
{
    char subject[QSC_X509_NAME_ATTRIBUTE_STRING_MAX];     
    char issuer[QSC_X509_NAME_ATTRIBUTE_STRING_MAX];      
    char common_name[QSC_X509_NAME_ATTRIBUTE_STRING_MAX]; 
    char dns_name[QSC_X509_NAME_ATTRIBUTE_STRING_MAX];    
    qsc_tls_socket_result result;                         
    qsc_tls_cipher_suite cipher_suite;                    
    qsc_tls_named_group named_group;                      
    qsc_tls_signature_scheme signature_scheme;            
    qsc_x509w_status x509_status;                         
    qsc_x509_verify_status verify_status;                 
    bool authenticated;                                   
    bool hostname_matched;                                
    bool hostname_checked;                                
    bool chain_valid;                                     
    bool psk_accepted;                                    
    bool early_data_accepted;                             
    bool alpn_selected;                                    
    char selected_alpn[QSC_TLS_SOCKET_ALPN_SIZE_MAX + 1U]; 
} qsc_tls_socket_peer_info;

typedef struct qsc_tls_socket_context
{
    qsc_x509w_trust_store truststore;                                           
    qsc_x509w_server_identity identity;                                         
    qsc_x509w_tls_bridge bridge;                                                
    qsc_x509w_tls_local_certificate localcert;                                  
    qsc_x509w_tls_local_certificate snilocalcerts[QSC_TLS_SOCKET_SERVER_IDENTITY_MAX]; 
    char snihostnames[QSC_TLS_SOCKET_SERVER_IDENTITY_MAX][QSC_TLS_MAX_HOSTNAME_SIZE + 1U]; 
    size_t sniidentitycount;                                                    
    bool requiresni;                                                           
    qsc_x509w_profile certificateprofile;                                       
    qsc_tls_socket_options socketoptions;                                       
    qsc_tls_socket_ticket_policy ticketpolicy;                                  
    qsc_tls_alpn_protocols alpn;                                                
    qsc_tls_session_ticket sessionticket;                                       
    qsc_tls_socket_log_callback logcallback;                                    
    void* logstate;                                                             
    qsc_tls_cipher_suite ciphersuites[QSC_TLS_SOCKET_CIPHER_SUITE_MAX];         
    qsc_tls_named_group groups[QSC_TLS_SOCKET_GROUP_MAX];                       
    qsc_tls_signature_scheme sigschemes[QSC_TLS_SOCKET_SIGNATURE_SCHEME_MAX];   
    size_t ciphersuitecount;                                                    
    size_t groupcount;                                                          
    size_t sigschemecount;                                                      
    bool hasidentity;                                                           
    bool hastruststore;                                                         
    qsc_tls_client_authorization_callback clientauthcallback;                   
    void* clientauthstate;                                                       
    bool requireclientauthorization;                                             
    bool requireclientauth;                                                     
    bool requestclientauth;                                                     
    bool allowunverified;                                                       
    bool hassessionticket;                                                      
    bool initialized;                                                           
} qsc_tls_socket_context;

typedef struct qsc_tls_socket_connection
{
    qsc_socket socket;                              
    qsc_tls_connection engine;                      
    qsc_tls_io_connection io;                       
    qsc_tls_role role;                              
    qsc_socket_address_families family;             
    qsc_tls_socket_result lastresult;               
    qsc_tls_socket_peer_info peerinfo;              
    qsc_tls_socket_options socketoptions;           
    qsc_tls_socket_ticket_policy ticketpolicy;      
    qsc_tls_session_ticket lastticket;              
    qsc_tls_signer_default_context signcontext;     
    qsc_tls_socket_log_callback logcallback;        
    void* logstate;                                 
    char peername[QSC_SOCKET_ADDRESS_MAX_SIZE];     
    uint16_t peerport;                              
    bool connected;                                 
    bool handshaked;                                
    bool owns_socket;                               
    bool haslastticket;                             
    bool cancelrequested;                           
} qsc_tls_socket_connection;

typedef struct qsc_tls_socket_listener
{
    qsc_socket socket;                         
    const qsc_tls_socket_context* context;     
    qsc_socket_address_families family;        
    uint16_t port;                             
    int32_t backlog;                           
    qsc_tls_socket_options socketoptions;      
    bool initialized;                          
    bool listening;                            
} qsc_tls_socket_listener;
 
struct qsc_tls_socket_server;

typedef struct qsc_tls_socket_server_worker_state
{
    struct qsc_tls_socket_server* server; 
    size_t index;                         
} qsc_tls_socket_server_worker_state;

typedef void (*qsc_tls_socket_server_connect_callback)(qsc_tls_socket_connection* connection, void* state);

typedef void (*qsc_tls_socket_server_receive_callback)(qsc_tls_socket_connection* connection, const uint8_t* message, size_t msglen, void* state);

typedef void (*qsc_tls_socket_server_disconnect_callback)(qsc_tls_socket_connection* connection, void* state);

typedef void (*qsc_tls_socket_server_error_callback)(qsc_tls_socket_connection* connection, qsc_tls_socket_status status, void* state);

typedef struct qsc_tls_socket_server
{
    qsc_tls_socket_listener listener;                                                       
    qsc_tls_socket_server_connect_callback onconnect;                                       
    qsc_tls_socket_server_receive_callback onreceive;                                       
    qsc_tls_socket_server_disconnect_callback ondisconnect;                                 
    qsc_tls_socket_server_error_callback onerror;                                           
    qsc_tls_socket_log_callback onlog;                                                      
    void* callbackstate;                                                                    
    void* logstate;                                                                         
    qsc_tls_socket_connection connections[QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX];           
    qsc_tls_socket_server_worker_state workerstates[QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX]; 
    qsc_thread workerthreads[QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX];                        
    volatile bool active[QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX];                            
    volatile bool started[QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX];                           
    qsc_mutex poolmutex;                                                                    
    size_t maxclients;                                                                      
    volatile bool running;                                                                  
    bool concurrent;                                                                        
    bool initialized;                                                                       
} qsc_tls_socket_server;

QSC_EXPORT_API void qsc_tls_socket_result_clear(qsc_tls_socket_result* result);

QSC_EXPORT_API const char* qsc_tls_socket_status_string(qsc_tls_socket_status status);

QSC_EXPORT_API void qsc_tls_socket_options_initialize_default(qsc_tls_socket_options* options);

QSC_EXPORT_API void qsc_tls_socket_ticket_policy_initialize_default(qsc_tls_socket_ticket_policy* policy);

QSC_EXPORT_API void qsc_tls_socket_context_initialize(qsc_tls_socket_context* context);

QSC_EXPORT_API void qsc_tls_socket_context_dispose(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_default_client_policy(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_default_server_policy(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_mlkem_hybrid_policy(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_experimental_pqc_policy(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_strict_policy(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_development_policy(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_cipher_suites(qsc_tls_socket_context* context, const qsc_tls_cipher_suite* suites, size_t suitecount);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_named_groups(qsc_tls_socket_context* context, const qsc_tls_named_group* groups, size_t groupcount);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_signature_schemes(qsc_tls_socket_context* context, const qsc_tls_signature_scheme* schemes, size_t schemecount);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_trust_anchor_file(qsc_tls_socket_context* context, const char* path, bool selfsigned);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_trust_anchor_bundle_file(qsc_tls_socket_context* context, const char* path, bool selfsigned);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_crl_file(qsc_tls_socket_context* context, const char* path);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_server_identity_files(qsc_tls_socket_context* context, const char* certificatechainpath, const char* privatekeypath, qsc_tls_signature_scheme verifyscheme);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_add_server_identity_files(qsc_tls_socket_context* context, const char* hostname,
    const char* certificatechainpath, const char* privatekeypath, qsc_tls_signature_scheme verifyscheme);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_sni_required(qsc_tls_socket_context* context, bool required);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_client_auth(qsc_tls_socket_context* context, bool requestclientauth, bool requireclientauth);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_client_authorization(qsc_tls_socket_context* context,
    qsc_tls_client_authorization_callback callback, void* state, bool required);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_socket_options(qsc_tls_socket_context* context, const qsc_tls_socket_options* options);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_alpn_protocols(qsc_tls_socket_context* context, const char* const* protocols, size_t protocolcount, bool required);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_clear_alpn_protocols(qsc_tls_socket_context* context);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_log_callback(qsc_tls_socket_context* context, qsc_tls_socket_log_callback callback, void* state);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_session_ticket_policy(qsc_tls_socket_context* context, const qsc_tls_socket_ticket_policy* policy);

QSC_EXPORT_API bool qsc_tls_socket_session_ticket_is_valid(const qsc_tls_session_ticket* ticket);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_session_ticket(qsc_tls_socket_context* context, const qsc_tls_session_ticket* ticket);

QSC_EXPORT_API void qsc_tls_socket_context_clear_session_ticket(qsc_tls_socket_context* context);

QSC_EXPORT_API void qsc_tls_socket_connection_initialize(qsc_tls_socket_connection* connection);

QSC_EXPORT_API void qsc_tls_socket_connection_dispose(qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_host(qsc_tls_socket_connection* connection, const qsc_tls_socket_context* context, const char* hostname, const char* service);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_host_ex(qsc_tls_socket_connection* connection, const qsc_tls_socket_context* context, const char* hostname, const char* service, const qsc_tls_session_ticket* ticket, bool enableearlydata);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_ipv4(qsc_tls_socket_connection* connection, const qsc_tls_socket_context* context, const qsc_ipinfo_ipv4_address* address, uint16_t port, const char* hostname);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_ipv6(qsc_tls_socket_connection* connection, const qsc_tls_socket_context* context, const qsc_ipinfo_ipv6_address* address, uint16_t port, const char* hostname);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_send(qsc_tls_socket_connection* connection, const uint8_t* input, size_t inlen, size_t* written);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_receive(qsc_tls_socket_connection* connection, uint8_t* output, size_t outlen, size_t* read);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_shutdown(qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_key_update(qsc_tls_socket_connection* connection, bool requestpeerupdate);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_send_session_ticket(qsc_tls_socket_connection* connection, uint32_t lifetime_seconds, qsc_tls_session_ticket* ticketout);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_set_socket_options(qsc_tls_socket_connection* connection, const qsc_tls_socket_options* options);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_set_log_callback(qsc_tls_socket_connection* connection, qsc_tls_socket_log_callback callback, void* state);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_cancel(qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_get_peer_info(const qsc_tls_socket_connection* connection, qsc_tls_socket_peer_info* peerinfo);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_get_selected_alpn(const qsc_tls_socket_connection* connection, char* protocol, size_t protocolcap, size_t* protocollen);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_get_session_ticket(const qsc_tls_socket_connection* connection, qsc_tls_session_ticket* ticketout);

QSC_EXPORT_API void qsc_tls_socket_connection_clear_session_ticket(qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_send_frame(qsc_tls_socket_connection* connection, const uint8_t* input, size_t inlen);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_receive_frame(qsc_tls_socket_connection* connection, uint8_t* output, size_t outlen, size_t* read);

QSC_EXPORT_API bool qsc_tls_socket_is_connected(const qsc_tls_socket_connection* connection);

QSC_EXPORT_API bool qsc_tls_socket_is_handshake_complete(const qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_cipher_suite qsc_tls_socket_negotiated_cipher_suite(const qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_named_group qsc_tls_socket_negotiated_group(const qsc_tls_socket_connection* connection);

QSC_EXPORT_API qsc_tls_signature_scheme qsc_tls_socket_negotiated_signature_scheme(const qsc_tls_socket_connection* connection);

QSC_EXPORT_API void qsc_tls_socket_listener_initialize(qsc_tls_socket_listener* listener);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_set_options(qsc_tls_socket_listener* listener, bool reuseaddress, bool nodelay, uint32_t recvtimeoutms, uint32_t sendtimeoutms);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_set_socket_options(qsc_tls_socket_listener* listener, const qsc_tls_socket_options* options);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_bind(qsc_tls_socket_listener* listener, const qsc_tls_socket_context* context, const char* address, uint16_t port, qsc_socket_address_families family);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_accept(qsc_tls_socket_listener* listener, qsc_tls_socket_connection* connection);

QSC_EXPORT_API void qsc_tls_socket_listener_close(qsc_tls_socket_listener* listener);

QSC_EXPORT_API void qsc_tls_socket_server_initialize(qsc_tls_socket_server* server);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_configure(qsc_tls_socket_server* server, const qsc_tls_socket_context* context, const char* address, uint16_t port, qsc_socket_address_families family);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_set_callbacks(qsc_tls_socket_server* server, qsc_tls_socket_server_connect_callback onconnect, qsc_tls_socket_server_receive_callback onreceive, qsc_tls_socket_server_disconnect_callback ondisconnect, qsc_tls_socket_server_error_callback onerror, void* state);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_set_log_callback(qsc_tls_socket_server* server, qsc_tls_socket_log_callback callback, void* state);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_set_max_clients(qsc_tls_socket_server* server, size_t maxclients);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_start(qsc_tls_socket_server* server);

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_start_concurrent(qsc_tls_socket_server* server);

QSC_EXPORT_API void qsc_tls_socket_server_stop(qsc_tls_socket_server* server);

QSC_EXPORT_API void qsc_tls_socket_server_dispose(qsc_tls_socket_server* server);
 
QSC_CPLUSPLUS_ENABLED_END
 
#endif