The NetBurner SSL/TLS Library. See SSL/TLS Programming Guide and examples in the examples/SSL folder. More...

Topics
	ACME Certificate Generation
	Request valid public certificates from an ACME certificate authority for devices with a public IP and DNS.

	Onboard Self-Signed Certificate Generation
	See On-board Cert Generation - Simple and other examples in the examples/SSL folder.

	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_connect (IPADDR ip, 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.

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)
	Old version of SSL_Connect with local port.

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.

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.

int	SSLReadWithTimeout (int fd, char *cp, int size, uint32_t timeout)
	SSL mirror of the ReadWithTiemout() function.

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.

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.

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.

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.

bool	SSL_ClearClientCaList ()
	Clears certs that have been added to the client's Certificate Authority list.

bool	SSL_ClearServerCaList ()
	Clears certs that have been added to the server's Certificate Authority list.

uint16_t	SSLGetRxBufferSpaceUsed (int fd)
	Returns the amount of data buffered to be read from the socket.

uint16_t	SSLGetTxBufferAvailSpace (int fd)
	Returns the amount of data buffered to be read from the socket.

void	SslInit ()
	This function initializes the SSL library.

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.

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.

ExpireRetCodes	SSL_IsCertExpired (unsigned char *certBuff, int certLen, uint16_t certBuffFormat=SSL_FILETYPE_PEM)
	Returns whether the given certificate has expired or not.

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.

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.

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.

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.

bool	SSL_GetTimeToExpire (unsigned char *certBuff, int certLen, uint16_t certBuffFormat, time_t &timeToExp)
	Returns whether the given certificate has expired or not.

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.

const char *	GetCertificatePEM ()
	Function that returns a pointer to the compiled in server certificate.

int	GetCertificateLen ()
	Function that returns the length of the compiled in server certificate.

const char *	GetPrivateKeyPEM ()
	Function that returns a pointer to the compiled in server key.

int	GetPrivateKeyLen ()
	Function that the length of the compiled in server key.

void	SslSetVerifyPeerClient (bool verifyPeer)
	Sets whether or not verify peer should be enabled on the global SSL client context.

void	SslSetVerifyPeerServer (bool verifyPeer)
	Sets whether or not verify peer should be enabled on the global SSL server context.

bool	SSL_IsCertAddedToClientCaList ()
	Checks to see if any certificates have been added to the global SSL client context.

bool	SSL_IsCertAddedToServerCaList ()
	Checks to see if any certificates have been added to the global SSL server context.

SSL Server Functions
BOOL(*	IsSSLfd )(int fd)
	Returns whether or not a file descriptor is an SSL file descriptor.

int(*	SSL_GetRawSocket )(int sslSocketFd)
	Returns the TCP file descriptor associated with an SSL socket file descriptor.

int(*	SSL_setsockoption )(int fd, int option)
	Set SSL TCP socket options.

int(*	SSL_clrsockoption )(int fd, int option)
	Clear SSL TCP socket options.

int(*	SSL_getsockoption )(int fd)
	Returns the options for the specified SSL TCP socket.

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.

IPADDR	SSL_GetSocketRemoteAddr (int fd)
	Returns the remote address of this connected socket.

uint16_t	SSL_GetSocketRemotePort (int fd)
	Returns the remote port of this connected socket.

IPADDR	SSL_GetSocketLocalAddr (int fd)
	Returns the local address of this connected socket.

uint16_t	SSL_GetSocketLocalPort (int fd)
	Returns the local port of this connected socket.

int	SSL_GetSocketInterface (int fd)
	Return the network interface associated with an SSL TCP socket.

uint16_t	SSL_GetTcpRtxCount (int fd)
	Return the current state of a SSL TCP socket.

uint32_t	SSL_TcpGetLastRxTime (int fd)
	SSL mirror of TcpGetLastRxTime().

uint32_t	SSL_TcpGetLastRxInterval (int fd)
	SSL mirror of TcpGetLastRxInterval().

void	SSL_TcpSendKeepAlive (int fd)
	SSL mirror of TcpSendKeepAlive().

bool	SSLSocketsAvail ()
	Returns whether or not there are any sockets available.

int	FreeSSLSockets ()
	Returns the number of currently free SSL sockets.

SSL socket option functions
int	SSL_getsocketerror (int fd)
	Returns the socket error state for the specified SSL socket.

Detailed Description

The NetBurner SSL/TLS Library. See SSL/TLS Programming Guide and examples in the examples/SSL folder.

#include< ssl.h >

Enumeration Type Documentation

◆ ExpireRetCodes

enum class ExpireRetCodes : unsigned char

strong

#include <ssl.h>

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

#include <ssl.h>

Returns the number of currently free SSL sockets.

Returns: The number of free SSL sockets.

◆ GetCertificateLen()

int GetCertificateLen ( )

#include <ssl.h>

Function that returns 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()

◆ GetCertificatePEM()

const char * GetCertificatePEM ( )

#include <ssl.h>

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

◆ GetPrivateKeyLen()

int GetPrivateKeyLen ( )

#include <ssl.h>

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

◆ GetPrivateKeyPEM()

const char * GetPrivateKeyPEM ( )

#include <ssl.h>

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

◆ IsSSL_CertNKeyValid()

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

#include <ssl.h>

Validate candidate certificate and private key.

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

Parameters

keyPEM	A buffer containing the private key
keylen	The length of the buffer containing the private key
certPEM	A buffer containing the certificate
certlen	The length of the buffer containing the certificate
certBuffFormat	The 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 )

#include <ssl.h>

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

newLifetimeTicks How 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 )

#include <ssl.h>

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

Parameters

fdListen	File descriptor of the TCP listening socket.
*address	IPADDR variable to hold the address of the connecting computer.
*port	Variable to receive the remote port of this connection.
timeout	Number of system time ticks to wait for a connection (regular TCP::accept()).
waitForNegotiation	Wait for negotiation to complete. Default is true.
verifyPeer	Default is false. Set to true to verify the client certificate on connect.
certBuff	Buffer containing the certificate data. Default is null.
certBuffSize	Size of the buffer containing the certificate data. Default is 0.
certBuffFormat	Format of the certificate buffer. Default is SSL_FILETYPE_PEM.
commonName	Common name to use for checking certificate validity. Default is null, which will accept any connection.

Return values

>0	The file descriptor of the connected SSL socket
<0	The 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 )

#include <ssl.h>

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

Parameters

certBuff	A buffer containing the certificate to add.
certBuffSize	The size of the cert being passed in.
certBuffFormat	The 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 )

#include <ssl.h>

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

Parameters

certBuff	A buffer containing the certificate to add.
certBuffSize	The size of the cert being passed in.
certBuffFormat	The 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 ( )

#include <ssl.h>

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

#include <ssl.h>

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 )

#include <ssl.h>

Add a key and certificate to the client.

Parameters

cert	Pointer to the buffer holding the PEM certificate data
key	Pointer to the buffer holding the PEM key data
certBuffFormat	The format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.

◆ SSL_connect() [1/2]

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 )

#include <ssl.h>

Old version of SSL_Connect with local port.

Parameters

ip	The address to connect to.
localPort	The local port to use. 0 will pick one
remotePort	The remote port to connect to.
timeout	The number of ticks to wait for a connection.
*commonName	The common name to use for checking certificate validity passing in NULL will accept any connection.
verifyPeer	Should the client verify the server's certificate against a Certificate Authority list?
waitForNegotiation	Should the function wait until the negotiation is complete before returning?
certBuff	Buffer containing the certificate data
certBuffSize	Size of the buffer containing the certificate data
certBuffFormat	The format of the certificate buffer
intf	Optional local interface number to use for connection

Return values

>0	The file descriptor of the connected SSL socket
<0	The 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_connect() [2/2]

int SSL_connect	(	IPADDR	ip,
		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 )

#include <ssl.h>

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

Parameters

ip	The address to connect to.
remotePort	The remote port to connect to.
timeout	The number of ticks to wait for a connection.
*commonName	The common name to use for checking certificate validity passing in NULL will accept any connection.
verifyPeer	Should the client verify the server's certificate against a Certificate Authority list?
waitForNegotiation	Should the function wait until the negotiation is complete before returning?
certBuff	Buffer containing the certificate data
certBuffSize	Size of the buffer containing the certificate data
certBuffFormat	The format of the certificate buffer
intf	Optional local interface number to use for connection

Return values

>0	The file descriptor of the connected SSL socket
<0	The 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 )

#include <ssl.h>

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

Parameters

certBuff	The buffer containing the certificate data
certLen	The length of the certificate
altNamBuf	The buffer to store the alternate name in
altNamBufLen	The length of the buffer where the alternate name will be placed
certBuffFormat	The 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 )

#include <ssl.h>

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

Parameters

certBuff	The buffer containing the certificate data
certLen	The length of the certificate
comNamBuf	The buffer to store the common name in
comNamBufLen	The length of the buffer where the common name will be placed
certBuffFormat	The 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 )

#include <ssl.h>

Returns the expiration data of the certificate in question.

Parameters

certBuff	The buffer containing the certificate data
certLen	The length of the certificate
expBuf	The buffer to store the expiration date in
expBufLen	The length of the buffer where the expiration date will be placed
certBuffFormat	The 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 )

#include <ssl.h>

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

Parameters

certBuff	The buffer containing the certificate data
certLen	The length of the certificate
issBuf	The buffer to store the issuer in
issBufLen	The length of the buffer where the issuer will be placed
certBuffFormat	The 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 )

#include <ssl.h>

Returns the socket error state for the specified SSL socket.

Parameters

fd	Socket file descriptor.

Returns: The error state for the specified socket

◆ SSL_GetSocketInterface()

int SSL_GetSocketInterface ( int fd )

inline

#include <ssl.h>

Return the network interface associated with an SSL TCP socket.

Parameters

fd	The socket file descriptor.

Returns: The network interface number (undefined for listening sockets)

See also: TcpGetSocketInterface()

◆ SSL_GetSocketLocalAddr()

IPADDR SSL_GetSocketLocalAddr ( int fd )

inline

#include <ssl.h>

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

fd	The 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 )

inline

#include <ssl.h>

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

fd	The 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 )

inline

#include <ssl.h>

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

fd	The 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 )

inline

#include <ssl.h>

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

fd	The 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_GetSubjectNameFromCert()

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

#include <ssl.h>

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

Parameters

certBuff	The buffer containing the certificate data
certLen	The length of the certificate
subNamBuf	The buffer to store the subject name in
subNamBufLen	The length of the buffer where the subject name will be placed
certBuffFormat	The 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_GetTcpRtxCount()

uint16_t SSL_GetTcpRtxCount ( int fd )

inline

#include <ssl.h>

Return the current state of a SSL TCP socket.

Parameters

fd	Socket file descriptor.

Returns: The current state of the socket: TCP Socket State

See also: TcpGetSocketState()

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

Parameters

fd	The socket file descriptor.

Returns: The number of system time ticks since the last packet was received on the connection.

See also: GetTcpRtxCount();

◆ SSL_GetTimeToExpire()

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

#include <ssl.h>

Returns whether the given certificate has expired or not.

Parameters

	certBuff	The buffer containing the certificate data
	certLen	The length of the certificate
	certBuffFormat	The format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.
[out]	timeToExp	The 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 ( )

#include <ssl.h>

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

#include <ssl.h>

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 )

#include <ssl.h>

Returns whether the given certificate has expired or not.

Parameters

certBuff	The buffer containing the certificate data
certLen	The length of the certificate
certBuffFormat	The 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 )

#include <ssl.h>

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

Parameters

tcpFd	The file descriptor for the socket to be secured.
*commonName	The common name to use for checking certificate validity passing in NULL will accept any connection.
verifyPeer	Should the client verify the server's certificate against a Certificate Authority list?
waitForNegotiation	Should the function wait until the negotiation is complete before returning?
certBuff	Buffer containing the certificate data
certBuffSize	Size of the buffer containing the certificate data
certBuffFormat	The format of the certificate buffer
bIsClient	Perform the TLS negotiation as the Client and not the Server?
timeout	The number of timeticks to wait for completion

Return values

>0	The file descriptor of the connected SSL socket
<0	The 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 )

#include <ssl.h>

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

Parameters

tcpFd	The TCP file descriptor to associate the connection with.
*common_name	The comman name to use for checking certificate validity passing in NULL will accept any connection.
reuseSessionPort	Should we look at the port for reuse lookup?
verifyPeer	Should the client verify the server's certificate against a Certificate Authority list?
certBuff	Buffer containing the certificate data
certBuffSize	Size of the buffer containing the certificate data
certBuffFormat	The format of the certificate buffer
bIsClient	Perform the TLS negotiation as the Client and not the Server?

Return values

>0	The file descriptor of the connected SSL socket
<0	The 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 )

#include <ssl.h>

Add a key and certificate to the server.

Parameters

cert	Pointer to the buffer holding the PEM certificate data
key	Pointer to the buffer holding the PEM key data
certBuffFormat	The format of the cert being passed in. Either SSL_FILETYPE_PEM or WOLFSSL_FILETYPE_ASN1.

◆ SSL_TcpGetLastRxInterval()

uint32_t SSL_TcpGetLastRxInterval ( int fd )

inline

#include <ssl.h>

SSL mirror of TcpGetLastRxInterval().

Parameters

fd	The socket file descriptor.

Returns: The number of system Time Ticks since the last packet was received on the connection.

See also: SSL_TcpSendKeepAlive(); TcpGetLastRxInterval()

◆ SSL_TcpGetLastRxTime()

uint32_t SSL_TcpGetLastRxTime ( int fd )

inline

#include <ssl.h>

SSL mirror of TcpGetLastRxTime().

Parameters

fd	The 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 )

inline

#include <ssl.h>

SSL mirror of TcpSendKeepAlive().

Parameters

fd	The socket file descriptor.

See also: SSL_TcpGetLastRxTime(); TcpSendKeepAlive()

◆ SSLGetRxBufferSpaceUsed()

uint16_t SSLGetRxBufferSpaceUsed ( int fd )

#include <ssl.h>

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

Parameters

fd	The socket's file descriptor

Return values

>=0	The number of bytes available to be read
<	0 The requested socket does not exist

◆ SSLGetTxBufferAvailSpace()

uint16_t SSLGetTxBufferAvailSpace ( int fd )

#include <ssl.h>

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

Parameters

fd	The socket's file descriptor

Return values

>=0	The number of bytes available to be read
<	0 The requested socket does not exist

◆ SslInit()

void SslInit ( )

#include <ssl.h>

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 )

#include <ssl.h>

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

fd	The file descriptor number.
*cp	A pointer to the read destination.
size	Maximum number of bytes to read.
timeout	The number of timer ticks to wait for data.

Return values

0	Invalid buf or size parameters were passed
>0	The number of bytes read
TCP_ERR_TIMEOUT	No bytes were read before timeout
TCP_ERR_CLOSING	TCP connection is no longer valid, or the SSLSocket_Record no longer exists

See also: ReadWithTimeout(); SSL_negotiate()

◆ SslSetVerifyPeerClient()

void SslSetVerifyPeerClient ( bool verifyPeer )

#include <ssl.h>

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

Parameters

verifyPeer True if verify should be enabled, or false otherwise.

◆ SslSetVerifyPeerServer()

void SslSetVerifyPeerServer ( bool verifyPeer )

#include <ssl.h>

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

Parameters

verifyPeer True if verify should be enabled, or false otherwise.

◆ SSLSocketsAvail()

bool SSLSocketsAvail ( )

#include <ssl.h>

Returns whether or not there are any sockets available.

Return values

true	If there are sockets available.
false	If there are not any sockets available

See also: FreeSSLSockets()

Variable Documentation

◆ IsSSLfd

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

extern

#include <ssl.h>

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

fd	The file descriptor to test.

Return values

TRUE	If it is an SSL fd
FALSE	If it is not an SSL fd or if there was an error

See also: SSL_GetSocketRemoteAddr(); SSL_GetSocketRemotePort(); SSL_GetSocketLocalAddr(); SSL_GetSocketLocalPort()

◆ SSL_clrsockoption

int(* SSL_clrsockoption) (int fd, int option)	(	int	fd,
		int	option )

extern

#include <ssl.h>

Clear SSL TCP socket options.

Parameters

fd	Socket file descriptor.
option	Socket option to clear: TCP Socket Options.

Returns: A bitmask of the options for the specified socket

See also: SSL_setsockoption(); SSL_getsockoption()

◆ SSL_GetRawSocket

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

extern

#include <ssl.h>

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

Parameters

sslSocketFd The socket file descriptor.

Returns: The TCP file descriptor associated with the SSL socket.

See also: SSL_GetSocketInterface()

◆ SSL_getsockoption

int(* SSL_getsockoption) (int fd) ( int fd )

extern

#include <ssl.h>

Returns the options for the specified SSL TCP socket.

Parameters

fd	Socket file descriptor.

Returns: A bitmask of the options for the specified socket

See also: SSL_setsockoption(); SSL_clrsockoption()

◆ SSL_setsockoption

int(* SSL_setsockoption) (int fd, int option)	(	int	fd,
		int	option )

extern

#include <ssl.h>

Set SSL TCP socket options.

Parameters

fd	Socket file descriptor.
option	Socket option to set: TCP Socket Options.

Returns: A bitmask of the options for the specified socket

See also: SSL_clrsockoption(); SSL_getsockoption()

Topics

Enumerations

Functions

SSL Server Functions

SSL socket option functions

Detailed Description

Enumeration Type Documentation

◆ ExpireRetCodes

Function Documentation

◆ FreeSSLSockets()

◆ GetCertificateLen()

◆ GetCertificatePEM()

◆ GetPrivateKeyLen()

◆ GetPrivateKeyPEM()

◆ IsSSL_CertNKeyValid()

◆ SetMaxSessionReuseTime()

◆ SSL_accept()

◆ SSL_AddCertToClientCaList()

◆ SSL_AddCertToServerCaList()

◆ SSL_ClearClientCaList()

◆ SSL_ClearServerCaList()

◆ SSL_ClientReadyCert()

◆ SSL_connect() [1/2]

◆ SSL_connect() [2/2]

◆ SSL_GetAltNameFromCert()

◆ SSL_GetCnFromCert()

◆ SSL_GetExpirationDate()

◆ SSL_GetIssuerFromCert()

◆ SSL_getsocketerror()

◆ SSL_GetSocketInterface()

◆ SSL_GetSocketLocalAddr()

◆ SSL_GetSocketLocalPort()

◆ SSL_GetSocketRemoteAddr()

◆ SSL_GetSocketRemotePort()

◆ SSL_GetSubjectNameFromCert()

◆ SSL_GetTcpRtxCount()

◆ SSL_GetTimeToExpire()

◆ SSL_IsCertAddedToClientCaList()

◆ SSL_IsCertAddedToServerCaList()

◆ SSL_IsCertExpired()

◆ SSL_makeSecure()

◆ SSL_negotiate()

◆ SSL_ServerReadyCert()

◆ SSL_TcpGetLastRxInterval()

◆ SSL_TcpGetLastRxTime()

◆ SSL_TcpSendKeepAlive()

◆ SSLGetRxBufferSpaceUsed()

◆ SSLGetTxBufferAvailSpace()

◆ SslInit()

◆ SSLReadWithTimeout()

◆ SslSetVerifyPeerClient()

◆ SslSetVerifyPeerServer()

◆ SSLSocketsAvail()

Variable Documentation

◆ IsSSLfd

◆ SSL_clrsockoption

◆ SSL_GetRawSocket

◆ SSL_getsockoption

◆ SSL_setsockoption