socketbase.h

Go to the documentation of this file.

/* 2020-2026 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 herein are proprietary to QRCS and are
 * protected under applicable Canadian, U.S., and international copyright,
 * patent, and trade secret laws.
 *
 * CRYPTOGRAPHIC ALGORITHMS AND IMPLEMENTATIONS:
 * - This software includes implementations of cryptographic primitives and
 *   algorithms that are standardized or in the public domain, such as AES
 *   and SHA-3, which are not proprietary to QRCS.
 * - This software also includes cryptographic primitives, constructions, and
 *   algorithms designed by QRCS, including but not limited to RCS, SCB, CSX, QMAC, and
 *   related components, which are proprietary to QRCS.
 * - All source code, implementations, protocol compositions, optimizations,
 *   parameter selections, and engineering work contained in this software are
 *   original works of QRCS and are protected under this license.
 *
 * LICENSE AND USE RESTRICTIONS:
 * - This software is licensed under the Quantum Resistant Cryptographic Solutions
 *   Public Research and Evaluation License (QRCS-PREL), 2025-2026.
 * - Permission is granted solely for non-commercial evaluation, academic research,
 *   cryptographic analysis, interoperability testing, and feasibility assessment.
 * - Commercial use, production deployment, commercial redistribution, or
 *   integration into products or services is strictly prohibited without a
 *   separate written license agreement executed with QRCS.
 * - Licensing and authorized distribution are solely at the discretion of QRCS.
 *
 * EXPERIMENTAL CRYPTOGRAPHY NOTICE:
 * Portions of this software may include experimental, novel, or evolving
 * cryptographic designs. Use of this software is entirely at the user's risk.
 *
 * DISCLAIMER:
 * THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE, SECURITY, OR NON-INFRINGEMENT. QRCS DISCLAIMS ALL
 * LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
 * ARISING FROM THE USE OR MISUSE OF THIS SOFTWARE.
 *
 * FULL LICENSE:
 * This software is subject to the Quantum Resistant Cryptographic Solutions
 * Public Research and Evaluation License (QRCS-PREL), 2025-2026. The complete license terms
 * are provided in the accompanying LICENSE file or at https://www.qrcscorp.ca.
 *
 * Written by: John G. Underhill
 * Contact: contact@qrcscorp.ca
 */
 
#ifndef QSC_SOCKETBASE_H
#define QSC_SOCKETBASE_H
 
#include "qsccommon.h"
#include "intutils.h"
#include "ipinfo.h"
#include "memutils.h"
#include "socket.h"
 
QSC_CPLUSPLUS_ENABLED_START

 
/* bogus winbase.h error */
QSC_SYSTEM_CONDITION_IGNORE(5105)
 
#if defined(QSC_SYSTEM_OS_WINDOWS)
#   include <WinSock2.h>
#elif defined(QSC_SYSTEM_OS_POSIX)
#   include <sys/select.h>
#endif

//\def QSC_SOCKET_DUAL_IPV6_STACK
//* \brief Enables a dual stack ipv4 and ipv6 listener.
//*/
//#if !defined(QSC_SOCKET_DUAL_IPV6_STACK)
//# define QSC_SOCKET_DUAL_IPV6_STACK
//#endif
 
/*** Function State ***/

#define QSC_SOCKET_RECEIVE_BUFFER_SIZE 1600U

#define QSC_SOCKET_DEFAULT_SNDBUF_SIZE 65536U  

typedef enum
{
    qsc_socket_exception_success = 0,                               
    qsc_socket_exception_error = -1,                              
    qsc_socket_invalid_input = -2,                                  
#if defined(QSC_SYSTEM_OS_WINDOWS)
    qsc_socket_exception_address_in_use = WSAEADDRINUSE,         
    qsc_socket_exception_address_required = WSAEDESTADDRREQ,       
    qsc_socket_exception_address_unsupported = WSAEAFNOSUPPORT,     
    qsc_socket_exception_already_in_use = WSAEISCONN,                
    qsc_socket_exception_blocking_cancelled = WSAEINTR,              
    qsc_socket_exception_blocking_in_progress = WSAEINPROGRESS,        
    qsc_socket_exception_broadcast_address = WSAEACCES,               
    qsc_socket_exception_buffer_fault = WSAEFAULT,                 
    qsc_socket_exception_circuit_reset = WSAECONNRESET,               
    qsc_socket_exception_circuit_terminated = WSAECONNABORTED,       
    qsc_socket_exception_circuit_timeout = WSAETIMEDOUT,            
    qsc_socket_exception_connection_refused = WSAECONNREFUSED,       
    qsc_socket_exception_descriptor_not_socket = WSAENOTSOCK,     
    qsc_socket_exception_disk_quota_exceeded = WSAEDQUOT,           
    qsc_socket_exception_dropped_connection = WSAENETRESET,          
    qsc_socket_exception_family_unsupported = WSAEPFNOSUPPORT,       
    qsc_socket_exception_host_is_down = WSAEHOSTDOWN,              
    qsc_socket_exception_host_unreachable = WSAEHOSTUNREACH,       
    qsc_socket_exception_in_progress = WSAEALREADY,                 
    qsc_socket_exception_invalid_address = WSAEADDRNOTAVAIL,        
    qsc_socket_exception_invalid_parameter = WSA_INVALID_PARAMETER, 
    qsc_socket_exception_invalid_protocol = WSAEPROTOTYPE,         
    qsc_socket_exception_invalid_protocol_option = WSAENOPROTOOPT,  
    qsc_socket_exception_invalid_provider = WSAEINVALIDPROVIDER,    
    qsc_socket_exception_item_is_remote = WSAEREMOTE,                
    qsc_socket_exception_message_too_long = WSAEMSGSIZE,           
    qsc_socket_exception_name_too_long = WSAENAMETOOLONG,         
    qsc_socket_exception_network_failure = WSAENETDOWN,             
    qsc_socket_exception_network_unreachable = WSAENETUNREACH,      
    qsc_socket_exception_no_buffer_space = WSAENOBUFS,              
    qsc_socket_exception_no_descriptors = WSAEMFILE,             
    qsc_socket_exception_no_memory = WSA_NOT_ENOUGH_MEMORY,         
    qsc_socket_exception_not_bound = WSAEINVAL,                       
    qsc_socket_exception_not_connected = WSAENOTCONN,             
    qsc_socket_exception_not_initialized = WSANOTINITIALISED,       
    qsc_socket_exception_operation_unsupported = WSAEOPNOTSUPP,       
    qsc_socket_exception_protocol_unsupported = WSAEPROTONOSUPPORT,    
    qsc_socket_exception_shut_down = WSAESHUTDOWN,                    
    qsc_socket_exception_socket_unsupported = WSAESOCKTNOSUPPORT,    
    qsc_socket_exception_system_not_ready = WSASYSNOTREADY,            
    qsc_socket_exception_too_many_processes = WSAEPROCLIM,          
    qsc_socket_exception_too_many_users = WSAEUSERS,             
    qsc_socket_exception_translation_failed = WSAELOOP,              
    qsc_socket_exception_would_block = WSAEWOULDBLOCK,              
#else
    qsc_socket_exception_address_in_use = EADDRINUSE,                
    qsc_socket_exception_address_required = EDESTADDRREQ,          
    qsc_socket_exception_address_unsupported = EAFNOSUPPORT,        
    qsc_socket_exception_already_in_use = EISCONN,                   
    qsc_socket_exception_blocking_cancelled = EINTR,             
    qsc_socket_exception_blocking_in_progress = EINPROGRESS,       
    qsc_socket_exception_broadcast_address = EACCES,              
    qsc_socket_exception_buffer_fault = EFAULT,                        
    qsc_socket_exception_circuit_terminated = ECONNABORTED,          
    qsc_socket_exception_circuit_reset = ECONNRESET,              
    qsc_socket_exception_circuit_timeout = ETIMEDOUT,               
    qsc_socket_exception_connection_refused = ECONNREFUSED,          
    qsc_socket_exception_descriptor_not_socket = ENOTSOCK,            
    qsc_socket_exception_disk_quota_exceeded = EDQUOT,              
    qsc_socket_exception_dropped_connection = ENETRESET,         
    qsc_socket_exception_family_unsupported = EPFNOSUPPORT,          
    qsc_socket_exception_host_is_down = EHOSTDOWN,                 
    qsc_socket_exception_host_unreachable = EHOSTUNREACH,          
    qsc_socket_exception_in_progress = EALREADY,                    
    qsc_socket_exception_invalid_address = EADDRNOTAVAIL,           
    //qsc_socket_exception_invalid_parameter = EOTHER,              /*!< One or more parameters are invalid */
    qsc_socket_exception_invalid_protocol = EPROTOTYPE,                
    qsc_socket_exception_invalid_protocol_option = ENOPROTOOPT,     
    //qsc_socket_exception_invalid_provider = EINVALIDPROVIDER,     /*!< The service provider is invalid */
    qsc_socket_exception_item_is_remote = EREMOTE,                   
    qsc_socket_exception_message_too_long = EMSGSIZE,              
    qsc_socket_exception_name_too_long = ENAMETOOLONG,                
    qsc_socket_exception_network_failure = ENETDOWN,                
    qsc_socket_exception_network_unreachable = ENETUNREACH,         
    qsc_socket_exception_no_buffer_space = ENOBUFS,                 
    qsc_socket_exception_no_descriptors = EMFILE,                    
    qsc_socket_exception_not_bound = EINVAL,                      
    qsc_socket_exception_not_connected = ENOTCONN,                    
    qsc_socket_exception_operation_unsupported = EOPNOTSUPP,      
    qsc_socket_exception_protocol_unsupported = EPROTONOSUPPORT,   
    qsc_socket_exception_socket_unsupported = ESOCKTNOSUPPORT,       
    qsc_socket_exception_shut_down = ESHUTDOWN,                       
    qsc_socket_exception_system_not_ready = ETXTBSY,               
    //qsc_socket_exception_too_many_processes = EPROCLIM,           /*!< The host is using too many processes */
    qsc_socket_exception_too_many_users = EUSERS,                    
    qsc_socket_exception_translation_failed = ELOOP,             
    qsc_socket_exception_would_block = EWOULDBLOCK,                 
 
#endif
} qsc_socket_exceptions;

extern const char QSC_SOCKET_ERROR_STRINGS[48][128];

typedef struct
{
    void (*callback)(qsc_socket* sock, const uint8_t* message, size_t* msglen);   
    void (*error)(const qsc_socket* sock, qsc_socket_exceptions exception);     
    qsc_socket* source;                                                         
    uint8_t buffer[QSC_SOCKET_RECEIVE_BUFFER_SIZE];                             
} qsc_socket_receive_async_state;

typedef struct
{
    qsc_socket** sockarr;                                                      
    void (*callback)(qsc_socket* sock, size_t id);                                
    void (*error)(qsc_socket* sock, qsc_socket_exceptions exception);           
    uint32_t count;                                                                
} qsc_socket_receive_poll_state;
 
/*** Function Prototypes ***/

//* \brief The socket exception callback prototype
//*
//* \param source:  [qsc_socket*] The socket source
//* \param error:   [qsc_socket_exceptions] The socket exception
//*/
//QSC_EXPORT_API void qsc_socket_exception_callback(qsc_socket* source, qsc_socket_exceptions error);

//* \brief The socket receive asynchronous callback prototype
//*
//* \param source:  [qsc_socket*] The socket source
//* \param message: [const uint8_t*] The socket message buffer
//* \param msglen:  [size_t*] A pointer to the size of the message
//*/
//QSC_EXPORT_API void qsc_socket_receive_async_callback(qsc_socket* source, const uint8_t* message, size_t* msglen);

//* \brief The receive polling callback prototype
//*
//* \param source:  [const qsc_socket*] The socket source
//* \param error:   [size_t] The socket exception
//*/
//QSC_EXPORT_API void qsc_socket_receive_poll_callback(const qsc_socket* source, size_t error);
 
/*** Accessors ***/

QSC_EXPORT_API bool qsc_socket_ipv4_valid_address(const char* address);

QSC_EXPORT_API bool qsc_socket_ipv6_valid_address(const char* address);

QSC_EXPORT_API bool qsc_socket_is_blocking(const qsc_socket* sock);

QSC_EXPORT_API bool qsc_socket_is_connected(const qsc_socket* sock);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_accept(const qsc_socket* source, qsc_socket* target);

QSC_EXPORT_API void qsc_socket_attach(qsc_socket* source, qsc_socket* target);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_bind(qsc_socket* sock, const char* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_bind_ipv4(qsc_socket* sock, const qsc_ipinfo_ipv4_address* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_bind_ipv6(qsc_socket* sock, const qsc_ipinfo_ipv6_address* address, uint16_t port);

QSC_EXPORT_API void qsc_socket_clear_socket(qsc_socket* sock);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_close_socket(qsc_socket* sock);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_connect(qsc_socket* sock, const char* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_connect_ipv4(qsc_socket* sock, const qsc_ipinfo_ipv4_address* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_connect_ipv6(qsc_socket* sock, const qsc_ipinfo_ipv6_address* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_create(qsc_socket* sock, qsc_socket_address_families family, qsc_socket_transports transport, qsc_socket_protocols protocol);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_listen(const qsc_socket* sock, int32_t backlog);

QSC_EXPORT_API size_t qsc_socket_max_send_buffer_size(const qsc_socket* sock);

QSC_EXPORT_API size_t qsc_socket_peek(const qsc_socket* sock, uint8_t* output, size_t otplen);

QSC_EXPORT_API size_t qsc_socket_receive(const qsc_socket* sock, uint8_t* output, size_t otplen, qsc_socket_receive_flags flag);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_receive_async(qsc_socket_receive_async_state* state);

QSC_EXPORT_API size_t qsc_socket_receive_all(const qsc_socket* sock, uint8_t* output, size_t otplen, qsc_socket_receive_flags flag);

QSC_EXPORT_API size_t qsc_socket_receive_from(qsc_socket* sock, char* dest, size_t destlen, uint16_t port, uint8_t* output, size_t otplen, qsc_socket_receive_flags flag);

QSC_EXPORT_API uint32_t qsc_socket_receive_poll(const qsc_socket_receive_poll_state* state);

QSC_EXPORT_API size_t qsc_socket_send(const qsc_socket* sock, const uint8_t* input, size_t inplen, qsc_socket_send_flags flag);

QSC_EXPORT_API size_t qsc_socket_send_to(const qsc_socket* sock, const uint8_t* input, size_t inplen, qsc_socket_send_flags flag);

QSC_EXPORT_API size_t qsc_socket_send_all(const qsc_socket* sock, const uint8_t* input, size_t inplen, qsc_socket_send_flags flag);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_shut_down(qsc_socket* sock, qsc_socket_shut_down_flags params);
 
/*~~~ Helper Functions ~~~*/

QSC_EXPORT_API const char* qsc_socket_error_to_string(qsc_socket_exceptions code);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_get_last_error(void);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_ioctl(const qsc_socket* sock, int32_t command, uint32_t* arguments);

QSC_EXPORT_API bool qsc_socket_receive_ready(const qsc_socket* sock, const struct timeval* timeout);

QSC_EXPORT_API bool qsc_socket_send_ready(const qsc_socket* sock, const struct timeval* timeout);

QSC_EXPORT_API void qsc_socket_set_last_error(qsc_socket_exceptions error);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_shut_down_sockets(void);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_set_option(const qsc_socket* sock, qsc_socket_protocols level, qsc_socket_options option, int32_t optval);

QSC_EXPORT_API bool qsc_socket_start_sockets(void);
 
QSC_CPLUSPLUS_ENABLED_END
 
#endif