NetBurner 3.3.9
PDF Version
SSL/TLS

Modules

 Onboard Certificate Generation
 
 SSL Error Codes
 

Enumerations

enum class  ExpireRetCodes : unsigned char { ExpireRetCodes::E_CERT_VALID = 0 , ExpireRetCodes::E_CERT_EXPIRED = 1 , ExpireRetCodes::E_BAD_EXPIRATION_VALUE = 2 , ExpireRetCodes::E_NO_SYSTEM_TIME = 3 }
 Return values for SSL_IsCertExpired(). More...
 

Functions

int SSL_accept (int fdListen, IPADDR *address, uint16_t *port, uint16_t timeout, bool waitForNegotiation=true, bool verifyPeer=false, const unsigned char *certBuff=nullptr, uint32_t certBuffSize=0, uint16_t certBuffFormat=SSL_FILETYPE_PEM, const char *commonName=nullptr)
 This call is a mirror of the TCP::accept() call. More...
 
bool SSLSocketsAvail ()
 Returns whether or not there are any sockets available. More...
 
int FreeSSLSockets ()
 Returns the number of currently free SSL sockets. 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 localPort, uint16_t remotePort, uint32_t timeout, const char *commonName, bool verifyPeer=false, bool waitForNegotiation=true, const unsigned char *certBuff=nullptr, uint32_t certBuffSize=0, uint16_t certBuffFormat=SSL_FILETYPE_PEM, int intf=-1)
 SSL mirror of the TCP::connect() call. More...
 
int SSL_makeSecure (int tcpFd, const char *commonName, bool verifyPeer=false, bool waitForNegotiation=true, const unsigned char *certBuff=nullptr, uint32_t certBuffSize=0, uint16_t certBuffFormat=SSL_FILETYPE_PEM, bool bIsClient=true, uint32_t timeout=WAIT_FOREVER)
 SSL mirror of the TCP::connect() call, but uses an existing TCP file descriptor. More...
 
int SSL_negotiate (int tcpFd, const char *common_name, bool reuseSessionPort=true, bool verifyPeer=false, const unsigned char *certBuff=nullptr, uint32_t certBuffSize=0, uint16_t certBuffFormat=SSL_FILETYPE_PEM, bool bIsClient=true)
 Executes the TLS negotiation over a given socket, to establish a secure communication channel through that socket. 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...
 
bool IsSSL_CertNKeyValid (const char *keyPEM, ssize_t keylen, const char *certPEM, ssize_t certlen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Validate candidate certificate and private key. More...
 
bool SSL_AddCertToClientCaList (const unsigned char *certBuff=nullptr, uint32_t certBuffSize=0, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Attempts to add a cert to the Certificate Authority List to the client SSL context. More...
 
bool SSL_AddCertToServerCaList (const unsigned char *certBuff=nullptr, uint32_t certBuffSize=0, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Attempts to add a cert to the Certificate Authority List to the client SSL context. More...
 
bool SSL_ClearClientCaList ()
 Clears certs that have been added to the client's Certificate Authority list. More...
 
bool SSL_ClearServerCaList ()
 Clears certs that have been added to the server's Certificate Authority list. 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...
 
void SslInit ()
 This function initializes the SSL library. More...
 
void SSL_DumpSSLSockets ()
 Prints the current state of all used sockets to stdio.
 
void SSL_ClientReadyCert (const unsigned char *cert, const unsigned char *key, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Add a key and certificate to the client. More...
 
void SSL_ServerReadyCert (const unsigned char *cert, const unsigned char *key, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Add a key and certificate to the server. More...
 
ExpireRetCodes SSL_IsCertExpired (unsigned char *certBuff, int certLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Returns whether the given certificate has expired or not. More...
 
bool SSL_GetIssuerFromCert (unsigned char *certBuff, int certLen, unsigned char *issBuf, int issBufLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Returns the issuer from a certificate blob in the PEM format. More...
 
bool SSL_GetSubjectNameFromCert (unsigned char *certBuff, int certLen, unsigned char *subNamBuf, int subNamBufLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Returns the subject name from a certificate blob in the PEM format. More...
 
bool SSL_GetAltNameFromCert (unsigned char *certBuff, int certLen, unsigned char *altNamBuf, int altNamBufLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Returns an alternate name from a certificate blob in the PEM format. More...
 
bool SSL_GetExpirationDate (unsigned char *certBuff, int certLen, unsigned char *expBuf, int expBufLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Returns the expiration data of the certificate in question. More...
 
bool SSL_GetTimeToExpire (unsigned char *certBuff, int certLen, uint16_t certBuffFormat, time_t &timeToExp)
 Returns whether the given certificate has expired or not. More...
 
bool SSL_GetCnFromCert (unsigned char *certBuff, int certLen, unsigned char *comNamBuf, int comNamBufLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
 Returns the common name from a certificate blob in the PEM format. More...
 
const char * GetCertificatePEM ()
 Function that returns a pointer to the compiled in server certificate. More...
 
int GetCertificateLen ()
 Function that the length of the compiled in server certificate. More...
 
const char * GetPrivateKeyPEM ()
 Function that returns a pointer to the compiled in server key. More...
 
int GetPrivateKeyLen ()
 Function that the length of the compiled in server key. More...
 
void SslSetVerifyPeerClient (bool verifyPeer)
 Sets whether or not verify peer should be enabled on the global SSL client context. More...
 
void SslSetVerifyPeerServer (bool verifyPeer)
 Sets whether or not verify peer should be enabled on the global SSL server context. More...
 
bool SSL_IsCertAddedToClientCaList ()
 Checks to see if any certificates have been added to the global SSL client context. More...
 
bool SSL_IsCertAddedToServerCaList ()
 Checks to see if any certificates have been added to the global SSL server context. More...
 

Variables

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...
 
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...
 
int(* SSL_GetSocketInterface )(int fd)
 Return the network interface associated with an SSL TCP socket. More...
 
int(* SSL_GetRawSocket )(int sslSocketFd)
 Returns the TCP file descriptor associated with an SSL socket file descriptor. More...
 
uint16_t(* SSL_GetTcpRtxCount )(int i)
 Returns the number of re-transmits that have occurred on the specified SSL connection. More...
 
uint32_t(* SSL_TcpGetLastRxTime )(int fd)
 SSL mirror of TcpGetLastRxTime(). More...
 
void(* SSL_TcpSendKeepAlive )(int fd)
 SSL mirror of TcpSendKeepAlive(). More...
 
short(* SSL_TcpGetSocketState )(int fd)
 Return the current state of a SSL TCP socket. More...
 

Detailed Description

The NetBurner SSL/TLS Library

Enumeration Type Documentation

◆ ExpireRetCodes

enum class ExpireRetCodes : unsigned char
strong

Return values for SSL_IsCertExpired().

Enumerator
E_CERT_VALID 

Certificate not expired.

E_CERT_EXPIRED 

Certificate expired.

E_BAD_EXPIRATION_VALUE 

Unable to read the expiration information from the certificate.

E_NO_SYSTEM_TIME 

The system time has not been set.

Function Documentation

◆ FreeSSLSockets()

int FreeSSLSockets ( )

Returns the number of currently free SSL sockets.

Returns
The number of free SSL sockets.

◆ GetCertificateLen()

int GetCertificateLen ( )

Function that the length of the compiled in server certificate.

See the SSL documentation and examples for information on generating a self signed certificate and key. This function can be overridden to provide the ability to install uploaded certificates.

Returns
The length of the compiled in certificate.
See also
GetCertificatePEM()
GetPrivateKeyLen()

Function that the length of the compiled in server certificate.

Return values
Pointerto the found cert

Function that the length of the compiled in server certificate.

◆ 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()
GetCertificateLen()

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.

◆ GetPrivateKeyLen()

int GetPrivateKeyLen ( )

Function that the length of the compiled in server key.

See the SSL documentation and examples for information on generating a self signed certificate and key. This function can be overridden to provide the ability to install uploaded keys.

Returns
The length of the compiled in key.
See also
GetPrivateKeyPEM()
GetCertificateLen()

Function that the length of the compiled in server key.

Return values
Pointerto the found key

Function that the length of the compiled in server key.

◆ 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()
GetPrivateKeyLen()

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.

◆ IsSSL_CertNKeyValid()

bool IsSSL_CertNKeyValid ( const char *  keyPEM,
ssize_t  keylen,
const char *  certPEM,
ssize_t  certlen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Validate candidate certificate and private key.

Determines if the passed in certificate and private key are valid or note.

Parameters
keyPEMA buffer containing the private key
keylenThe length of the buffer containing the private key
certPEMA buffer containing the certificate
certlenThe length of the buffer containing the certificate
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>Certificate and key passed in are valid
<code>false</code>Certificate and/or key passed in are not valid

◆ 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. This will force a new negotiation on every connection. Calling this functhyion will not affect sessions that are currently stored until they have been used to establish a new connection.

The default value used for this purpose on startup is defined in predef.h as the macro SSL_DEFAULT_MAX_SESSION_AGE_TICKS and is set to one hour.

Parameters
newLifetimeTicksHow long (in ticks) to allow an established session to be used.
Returns
Returns previously assigned reuse maximum.

◆ SSL_accept()

int SSL_accept ( int  fdListen,
IPADDR address,
uint16_t *  port,
uint16_t  timeout,
bool  waitForNegotiation = true,
bool  verifyPeer = false,
const unsigned char *  certBuff = nullptr,
uint32_t  certBuffSize = 0,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM,
const char *  commonName = nullptr 
)

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

Parameters
fdListenFile descriptor of the TCP listening socket.
*addressIPADDR variable to hold the address of the connecting computer.
*portVariable to receive the remote port of this connection.
timeoutNumber of system time ticks to wait for a connection (regular TCP::accept()).
waitForNegotiationWait for negotiation to complete. Default is true.
verifyPeerDefault is false. Set to true to verify the client certificate on connect.
certBuffBuffer containing the certificate data. Default is null.
certBuffSizeSize of the buffer containing the certificate data. Default is 0.
certBuffFormatFormat of the certificate buffer. Default is SSL_FILETYPE_PEM.
commonNameCommon name to use for checking certificate validity. Default is null, which will accept any connection.
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_connect()
SSL_GetSocketRemoteAddr()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()
IsSSLfd()
SSL_setsockoption()
SSL_clrsockoption()
SSL_getsockoption()

◆ SSL_AddCertToClientCaList()

bool SSL_AddCertToClientCaList ( const unsigned char *  certBuff = nullptr,
uint32_t  certBuffSize = 0,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Attempts to add a cert to the Certificate Authority List to the client SSL context.

Parameters
certBuffA buffer containing the certificate to add.
certBuffSizeThe size of the cert being passed in.
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>Successfully add the certificate to the CA List
<code>false</code>Was not able to add the certificate to the CA List

◆ SSL_AddCertToServerCaList()

bool SSL_AddCertToServerCaList ( const unsigned char *  certBuff = nullptr,
uint32_t  certBuffSize = 0,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Attempts to add a cert to the Certificate Authority List to the client SSL context.

Parameters
certBuffA buffer containing the certificate to add.
certBuffSizeThe size of the cert being passed in.
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>Successfully add the certificate to the CA List
<code>false</code>Was not able to add the certificate to the CA List

◆ SSL_ClearClientCaList()

bool SSL_ClearClientCaList ( )

Clears certs that have been added to the client's Certificate Authority list.

Return values
<code>true</code>Successfully cleared the Certificate Authority list
<code>false</code>Failed to clear the Certificate Authority list

◆ SSL_ClearServerCaList()

bool SSL_ClearServerCaList ( )

Clears certs that have been added to the server's Certificate Authority list.

Return values
<code>true</code>Successfully cleared the Certificate Authority list
<code>false</code>Failed to clear the Certificate Authority list

◆ SSL_ClientReadyCert()

void SSL_ClientReadyCert ( const unsigned char *  cert,
const unsigned char *  key,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Add a key and certificate to the client.

Parameters
certPointer to the buffer holding the PEM certificate data
keyPointer to the buffer holding the PEM key data
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.

◆ 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  localPort,
uint16_t  remotePort,
uint32_t  timeout,
const char *  commonName,
bool  verifyPeer = false,
bool  waitForNegotiation = true,
const unsigned char *  certBuff = nullptr,
uint32_t  certBuffSize = 0,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM,
int  intf = -1 
)

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

Parameters
ipThe address to connect to.
localPortThe local port to use. 0 will pick one
remotePortThe remote port to connect to.
timeoutThe number of ticks to wait for a connection.
*commonNameThe common 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?
certBuffBuffer containing the certificate data
certBuffSizeSize of the buffer containing the certificate data
certBuffFormatThe format of the certificate buffer
intfOptional local interface number to use for connection
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()
SSL_GetSocketRemoteAddr()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()
IsSSLfd()
SSL_setsockoption()
SSL_clrsockoption()
SSL_getsockoption()

◆ SSL_GetAltNameFromCert()

bool SSL_GetAltNameFromCert ( unsigned char *  certBuff,
int  certLen,
unsigned char *  altNamBuf,
int  altNamBufLen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Returns an alternate name from a certificate blob in the PEM format.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
altNamBufThe buffer to store the alternate name in
altNamBufLenThe length of the buffer where the alternate name will be placed
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>If successfully retrieved the alternate name from the cert
<code>false</code>If unable to retrieved the alternate name from the cert

◆ SSL_GetCnFromCert()

bool SSL_GetCnFromCert ( unsigned char *  certBuff,
int  certLen,
unsigned char *  comNamBuf,
int  comNamBufLen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Returns the common name from a certificate blob in the PEM format.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
comNamBufThe buffer to store the common name in
comNamBufLenThe length of the buffer where the common name will be placed
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>If successfully retrieved the common name from the cert
<code>false</code>If unable to retrieved the common name from the cert

◆ SSL_GetExpirationDate()

bool SSL_GetExpirationDate ( unsigned char *  certBuff,
int  certLen,
unsigned char *  expBuf,
int  expBufLen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Returns the expiration data of the certificate in question.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
expBufThe buffer to store the expiration date in
expBufLenThe length of the buffer where the expiration date will be placed
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>If successfully retrieved the alternate name from the cert
<code>false</code>If unable to retrieved the alternate name from the cert

◆ SSL_GetIssuerFromCert()

bool SSL_GetIssuerFromCert ( unsigned char *  certBuff,
int  certLen,
unsigned char *  issBuf,
int  issBufLen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Returns the issuer from a certificate blob in the PEM format.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
issBufThe buffer to store the issuer in
issBufLenThe length of the buffer where the issuer will be placed
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>If successfully retrieved the issuer from the cert
<code>false</code>If unable to retrieved the issuer from the cert

◆ 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_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_GetSubjectNameFromCert()

bool SSL_GetSubjectNameFromCert ( unsigned char *  certBuff,
int  certLen,
unsigned char *  subNamBuf,
int  subNamBufLen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Returns the subject name from a certificate blob in the PEM format.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
subNamBufThe buffer to store the subject name in
subNamBufLenThe length of the buffer where the subject name will be placed
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>true</code>If successfully retrieved the subject name from the cert
<code>false</code>If unable to retrieved the subject name from the cert

◆ SSL_GetTimeToExpire()

bool SSL_GetTimeToExpire ( unsigned char *  certBuff,
int  certLen,
uint16_t  certBuffFormat,
time_t &  timeToExp 
)

Returns whether the given certificate has expired or not.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
[out]timeToExpThe time the certificate is set to expire
Return values
<code>true</code>If the certificate expiration was found
<code>false</code>If the certificate expiration was not found

◆ SSL_IsCertAddedToClientCaList()

bool SSL_IsCertAddedToClientCaList ( )

Checks to see if any certificates have been added to the global SSL client context.

Certificate Authority certificates can be added to the client context during calls to SSL_connect() or with calls to SSL_AddCertToClientCaList().

Returns
true If a certificate has been added to the certificate authority list.
false If a certificate has not been added to the certificate authority list.

◆ SSL_IsCertAddedToServerCaList()

bool SSL_IsCertAddedToServerCaList ( )

Checks to see if any certificates have been added to the global SSL server context.

Certificate Authority certificates can be added to the server context during calls to SSL_connect() or with calls to SSL_AddCertToServerCaList().

Returns
true If a certificate has been added to the certificate authority list.
false If a certificate has not been added to the certificate authority list.

◆ SSL_IsCertExpired()

ExpireRetCodes SSL_IsCertExpired ( unsigned char *  certBuff,
int  certLen,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Returns whether the given certificate has expired or not.

Parameters
certBuffThe buffer containing the certificate data
certLenThe length of the certificate
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
Return values
<code>ExpireRetCodes::E_CERT_EXPIRED</code>If the certificate has expired
<code>ExpireRetCodes::E_CERT_VALID</code>If the certificate has not expired
<code>ExpireRetCodes::E_BAD_EXPIRATION_VALUE</code>If unable to get the expiration data from the certificate
<code>ExpireRetCodes::E_NO_SYSTEM_TIME</code>If the system time has not been set

◆ SSL_makeSecure()

int SSL_makeSecure ( int  tcpFd,
const char *  commonName,
bool  verifyPeer = false,
bool  waitForNegotiation = true,
const unsigned char *  certBuff = nullptr,
uint32_t  certBuffSize = 0,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM,
bool  bIsClient = true,
uint32_t  timeout = WAIT_FOREVER 
)

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

Parameters
tcpFdThe file descriptor for the socket to be secured.
*commonNameThe common 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?
certBuffBuffer containing the certificate data
certBuffSizeSize of the buffer containing the certificate data
certBuffFormatThe format of the certificate buffer
bIsClientPerform the TLS negotiation as the Client and not the Server?
timeoutThe number of timeticks to wait for completion
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()
SSL_GetSocketRemoteAddr()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()
IsSSLfd()
SSL_setsockoption()
SSL_clrsockoption()
SSL_getsockoption()

◆ SSL_negotiate()

int SSL_negotiate ( int  tcpFd,
const char *  common_name,
bool  reuseSessionPort = true,
bool  verifyPeer = false,
const unsigned char *  certBuff = nullptr,
uint32_t  certBuffSize = 0,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM,
bool  bIsClient = true 
)

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

Parameters
tcpFdThe TCP file descriptor to associate the connection with.
*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?
certBuffBuffer containing the certificate data
certBuffSizeSize of the buffer containing the certificate data
certBuffFormatThe format of the certificate buffer
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()
SSL_GetSocketRemoteAddr()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()
IsSSLfd()
SSL_setsockoption()
SSL_clrsockoption()
SSL_getsockoption()

◆ SSL_ServerReadyCert()

void SSL_ServerReadyCert ( const unsigned char *  cert,
const unsigned char *  key,
uint16_t  certBuffFormat = SSL_FILETYPE_PEM 
)

Add a key and certificate to the server.

Parameters
certPointer to the buffer holding the PEM certificate data
keyPointer to the buffer holding the PEM key data
certBuffFormatThe format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.

◆ 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()

◆ 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

◆ SslInit()

void SslInit ( )

This function initializes the SSL library.

Note: It should only be called in the case that you want to verify peer certificates as a client and need to add the certificates individually. Otherwise, calls to SSL_connect() will automatically call this function for you.

◆ 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()

◆ SslSetVerifyPeerClient()

void SslSetVerifyPeerClient ( bool  verifyPeer)

Sets whether or not verify peer should be enabled on the global SSL client context.

Parameters
verifyPeerTrue if verify should be enabled, or false otherwise.

◆ SslSetVerifyPeerServer()

void SslSetVerifyPeerServer ( bool  verifyPeer)

Sets whether or not verify peer should be enabled on the global SSL server context.

Parameters
verifyPeerTrue if verify should be enabled, or false otherwise.

◆ SSLSocketsAvail()

bool SSLSocketsAvail ( )

Returns whether or not there are any sockets available.

Return values
trueIf there are sockets available.
falseIf there are not any sockets available
See also
FreeSSLSockets()

Variable Documentation

◆ IsSSLfd

BOOL(* IsSSLfd) (int fd) ( int  fd)
extern

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()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()

◆ SSL_GetRawSocket

int(* SSL_GetRawSocket) (int sslSocketFd) ( int  sslSocketFd)
extern

Returns the TCP file descriptor associated with an SSL socket file descriptor.

Parameters
sslSocketFdThe socket file descriptor.
Returns
The TCP file descriptor associated with the SSL socket.
See also
SSL_GetSocketInterface()

◆ SSL_GetSocketInterface

int(* SSL_GetSocketInterface) (int fd) ( int  fd)
extern

Return the network interface associated with an SSL TCP socket.

Parameters
fdThe socket file descriptor.
Returns
The network interface number (undefined for listening sockets)
See also
TcpGetSocketInterface()

◆ SSL_GetSocketLocalAddr

IPADDR(* SSL_GetSocketLocalAddr) (int fd) ( int  fd)
extern

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()
SSL_GetSocketRemotePort()
SSL_GetSocketRemoteAddr()
SSL_GetSocketLocalPort()

◆ SSL_GetSocketLocalPort

uint16_t(* SSL_GetSocketLocalPort) (int fd) ( int  fd)
extern

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()
SSL_GetSocketRemoteAddr()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalPort()

◆ SSL_GetSocketRemoteAddr

IPADDR(* SSL_GetSocketRemoteAddr) (int fd) ( int  fd)
extern

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()
SSL_GetSocketRemotePort()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()

◆ SSL_GetSocketRemotePort

uint16_t(* SSL_GetSocketRemotePort) (int fd) ( int  fd)
extern

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()
SSL_GetSocketRemoteAddr()
SSL_GetSocketLocalAddr()
SSL_GetSocketLocalPort()

◆ SSL_GetTcpRtxCount

uint16_t(* SSL_GetTcpRtxCount) (int i) ( int  i)
extern

Returns the number of re-transmits that have occurred on the specified SSL connection.

Parameters
iThe socket file descriptor.
Returns
The number of system time ticks since the last packet was received on the connection.
See also
GetTcpRtxCount();

◆ SSL_TcpGetLastRxTime

uint32_t(* SSL_TcpGetLastRxTime) (int fd) ( int  fd)
extern

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_TcpGetSocketState

short(* SSL_TcpGetSocketState) (int fd) ( int  fd)
extern

Return the current state of a SSL TCP socket.

Parameters
fdSocket file descriptor.
Returns
The current state of the socket: TCP Socket State
See also
TcpGetSocketState()

◆ SSL_TcpSendKeepAlive

void(* SSL_TcpSendKeepAlive) (int fd) ( int  fd)
extern

SSL mirror of TcpSendKeepAlive().

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