Core API

Detailed Description

The transport agnostic SharkSSL API.

The SharkSSL API provides a unique design that enables anything from bare-metal embedded devices to high end non embedded systems to include a very fast and compact secure socket layer. The core API documentation includes information on the SharkSSL transport agnostic API.

Most of the SharkSSL's core API is used internally by the SharkSSL socket example lib (selib). It is easier to use selib, however, You must use the core functions if you are working with a nontraditional TCP/IP stack or if you provide encryption for another type of networking than TCP/IP.

Macros
#define	SHARKSSL_KEY_UPDATE_NOT_REQUESTED   0
	Updates the local write keys without requesting a reciprocal update of the peer's write keys. More...
#define	SHARKSSL_KEY_UPDATE_REQUESTED   1
	Updates the local write keys and requests a reciprocal update of the peer's write keys. More...
#define	SharkSslCon_getAlertData(o)   SharkSslCon_getEncData(o)
	This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt. More...
#define	SharkSslCon_getAlertDataLen(o)   SharkSslCon_getEncDataLen(o)
	This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt. More...

Enumerations
enum	SharkSslCon_RetVal {   SharkSslCon_Error = 1 , SharkSslCon_AllocationError , SharkSslCon_Decrypted , SharkSslCon_Handshake ,   SharkSslCon_NeedMoreData , SharkSslCon_AlertSend , SharkSslCon_AlertRecv , SharkSslCon_Encrypted ,   SharkSslCon_HandshakeNotComplete , SharkSslCon_CertificateError }
	The SharkSslCon_decrypt and SharkSslCon_encrypt return values. More...

Functions
SharkSslCon_RetVal	SharkSslCon_decrypt (SharkSslCon *o, U16 readLen)
	Decrypt the received data copied into the SharkSslCon receive buffer (the buffer returned by SharkSslCon_getBuf). More...
SharkSslCon_RetVal	SharkSslCon_encrypt (SharkSslCon *o, U8 *buf, U16 maxLen)
	Encrypt the data provided by parameter 'buf' or encrypt data in the SharkSslCon send buffer. More...
SHARKSSL_API U8	SharkSslCon_keyUpdate (SharkSslCon *o, U8 requestUpdate)
	Creates a TLS 1.3 KeyUpdate message and advances the local write keys. More...
U8	SharkSslCon_isHandshakeComplete (SharkSslCon *o)
	Returns the following values: More...
U8	SharkSslCon_encryptMore (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCon_encrypt. More...
U8	SharkSslCon_decryptMore (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_Decrypted returned by function SharkSslCon_decrypt. More...
U8 *	SharkSslCon_getBuf (SharkSslCon *o)
	Returns a pointer to the SharkSslCon input/receive buffer. More...
U16	SharkSslCon_getBufLen (SharkSslCon *o)
	Returns the number of bytes currently available at the pointer returned by SharkSslCon_getBuf. More...
U16	SharkSslCon_copyDecData (SharkSslCon *o, U8 *buf, U16 maxLen)
	Copy decoded data to 'buf'. More...
SHARKSSL_API U16	SharkSslCon_getDecData (SharkSslCon *o, U8 **bufPtr)
	Get a pointer to the decoded data. More...
U8 *	SharkSslCon_getHandshakeData (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_Handshake returned by function SharkSslCon_encrypt. More...
U16	SharkSslCon_getHandshakeDataLen (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_Handshake returned by function SharkSslCon_decrypt. More...
U16	SharkSslCon_setHandshakeDataSent (SharkSslCon *o, U16 length)
	This function is used in conjunction with SharkSslCon_getHandshakeData. More...
U8 *	SharkSslCon_getEncData (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCon_encrypt. More...
U16	SharkSslCon_getEncDataLen (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCon_encrypt. More...
U8 *	SharkSslCon_getEncBufPtr (SharkSslCon *o)
	This function is used in conjunction with SharkSslCon_encrypt when using the zero copy send API. More...
U16	SharkSslCon_getEncBufSize (SharkSslCon *o)
	Returns the length of the buffer returned by SharkSslCon_getEncBufPtr.
U8	SharkSslCon_getAlertLevel (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt or in conjunction with state SharkSslCon_AlertRecv returned by function SharkSslCon_decrypt. More...
U8	SharkSslCon_getAlertDescription (SharkSslCon *o)
	This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt or in conjunction with state SharkSslCon_AlertRecv returned by function SharkSslCon_decrypt. More...

Macro Definition Documentation

SHARKSSL_KEY_UPDATE_NOT_REQUESTED

#define SHARKSSL_KEY_UPDATE_NOT_REQUESTED   0

Updates the local write keys without requesting a reciprocal update of the peer's write keys.

The peer still updates its read keys when it receives the KeyUpdate. This value is also used when replying to a peer that sent SHARKSSL_KEY_UPDATE_REQUESTED, preventing an endless KeyUpdate exchange.

SHARKSSL_KEY_UPDATE_REQUESTED

#define SHARKSSL_KEY_UPDATE_REQUESTED   1

Updates the local write keys and requests a reciprocal update of the peer's write keys.

The peer must reply with a KeyUpdate containing SHARKSSL_KEY_UPDATE_NOT_REQUESTED before sending its next application data.

SharkSslCon_getAlertData

#define SharkSslCon_getAlertData

(

o

)

SharkSslCon_getEncData(o)

This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt.

The function returns a pointer to the alert data that must be sent to the peer side.

See also

SharkSslCon_getAlertDataLen

SharkSslCon_getAlertDataLen

#define SharkSslCon_getAlertDataLen

(

o

)

SharkSslCon_getEncDataLen(o)

This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt.

The function returns the length of the alert data that must be sent to the peer side.

See also

SharkSslCon_getAlertData

Enumeration Type Documentation

SharkSslCon_RetVal

enum SharkSslCon_RetVal

The SharkSslCon_decrypt and SharkSslCon_encrypt return values.

Enumerator
SharkSslCon_Error	Indicates general errors, including configuration errors.
SharkSslCon_AllocationError	The memory pool is too small.
SharkSslCon_Decrypted	Returned when a block of received data has been successfully decrypted. selib.c code snippet: case SharkSslCon_Decrypted: baAssert(buf); readLen = SharkSslCon_getDecData(s, buf); if (SharkSslCon_decryptMore(s) && (readLen == 0)) { break; /* decrypt next record */ } return readLen; See also SharkSslCon_getDecData
SharkSslCon_Handshake	Returned when an SSL/TLS handshake message has been received or is to be sent. During this phase, one must call SharkSslCon_getHandshakeData and SharkSslCon_getHandshakeDataLen, send the handshake data to the peer, and report the accepted length using SharkSslCon_setHandshakeDataSent. selib.c code snippet: case SharkSslCon_Handshake:
SharkSslCon_NeedMoreData	Returned when SharkSSL holds an incomplete SSL/TLS record or when the connection is initially established and the readLen parameter is zero. selib.c code snippet: case SharkSslCon_NeedMoreData: readLen = se_recv(sock, (void*)SharkSslCon_getBuf(s), SharkSslCon_getBufLen(s), timeout); if (readLen <= 0) return readLen; /* 0 (no data) or -1 (socket error) */ if (NULL == buf) /* seSec_handshake */ { NTD xprintf(("received %d handshake bytes\n", readLen)); } break; /* decrypt next record */ See also SharkSslCon_getBuf and SharkSslCon_getBufLen
SharkSslCon_AlertSend	Returned when an SSL/TLS alert message must be sent to the peer side. The error code, which must be sent to the peer, indicates that SharkSSL was unable to decode the data sent from the peer. selib.c code snippet: case SharkSslCon_AlertSend: /* SSL alert message sent to peer. */ /* One can retrieve the alert level and description through: * SharkSslCon_getAlertLevel(s) * SharkSslCon_getAlertDescription(s) */ xprintf(("SharkSSL : Sent alert message, level %d, description %d\n", SharkSslCon_getAlertLevel(s), SharkSslCon_getAlertDescription(s))); baAssert(SharkSslCon_getAlertDataLen(s)); se_send(sock, (void*)SharkSslCon_getAlertData(s), SharkSslCon_getAlertDataLen(s)); break; case SharkSslCon_AlertRecv: /* Alert message received from peer. */ /* One can retrieve the alert level & description through: * SharkSslCon_getAlertLevel(s) * SharkSslCon_getAlertDescription(s) */ if ((SharkSslCon_getAlertLevel(s) == SHARKSSL_ALERT_LEVEL_WARNING) && (SharkSslCon_getAlertDescription(s)==SHARKSSL_ALERT_CLOSE_NOTIFY)) { xprintf(("SharkSSL : Received closure alert \n")); } else { xprintf(("SharkSSL : Received alert, level %d, description %d\n", SharkSslCon_getAlertLevel(s), SharkSslCon_getAlertDescription(s))); } break; case SharkSslCon_Error: xprintf(("SharkSSL : Internal failure\n")); break; case SharkSslCon_CertificateError: xprintf(("SharkSSL : Certificate error\n")); break; case SharkSslCon_AllocationError: xprintf(("SharkSSL : Allocation error\n")); break; default: baAssert(0); return -1; See also SharkSslCon_getAlertData and SharkSslCon_getAlertDataLen
SharkSslCon_AlertRecv	SharkSSL received an SSL/TLS alert message from the peer, which means that the peer either failed to decode the message from SharkSSL or the peer entered an exception state. See also SharkSslCon_getAlertLevel and SharkSslCon_getAlertDescription
SharkSslCon_Encrypted	SharkSSL has successfully decrypted a chunk of data. The data is available in the SharkSSL receive buffer, which is returned by function SharkSslCon_getEncData. The length is returned by function SharkSslCon_getEncDataLen. selib.c code snippet: case SharkSslCon_Encrypted: nb = SharkSslCon_getEncDataLen(s); if (nb != se_send(sock, (void*)SharkSslCon_getEncData(s), nb)) { return -1; } /* * Returns true if the unencrypted buffer is larger than * what fits into the SharkSSL output buffer. SharkSSL * solves this by breaking the buffer into multiple chunks. */ if (SharkSslCon_encryptMore(s)) { break; } return maxLen; /* All data encrypted and sent. */
SharkSslCon_HandshakeNotComplete	An error condition returned by function SharkSslCon_encrypt if the SSL handshake is not completed. You cannot send encrypted data before completing the handshake phase.
SharkSslCon_CertificateError	Unrecognized format of a provided certificate.

Function Documentation

SharkSslCon_copyDecData()

U16 SharkSslCon_copyDecData	(	SharkSslCon *	o,
		U8 *	buf,
		U16	maxLen
	)

Copy decoded data to 'buf'.

Provides an alternative to using the zero copy API and the buffer returned by SharkSslCon_getDecData.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
buf	a buffer provided by the caller
maxLen	the size of parameter 'buf'. SharkSSL will copy at most maxLen bytes to 'buf'.

Example:

for(;;)
{
switch (SharkSslCon_decrypt(s, (U16)readLen))
{
  case SharkSslCon_Decrypted:
     readLen = SharkSslCon_copyDecData(s, buf, maxLen);
     // decrypted readLen bytes
     if (SharkSslCon_decryptMore(s))
     {
        if ((readLen == 0) && (maxLen > 0))
        {
           break; // zero-length record, decrypt next one
        }
     }
     return readLen;
 
  // other cases not shown here

See also

SharkSslCon_getDecData

SharkSslCon_decrypt()

SharkSslCon_RetVal SharkSslCon_decrypt	(	SharkSslCon *	o,
		U16	readLen
	)

Decrypt the received data copied into the SharkSslCon receive buffer (the buffer returned by SharkSslCon_getBuf).

See SharkSslCon_RetVal for example code.

The SharkSslCon_decrypt function keeps decrypt state information in the SharkSslCon object and the function can therefore be used in event driven systems.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
readLen	the length of the received network data copied into the buffer returned by SharkSslCon_getBuf.

Returns

the decrypt state information SharkSslCon_RetVal.

See also

SharkSslCon_getBuf, SharkSslCon_getBufLen, SharkSslCon_encrypt

SharkSslCon_decryptMore()

U8 SharkSslCon_decryptMore

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_Decrypted returned by function SharkSslCon_decrypt.

The function returns TRUE if a complete SSL frame has been decrypted and is ready for consumption. See SharkSslCon_Decrypted for example code.

SharkSslCon_encrypt()

SharkSslCon_RetVal SharkSslCon_encrypt	(	SharkSslCon *	o,
		U8 *	buf,
		U16	maxLen
	)

Encrypt the data provided by parameter 'buf' or encrypt data in the SharkSslCon send buffer.

SharkSSL provides a zero copy API and you can optionally copy data directly to the SharkSslCon send buffer. The send buffer is returned by calling function SharkSslCon_getEncBufPtr.

The SharkSslCon_encrypt function keeps decrypt state information in the SharkSslCon object and the function can therefore be used in event driven systems.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
buf	the data to be encrypted or NULL when encrypting data copied directly to the SharkSslCon send buffer i.e. when copying the data to the pointer returned by function SharkSslCon_getEncBufPtr.
maxLen	is the length of 'buf' or the length of the data data copied directly to the SharkSslCon send buffer.

When SHARKSSL_ENABLE_KEY_UPDATE is enabled and the copy API is used, this function can return SharkSslCon_Handshake before consuming any application bytes in order to send a proactive AES-GCM KeyUpdate. Send and acknowledge the handshake data, then call this function again with the same buf and maxLen values. The zero-copy API cannot update before encrypting plaintext already placed in its output buffer; it therefore fails closed at the key-usage limit if the application has not explicitly updated sooner.

Returns

the encrypt state information SharkSslCon_RetVal.

See also

SharkSslCon_getEncBufPtr, SharkSslCon_getEncBufSize, SharkSslCon_decrypt

SharkSslCon_encryptMore()

U8 SharkSslCon_encryptMore

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCon_encrypt.

The function returns TRUE if the SharkSslCon send buffer is full and must be flushed out.

The maximum size of the output buffer is set with parameter 'outBufSize' when calling the SharkSsl_constructor. When the unencrypted buffer is larger than what fits into the internal output buffer, SharkSSL breaks the unencrypted data into multiple chunks and SharkSslCon_encryptMore lets the application know when the buffer must be flushed.

See SharkSslCon_Encrypted for example code.

SharkSslCon_getAlertDescription()

U8 SharkSslCon_getAlertDescription

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt or in conjunction with state SharkSslCon_AlertRecv returned by function SharkSslCon_decrypt.

returns the SSL/TLS alert message

See also

SharkSslCon_getAlertLevel and SharkSslCon_getAlertData

SharkSslCon_getAlertLevel()

U8 SharkSslCon_getAlertLevel

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCon_encrypt or in conjunction with state SharkSslCon_AlertRecv returned by function SharkSslCon_decrypt.

Returns

SHARKSSL_ALERT_LEVEL_WARNING or SHARKSSL_ALERT_LEVEL_FATAL

See also

SharkSslCon_getAlertDescription and SharkSslCon_getAlertData

SharkSslCon_getBuf()

U8 * SharkSslCon_getBuf

(

SharkSslCon *

o

)

Returns a pointer to the SharkSslCon input/receive buffer.

The pointer returned by SharkSslCon_getBuf is where you copy the encrypted data you receive from the network.

Example code:

readLen = recv(mysocket, SharkSslCon_getBuf(s),SharkSslCon_getBufLen(s), 0);

See also

SharkSslCon_getBufLen and SharkSslCon_getDecData

SharkSslCon_getBufLen()

U16 SharkSslCon_getBufLen

(

SharkSslCon *

o

)

Returns the number of bytes currently available at the pointer returned by SharkSslCon_getBuf.

The SharkSslCon input-buffer start size is set with parameter inBufStartSize when calling the SharkSsl_constructor. If #SHARKSSL_DISABLE_INBUF_EXPANSION is zero, SharkSSL may grow this buffer to receive a larger record or reassemble a fragmented handshake message. The configured SHARKSSL_MAX_HANDSHAKE_LENGTH and the internal record limit bound this growth. This U16 API exposes at most 65535 bytes at a time.

Many ciphers are block based and the receiving end must read the complete block before it can be decrypted. The SSL/TLS specification enables blocks up to 16K in size. Note, the block will not be larger than the size of the packet sent by the peer side.

See also

SharkSslCon_getBuf

SharkSslCon_getDecData()

SHARKSSL_API U16 SharkSslCon_getDecData	(	SharkSslCon *	o,
		U8 **	bufPtr
	)

Get a pointer to the decoded data.

See SharkSslCon_Decrypted for example code.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
bufPtr	is set to the beginning of the decoded data.

Returns

Number of bytes decoded.

See also

SharkSslCon_copyDecData

SharkSslCon_getEncBufPtr()

U8 * SharkSslCon_getEncBufPtr

(

SharkSslCon *

o

)

This function is used in conjunction with SharkSslCon_encrypt when using the zero copy send API.

Returns

a pointer to the internal SharkSslCon send buffer.

See also

SharkSslCon_getEncBufSize.

SharkSslCon_getEncData()

U8 * SharkSslCon_getEncData

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCon_encrypt.

The function returns a pointer to the encoded data that must be sent to the peer side.

See also

SharkSslCon_getEncDataLen and SharkSslCon_encryptMore

SharkSslCon_getEncDataLen()

U16 SharkSslCon_getEncDataLen

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCon_encrypt.

The function returns the length of the encoded data that must be sent to the peer side.

See SharkSslCon_Encrypted for example code.

See also

SharkSslCon_getEncData and SharkSslCon_encryptMore

SharkSslCon_getHandshakeData()

U8 * SharkSslCon_getHandshakeData

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_Handshake returned by function SharkSslCon_encrypt.

The function returns the handshake data that must be sent to the peer side, if any.

After each send attempt, report the number of bytes accepted by the transport using SharkSslCon_setHandshakeDataSent.

See SharkSslCon_Handshake for example code.

See also

SharkSslCon_getHandshakeDataLen, SharkSslCon_setHandshakeDataSent

SharkSslCon_getHandshakeDataLen()

U16 SharkSslCon_getHandshakeDataLen

(

SharkSslCon *

o

)

This function is used in conjunction with state SharkSslCon_Handshake returned by function SharkSslCon_decrypt.

The function returns the length of the handshake data that must be sent to the peer side, if any. The function returns zero if no handshake data should be sent.

See SharkSslCon_Handshake for example code.

See also

SharkSslCon_getHandshakeData, SharkSslCon_setHandshakeDataSent

SharkSslCon_isHandshakeComplete()

U8 SharkSslCon_isHandshakeComplete

(

SharkSslCon *

o

)

Returns the following values:

• 0: The TLS handshake has not completed.
• 1: The TLS handshake has completed.
• 2: The TLS handshake has completed; however, the SharkSSL connection includes additional data that must be processed by calling SharkSslCon_decrypt. See state SharkSslCon_Handshake for example code.

SharkSslCon_keyUpdate()

SHARKSSL_API U8 SharkSslCon_keyUpdate	(	SharkSslCon *	o,
		U8	requestUpdate
	)

Creates a TLS 1.3 KeyUpdate message and advances the local write keys.

Every KeyUpdate rotates the sending direction from the caller to the peer. SHARKSSL_KEY_UPDATE_NOT_REQUESTED rotates only caller-to-peer traffic and requires no response. SHARKSSL_KEY_UPDATE_REQUESTED also asks the peer to respond with SHARKSSL_KEY_UPDATE_NOT_REQUESTED, thereby rotating both traffic directions. After a successful SHARKSSL_KEY_UPDATE_REQUESTED, another requested update is rejected until any subsequent peer KeyUpdate is successfully processed. SHARKSSL_KEY_UPDATE_NOT_REQUESTED remains available while a requested update is outstanding, subject to the normal connection and output checks.

Retrieve the encrypted handshake data using SharkSslCon_getHandshakeData, send it, and report the number of bytes accepted by the transport using SharkSslCon_setHandshakeDataSent. This acknowledgement is required after every send attempt, including a complete send or a zero-byte result.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
requestUpdate	must be SHARKSSL_KEY_UPDATE_NOT_REQUESTED to rotate only the local sending direction, or SHARKSSL_KEY_UPDATE_REQUESTED to ask the peer to rotate its sending direction as well. Both values rotate the local write keys.

Returns

TRUE (1) if the request is accepted. Returns FALSE (0) if TLS 1.3 is not active, the handshake has not completed, output is pending, the request value is invalid, the sending epoch has reached 2^48-1, or if a requested update is already outstanding.

SharkSslCon_setHandshakeDataSent()

U16 SharkSslCon_setHandshakeDataSent	(	SharkSslCon *	o,
		U16	length
	)

This function is used in conjunction with SharkSslCon_getHandshakeData.

See SharkSslCon_Handshake for example code.

The function returns the residual length of the handshake data that must be sent to the peer side, if any. The function returns zero if no handshake data should be sent.

Call this function after every attempt to send handshake data, including when the transport accepts the complete buffer or zero bytes. Do not continue connection processing until the function returns zero. A zero-copy transport must acknowledge only bytes for which it no longer references the buffer returned by SharkSslCon_getHandshakeData.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
length	is the number of handshake bytes consumed or copied by the transport (usually TCP/IP); it may be zero.

See also

SharkSslCon_getHandshakeData