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... | |
The NetBurner SSL Library
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.
Function that returns a pointer to the compiled in server certificate.
Pointer | to the found cert |
Function that returns a pointer to the compiled in server certificate.
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.
Function that returns a pointer to the compiled in server key.
Pointer | to the found key |
Function that returns a pointer to the compiled in server key.
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.
fd | The file descriptor to test. |
TRUE | If it is an SSL fd |
FALSE | If it is not an SSL fd or if there was an error |
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.
newLifetimeTicks |
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.
fdListen | The file descriptor of the TCP listening socket. | |
[out] | *address | The IPADDR variable to hold the address of the connecting computer. |
[out] | *port | The variable to receive the remote port of this connection. |
accept_timeout | The number of ticks to wait for a connection (regular TCP::accept()). | |
negotiation_timeout | The number of ticks to wait after a regular TCP connection has been accepted and negotiation should be completed in. |
>0 | The file descriptorof the connected SSL socket |
<0 | The error code for the failure from SSL Error Codes or TCP Socket Status |
int SSL_clrsockoption | ( | int | fd, |
int | option | ||
) |
Clear SSL TCP socket options.
fd | Socket file descriptor. |
option | Socket option to clear: TCP Socket Options. |
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.
ip | the address to connect to. |
local_port | 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. |
*common_name | The comman 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? |
caList | The certificate authority list to use in conjunction with verifyPeer. |
>0 | The file descripto rof the connected SSL socket |
<0 | The error code for the failure from SSL Error Codes or TCP Socket Status |
int SSL_getsocketerror | ( | int | fd | ) |
Returns the socket error state for the specified SSL socket.
fd | Socket file descriptor. |
int SSL_GetSocketInterface | ( | int | fd | ) |
Return the network interface associated with a TCP socket.
fd | Socket file descriptor. |
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.
fd | The file descriptor to test. |
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.
fd | The file descriptor to test. |
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.
fd | The file descriptor to test. |
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.
fd | The file descriptor to test. |
int SSL_getsockoption | ( | int | fd | ) |
Returns the options for the specified SSL TCP socket.
fd | Socket file descriptor. |
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.
fds | The file descriptor for the socket to be secured. |
timeout | The number of ticks to wait for a connection. |
*common_name | The comman 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? |
caList | The certificate authority list to use in conjunction with verifyPeer. |
bIsClient | Perform the TLS negotiation as the Client and not the Server? |
>0 | The file descriptor of the connected SSL socket |
<0 | The error code for the failure from SSL Error Codes or TCP Socket Status |
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.
fds | The TCP file descriptor to associate the connection with. |
timeout | The number of ticks to wait for a connection. |
*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? |
caList | The certificate authority list to use in conjunction with verifyPeer. |
bIsClient | Perform the TLS negotiation as the Client and not the Server? |
>0 | The file descriptor of the connected SSL socket |
<0 | The error code for the failure from SSL Error Codes or TCP Socket Status |
bool SSL_SetClientCAList | ( | SharkSslCAList * | CAList | ) |
Attempts to set the Certificate Authority List for the SharkSsl clientCtx
CAList | A pointer to the certificate list to try and associate with the client. |
TRUE | Successfully set the CA List |
FALSE | Was not able to set the CA List |
bool SSL_SetServerCAList | ( | SharkSslCAList * | CAList | ) |
Attempts to set the Certificate Authority List for the SharkSsl serverCtx
CAList | A pointer to the certificate list to try and associate with the server. |
TRUE | Successfully set the CA List |
FALSE | Was not able to set the CA List |
int SSL_setsockoption | ( | int | fd, |
int | option | ||
) |
Set SSL TCP socket options.
fd | Socket file descriptor. |
option | Socket option to set: TCP Socket Options. |
uint32_t SSL_TcpGetLastRxTime | ( | int | fd | ) |
SSL mirror of TcpGetLastRxTime().
fd | The socket file descriptor. |
void SSL_TcpSendKeepAlive | ( | int | fd | ) |
SSL mirror of TcpSendKeepAlive().
fd | The socket file descriptor. |
uint16_t SSLGetRxBufferSpaceUsed | ( | int | fd | ) |
Returns the amount of data buffered to be read from the socket.
fd | The socket's file descriptor |
>=0 | The number of bytes available to be read |
< | 0 The requested socket does not exist |
uint16_t SSLGetTxBufferAvailSpace | ( | int | fd | ) |
Returns the amount of data buffered to be read from the socket.
fd | The socket's file descriptor |
>=0 | The number of bytes available to be read |
< | 0 The requested socket does not exist |
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.
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. |
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 |