SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
SharkMQ proxy connections

Detailed Description

Define ENABLE_PROXY when compiling both SharkMQ.c and its callers to include HTTP CONNECT and SOCKS5.

Alternatively define only ENABLE_HTTPS_PROXY or ENABLE_SOCKS_PROXY for one protocol. These options are tested for presence; defining one as 0 still enables it. SharkMQ.c includes proxy.ch; do not compile that file separately.

Construct SharkMQ first, then initialize a caller-owned Proxy and assign its address to SharkMQ::proxy before SharkMQ_init. Keep the Proxy and its strings alive through all connection attempts; SharkMQ does not free them. A NULL proxy pointer selects a direct connection.

HTTP CONNECT establishes a tunnel over plain TCP to the proxy; the HTTPS option name does not enable TLS to the proxy itself. SharkMQ then performs TLS with the broker through the tunnel. Basic/SOCKS credentials are not encrypted on the proxy connection. Use a trusted proxy network.

Size the SharkMQ communication buffer for the proxy request, hostname and credentials as well as the broker traffic. SOCKS requires at least 30 plus the larger of hostname length and credential-string length bytes. Proxy errors propagate from SharkMQ_init; a small SOCKS buffer returns -1.

Files

file  proxy.h
 Optional proxy configuration for the SharkMQ example library.
 

Data Structures

struct  Proxy
 Caller-owned proxy settings with borrowed string pointers. More...
 

Macros

#define E_PROXY_AUTH   -1000
 Authentication required or credentials rejected. More...
 
#define E_PROXY_GENERAL   -1001
 General proxy failure or unacceptable HTTP reply. More...
 
#define E_PROXY_NOT_ALLOWED   -1002
 SOCKS connection forbidden by ruleset. More...
 
#define E_PROXY_NETWORK   -1003
 SOCKS destination network unreachable. More...
 
#define E_PROXY_HOST   -1004
 SOCKS host unreachable or HTTP 404 response. More...
 
#define E_PROXY_REFUSED   -1005
 SOCKS connection refused. More...
 
#define E_PROXY_TTL   -1006
 SOCKS TTL expired. More...
 
#define E_PROXY_COMMAND_NOT_SUP   -1007
 SOCKS command unsupported. More...
 
#define E_PROXY_ADDRESS_NOT_SUP   -1008
 SOCKS address type unsupported. More...
 
#define E_PROXY_NOT_COMPATIBLE   -1009
 Unsupported SOCKS version. More...
 
#define E_PROXY_UNKNOWN   -1010
 Unknown SOCKS reply or authentication method. More...
 
#define E_PROXY_CLOSED   -1011
 Transport closed or failed during proxy negotiation. More...
 
#define E_PROXY_CANNOTCONNECT   -1012
 Proxy resolution or TCP connection failed. More...
 

Typedefs

typedef int(* ProxyConnect) (struct Proxy *o, struct ProxyArgs *args)
 Internal connector selected by Proxy_constructor; applications do not call it. More...
 
typedef struct Proxy Proxy
 Caller-owned proxy settings with borrowed string pointers. More...
 

Functions

void Proxy_constructor (Proxy *o, const char *proxyName, U16 proxyPortNo, const char *proxyUserPass, int socks)
 Initialize settings without allocating memory or opening a connection. More...
 

Macro Definition Documentation

◆ E_PROXY_ADDRESS_NOT_SUP

#define E_PROXY_ADDRESS_NOT_SUP   -1008

SOCKS address type unsupported.

◆ E_PROXY_AUTH

#define E_PROXY_AUTH   -1000

Authentication required or credentials rejected.

◆ E_PROXY_CANNOTCONNECT

#define E_PROXY_CANNOTCONNECT   -1012

Proxy resolution or TCP connection failed.

◆ E_PROXY_CLOSED

#define E_PROXY_CLOSED   -1011

Transport closed or failed during proxy negotiation.

◆ E_PROXY_COMMAND_NOT_SUP

#define E_PROXY_COMMAND_NOT_SUP   -1007

SOCKS command unsupported.

◆ E_PROXY_GENERAL

#define E_PROXY_GENERAL   -1001

General proxy failure or unacceptable HTTP reply.

◆ E_PROXY_HOST

#define E_PROXY_HOST   -1004

SOCKS host unreachable or HTTP 404 response.

◆ E_PROXY_NETWORK

#define E_PROXY_NETWORK   -1003

SOCKS destination network unreachable.

◆ E_PROXY_NOT_ALLOWED

#define E_PROXY_NOT_ALLOWED   -1002

SOCKS connection forbidden by ruleset.

◆ E_PROXY_NOT_COMPATIBLE

#define E_PROXY_NOT_COMPATIBLE   -1009

Unsupported SOCKS version.

◆ E_PROXY_REFUSED

#define E_PROXY_REFUSED   -1005

SOCKS connection refused.

◆ E_PROXY_TTL

#define E_PROXY_TTL   -1006

SOCKS TTL expired.

◆ E_PROXY_UNKNOWN

#define E_PROXY_UNKNOWN   -1010

Unknown SOCKS reply or authentication method.

Typedef Documentation

◆ Proxy

typedef struct Proxy Proxy

Caller-owned proxy settings with borrowed string pointers.

◆ ProxyConnect

typedef int(* ProxyConnect) (struct Proxy *o, struct ProxyArgs *args)

Internal connector selected by Proxy_constructor; applications do not call it.

Parameters
ostruct Proxy *; required borrowed configuration.
argsstruct ProxyArgs *; required temporary request owned by SharkMQ.
Returns
int: 0 after tunnel setup; negative E_PROXY_* or -1 on failure.

Function Documentation

◆ Proxy_constructor()

void Proxy_constructor ( Proxy *  o,
const char *  proxyName,
U16  proxyPortNo,
const char *  proxyUserPass,
int  socks 
)

Initialize settings without allocating memory or opening a connection.

Parameters
oProxy *; required caller-owned settings storage.
proxyNameconst char *; required NUL-terminated proxy hostname or address. Borrowed for the lifetime of all connections using these settings.
proxyPortNoU16; proxy TCP port, from 1 through 65535.
proxyUserPassconst char *; optional borrowed NUL-terminated user:password string, or NULL for no credentials. For SOCKS, include the colon and use 1-255 bytes for each component; the caller validates this.
socksint; 0 for HTTP CONNECT, nonzero for SOCKS5 when both are compiled. Ignored when only one protocol is compiled.