NetBurner 3.1
SSL - Secure Socket Layer

Modules

 SSL Error Codes
 

Functions

int SSL_accept (int fdListen, IPADDR *address, uint16_t *port, uint16_t accept_timeout, uint16_t negotiation_timeout=0)
 This call is a mirror of the TCP::accept() call. More...
 
BOOL IsSSLfd (int fd)
 Returns whether or not a file descriptor is an SSL file descriptor. More...
 
IPADDR SSL_GetSocketRemoteAddr (int fd)
 Returns the remote address of this connected socket. More...
 
int SSL_GetSocketInterface (int fd)
 Return the network interface associated with a TCP socket. More...
 
uint16_t SSL_GetSocketRemotePort (int fd)
 Returns the remote port of this connected socket. More...
 
IPADDR SSL_GetSocketLocalAddr (int fd)
 Returns the local address of this connected socket. More...
 
uint16_t SSL_GetSocketLocalPort (int fd)
 Returns the local port of this connected socket. More...
 
uint32_t SSL_TcpGetLastRxTime (int fd)
 SSL mirror of TcpGetLastRxTime(). More...
 
void SSL_TcpSendKeepAlive (int fd)
 SSL mirror of TcpSendKeepAlive(). More...
 
int SSL_setsockoption (int fd, int option)
 Set SSL TCP socket options. More...
 
int SSL_clrsockoption (int fd, int option)
 Clear SSL TCP socket options. More...
 
int SSL_getsockoption (int fd)
 Returns the options for the specified SSL TCP socket. More...
 
int SSL_getsocketerror (int fd)
 Returns the socket error state for the specified SSL socket. More...
 
int SSL_connect (IPADDR ip, uint16_t local_port, uint16_t remote_port, uint32_t timeout, const char *common_name, bool verifyPeer=false, bool waitForNegotiation=true, SharkSslCAList caList=nullptr)
 SSL mirror of the TCP::connect() call. More...
 
int SSL_makeSecure (int fds, uint32_t timeout, const char *common_name, bool verifyPeer=false, bool waitForNegotiation=true, SharkSslCAList caList=nullptr, bool bIsClient=true)
 Executes the TLS negotiation over a given socket, to establish a secure communication channel through that socket. More...
 
int SSL_negotiate (int fds, uint32_t timeout, const char *common_name, bool reuseSessionPort=true, bool verifyPeer=false, SharkSslCAList caList=nullptr, bool bIsClient=true)
 SSL mirror of the TCP::connect() call, but uses an existing TCP file descriptor. More...
 
int SSLReadWithTimeout (int fd, char *cp, int size, uint32_t timeout)
 SSL mirror of the ReadWithTiemout() function. More...
 
uint32_t SetMaxSessionReuseTime (uint32_t newLifetimeTicks)
 Allows one to specify at runtime what the longest duration that an established session can be used for before new connections must be fully renegotiated. More...
 
const char * GetCertificatePEM ()
 Function that returns a pointer to the compiled in server certificate. More...
 
const char * GetPrivateKeyPEM ()
 Function that returns a pointer to the compiled in server key. More...
 
bool IsSSL_CertNKeyValid (const char *keyPEM, ssize_t keylen, const char *certPEM, ssize_t certlen)
 Validate candidate certificate and private key.
 
bool SSL_SetClientCAList (SharkSslCAList *CAList)
 Attempts to set the Certificate Authority List for the SharkSsl clientCtx More...
 
bool SSL_SetServerCAList (SharkSslCAList *CAList)
 Attempts to set the Certificate Authority List for the SharkSsl serverCtx More...
 
uint16_t SSLGetRxBufferSpaceUsed (int fd)
 Returns the amount of data buffered to be read from the socket. More...
 
uint16_t SSLGetTxBufferAvailSpace (int fd)
 Returns the amount of data buffered to be read from the socket. More...
 

Detailed Description

The NetBurner SSL Library

Function Documentation

◆ GetCertificatePEM()

const char* GetCertificatePEM ( )

Function that returns a pointer to the compiled in server certificate.

See the SSL documentation and examples for information on generating a self signed certificate and key.

Returns
A pointer to the compiled in certificate.
See also
GetPrivateKeyPEM()

Function that returns a pointer to the compiled in server certificate.

Return values
Pointerto the found cert

Function that returns a pointer to the compiled in server certificate.

◆ GetPrivateKeyPEM()

const char* GetPrivateKeyPEM ( )

Function that returns a pointer to the compiled in server key.

See the SSL documentation and examples for information on generating a self signed certificate and key.

Returns
A pointer to the compiled in server key.
See also
GetCertificatePEM()

Function that returns a pointer to the compiled in server key.

Return values
Pointerto the found key

Function that returns a pointer to the compiled in server key.

◆ IsSSLfd()

BOOL IsSSLfd ( int  fd)

Returns whether or not a file descriptor is an SSL file descriptor.

This function is used to determine if the fd is an SSL connection. It can be used by things like the callback functions of the web server to determine how secure the fd is before sending sensitive information over it.

Parameters
fdThe file descriptor to test.
Return values
TRUEIf it is an SSL fd
FALSEIf it is not an SSL fd or if there was an error
See also
SSL_GetSocketRemoteAddr(int i)
SSL_GetSocketRemotePort(int i)
SSL_GetSocketLocalAddr(int i)
SSL_GetSocketLocalPort(int i)

◆ SetMaxSessionReuseTime()

uint32_t SetMaxSessionReuseTime ( uint32_t  newLifetimeTicks)

Allows one to specify at runtime what the longest duration that an established session can be used for before new connections must be fully renegotiated.

This is a security trade-off feature. It will negatively impact performance to decrease this value. To disable maximum reuse lifetime, pass the argument as 0.

The default value used for this purpose on startup is defined in predef.h as the macro SSL_DEFAULT_MAX_SESSION_AGE_TICKS.

Parameters
newLifetimeTicks
Returns
Returns previously assigned reuse maximum.

◆ SSL_accept()

int SSL_accept ( int  fdListen,
IPADDR address,
uint16_t *  port,
uint16_t  accept_timeout,
uint16_t  negotiation_timeout = 0 
)

This call is a mirror of the TCP::accept() call.

Parameters
fdListenThe file descriptor of the TCP listening socket.
[out]*addressThe IPADDR variable to hold the address of the connecting computer.
[out]*portThe variable to receive the remote port of this connection.
accept_timeoutThe number of ticks to wait for a connection (regular TCP::accept()).
negotiation_timeoutThe number of ticks to wait after a regular TCP connection has been accepted and negotiation should be completed in.
Return values
>0The file descriptorof the connected SSL socket
<0The error code for the failure from SSL Error Codes or TCP Socket Status
See also
SSL_connect(IPADDR ip, WORD local_port, WORD remote_port, DWORD timeout, const char * common_name)
SSL_GetSocketRemoteAddr(int i)
SSL_GetSocketRemotePort(int i)
SSL_GetSocketLocalAddr(int i)
SSL_GetSocketLocalPort(int i)
IsSSLfd(int fd)
SSL_setsockoption(int fd, int option)
SSL_clrsockoption(int fd, int option)
SSL_getsockoption(int fd)

◆ SSL_clrsockoption()

int SSL_clrsockoption ( int  fd,
int  option 
)

Clear SSL TCP socket options.

Parameters
fdSocket file descriptor.
optionSocket option to clear: TCP Socket Options.
Returns
A bitmask of the options for the specified socket
See also
SSL_setsockoption()
SSL_getsockoption()

◆ SSL_connect()

int SSL_connect ( IPADDR  ip,
uint16_t  local_port,
uint16_t  remote_port,
uint32_t  timeout,
const char *  common_name,
bool  verifyPeer = false,
bool  waitForNegotiation = true,
SharkSslCAList  caList = nullptr 
)

SSL mirror of the TCP::connect() call.

Parameters
ipthe address to connect to.
local_portThe local port to use. 0 will pick one
remoteportThe remote port to connect to.
timeoutThe number of ticks to wait for a connection.
*common_nameThe comman name to use for checking certificate validity passing in NULL will accept any connection.
verifyPeerShould the client verify the server's certificate against a Certificate Authority list?
waitForNegotiationShould the function wait until the negotiation is complete before returning?
caListThe certificate authority list to use in conjunction with verifyPeer.
Return values
>0The file descripto rof the connected SSL socket
<0The error code for the failure from SSL Error Codes or TCP Socket Status
See also
SSL_accept(int fdListen, IPADDR *address, uint16_t *port, uint16_t accept_timeout, uint16_t negotiation_timeout)
SSL_GetSocketRemoteAddr(int i)
SSL_GetSocketRemotePort(int i)
SSL_GetSocketLocalAddr(int i)
SSL_GetSocketLocalPort(int i)
IsSSLfd(int fd)
SSL_setsockoption(int fd, int option)
SSL_clrsockoption(int fd, int option)
SSL_getsockoption(int fd)

◆ SSL_getsocketerror()

int SSL_getsocketerror ( int  fd)

Returns the socket error state for the specified SSL socket.

Parameters
fdSocket file descriptor.
Returns
The error state for the specified socket

◆ SSL_GetSocketInterface()

int SSL_GetSocketInterface ( int  fd)

Return the network interface associated with a TCP socket.

Parameters
fdSocket file descriptor.
Returns
The network interface number (undefined for listening sockets)

◆ SSL_GetSocketLocalAddr()

IPADDR SSL_GetSocketLocalAddr ( int  fd)

Returns the local address of this connected socket.

This function is used to retrieve the local address of an SSL fd. This function will also work correctly if you pass in an fd that is a TCP connection. This allows you to use one set of code for both normal TCP and SSL connections.

Parameters
fdThe file descriptor to test.
Returns
The local IP address of the TCP or SSL connection, or 0 otherwise.
See also
IsSSLfd(int fd);
SSL_GetSocketRemotePort(int i);
SSL_GetSocketRemoteAddr(int i);
SSL_GetSocketLocalPort(int i);

◆ SSL_GetSocketLocalPort()

uint16_t SSL_GetSocketLocalPort ( int  fd)

Returns the local port of this connected socket.

This function is used to retrieve the local port of an SSL fd. This function will also work correctly if you pass in an fd that is a TCP connection. This allows you to use one set of code for both normal TCP and SSL connections.

Parameters
fdThe file descriptor to test.
Returns
The local port number of TCP or SSL connection, or 0 otherwise.
See also
IsSSLfd(int fd);
SSL_GetSocketRemoteAddr(int i);
SSL_GetSocketLocalAddr(int i);
SSL_GetSocketLocalPort(int i);

◆ SSL_GetSocketRemoteAddr()

IPADDR SSL_GetSocketRemoteAddr ( int  fd)

Returns the remote address of this connected socket.

This function is used to retrieve the remote address of an SSL fd. This function will also work correctly if you pass in an fd that is a TCP connection. This allows you to use one set of code for both normal TCP and SSL connections.

Parameters
fdThe file descriptor to test.
Returns
IP address of the TCP or SSL connection, or 0 otherwise.
See also
IsSSLfd(int fd)
SSL_GetSocketRemotePort(int i)
SSL_GetSocketLocalAddr(int i)
SSL_GetSocketLocalPort(int i)

◆ SSL_GetSocketRemotePort()

uint16_t SSL_GetSocketRemotePort ( int  fd)

Returns the remote port of this connected socket.

This function is used to retrieve the remote port of an SSL fd. This function will also work correctly if you pass in an fd that is a TCP connection. This allows you to use one set of code for both normal TCP and SSL connections.

Parameters
fdThe file descriptor to test.
Returns
The remote port number of TCP or SSL connection, or 0 otherwise.
See also
IsSSLfd(int fd);
SSL_GetSocketRemoteAddr(int i);
SSL_GetSocketLocalAddr(int i);
SSL_GetSocketLocalPort(int i);

◆ SSL_getsockoption()

int SSL_getsockoption ( int  fd)

Returns the options for the specified SSL TCP socket.

Parameters
fdSocket file descriptor.
Returns
A bitmask of the options for the specified socket
See also
SSL_setsockoption()
SSL_clrsockoption()

◆ SSL_makeSecure()

int SSL_makeSecure ( int  fds,
uint32_t  timeout,
const char *  common_name,
bool  verifyPeer = false,
bool  waitForNegotiation = true,
SharkSslCAList  caList = nullptr,
bool  bIsClient = true 
)

Executes the TLS negotiation over a given socket, to establish a secure communication channel through that socket.

Parameters
fdsThe file descriptor for the socket to be secured.
timeoutThe number of ticks to wait for a connection.
*common_nameThe comman name to use for checking certificate validity passing in NULL will accept any connection.
verifyPeerShould the client verify the server's certificate against a Certificate Authority list?
waitForNegotiationShould the function wait until the negotiation is complete before returning?
caListThe certificate authority list to use in conjunction with verifyPeer.
bIsClientPerform the TLS negotiation as the Client and not the Server?
Return values
>0The file descriptor of the connected SSL socket
<0The error code for the failure from SSL Error Codes or TCP Socket Status
See also
SSL_accept(int fdListen, IPADDR *address, uint16_t *port, uint16_t accept_timeout, uint16_t negotiation_timeout)
SSL_GetSocketRemoteAddr(int i)
SSL_GetSocketRemotePort(int i)
SSL_GetSocketLocalAddr(int i)
SSL_GetSocketLocalPort(int i)
IsSSLfd(int fd)
SSL_setsockoption(int fd, int option)
SSL_clrsockoption(int fd, int option)
SSL_getsockoption(int fd)

◆ SSL_negotiate()

int SSL_negotiate ( int  fds,
uint32_t  timeout,
const char *  common_name,
bool  reuseSessionPort = true,
bool  verifyPeer = false,
SharkSslCAList  caList = nullptr,
bool  bIsClient = true 
)

SSL mirror of the TCP::connect() call, but uses an existing TCP file descriptor.

Parameters
fdsThe TCP file descriptor to associate the connection with.
timeoutThe number of ticks to wait for a connection.
*common_nameThe comman name to use for checking certificate validity passing in NULL will accept any connection.
reuseSessionPortShould we look at the port for reuse lookup?
verifyPeerShould the client verify the server's certificate against a Certificate Authority list?
caListThe certificate authority list to use in conjunction with verifyPeer.
bIsClientPerform the TLS negotiation as the Client and not the Server?
Return values
>0The file descriptor of the connected SSL socket
<0The error code for the failure from SSL Error Codes or TCP Socket Status
See also
SSL_accept(int fdListen, IPADDR *address, uint16_t *port, uint16_t accept_timeout, uint16_t negotiation_timeout)
SSL_GetSocketRemoteAddr(int i)
SSL_GetSocketRemotePort(int i)
SSL_GetSocketLocalAddr(int i)
SSL_GetSocketLocalPort(int i)
IsSSLfd(int fd)
SSL_setsockoption(int fd, int option)
SSL_clrsockoption(int fd, int option)
SSL_getsockoption(int fd)

◆ SSL_SetClientCAList()

bool SSL_SetClientCAList ( SharkSslCAList *  CAList)

Attempts to set the Certificate Authority List for the SharkSsl clientCtx

Parameters
CAListA pointer to the certificate list to try and associate with the client.
Return values
TRUESuccessfully set the CA List
FALSEWas not able to set the CA List

◆ SSL_SetServerCAList()

bool SSL_SetServerCAList ( SharkSslCAList *  CAList)

Attempts to set the Certificate Authority List for the SharkSsl serverCtx

Parameters
CAListA pointer to the certificate list to try and associate with the server.
Return values
TRUESuccessfully set the CA List
FALSEWas not able to set the CA List

◆ SSL_setsockoption()

int SSL_setsockoption ( int  fd,
int  option 
)

Set SSL TCP socket options.

Parameters
fdSocket file descriptor.
optionSocket option to set: TCP Socket Options.
Returns
A bitmask of the options for the specified socket
See also
SSL_clrsockoption()
SSL_getsockoption()

◆ SSL_TcpGetLastRxTime()

uint32_t SSL_TcpGetLastRxTime ( int  fd)

SSL mirror of TcpGetLastRxTime().

Parameters
fdThe socket file descriptor.
Returns
The value of system Time Ticks when the last packet was received on the connection.
See also
SSL_TcpSendKeepAlive()
TcpGetLastRxTime()

◆ SSL_TcpSendKeepAlive()

void SSL_TcpSendKeepAlive ( int  fd)

SSL mirror of TcpSendKeepAlive().

Parameters
fdThe socket file descriptor.
See also
SSL_TcpGetLastRxTime()
TcpSendKeepAlive

◆ SSLGetRxBufferSpaceUsed()

uint16_t SSLGetRxBufferSpaceUsed ( int  fd)

Returns the amount of data buffered to be read from the socket.

Parameters
fdThe socket's file descriptor
Return values
>=0The number of bytes available to be read
<0 The requested socket does not exist

◆ SSLGetTxBufferAvailSpace()

uint16_t SSLGetTxBufferAvailSpace ( int  fd)

Returns the amount of data buffered to be read from the socket.

Parameters
fdThe socket's file descriptor
Return values
>=0The number of bytes available to be read
<0 The requested socket does not exist

◆ SSLReadWithTimeout()

int SSLReadWithTimeout ( int  fd,
char *  cp,
int  size,
uint32_t  timeout 
)

SSL mirror of the ReadWithTiemout() function.

This function will block until either the time-out expires or at least one byte is available to be read. This function can be used to read from stdio, TCP sockets, or Serial ports.

Important: This function operates like a read function in that it reads all available bytes and returns. The addition of a time-out does not cause the function to block until the maximum number of bytes specified in the function call is available. The application must use the return value of the function to determine how many bytes were read, and call the function again if necessary.

Parameters
fdThe file descriptor number.
*cpA pointer to the read destination.
sizeMaximum number of bytes to read.
timeoutThe number of timer ticks to wait for data.
Return values
0Invalid buf or size parameters were passed
>0The number of bytes read
TCP_ERR_TIMEOUTNo bytes were read before timeout
TCP_ERR_CLOSINGTCP connection is no longer valid, or the SSLSocket_Record no longer exists
See also
ReadWithTimeout()
SSL_negotiate()