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	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...

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 length of the SharkSslCon input buffer. 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

◆ 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: SharkSslCon_Decrypted @ SharkSslCon_Decrypted Returned when a block of received data has been successfully decrypted. Definition: SharkSSL.h:628 baAssert(buf); readLen = SharkSslCon_getDecData(s, buf); if (SharkSslCon_decryptMore(s) && (readLen == 0)) { break; /* decrypt next record / } return readLen; SharkSslCon_decryptMore U8 SharkSslCon_decryptMore(SharkSslCon o) This function is used in conjunction with state SharkSslCon_Decrypted returned by function SharkSslCo... SharkSslCon_getDecData SHARKSSL_API U16 SharkSslCon_getDecData(SharkSslCon o, U8 *bufPtr) Get a pointer to the decoded data. 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, and send the handshake data to the peer side. selib.c code snippet: case SharkSslCon_Handshake: SharkSslCon_Handshake @ SharkSslCon_Handshake Returned when an SSL/TLS handshake message has been received or is to be sent. Definition: SharkSSL.h:641
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: SharkSslCon_NeedMoreData @ SharkSslCon_NeedMoreData Returned when SharkSSL holds an incomplete SSL/TLS record or when the connection is initially establi... Definition: SharkSSL.h:654 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 / SharkSslCon_getBufLen U16 SharkSslCon_getBufLen(SharkSslCon o) Returns the length of the SharkSslCon input buffer. SharkSslCon_getBuf U8 * SharkSslCon_getBuf(SharkSslCon o) Returns a pointer to the SharkSslCon input/receive buffer. xprintf #define xprintf(data) The macro xprintf expands to function _xprintf if the code is compiled with XPRINTF set to 1. Definition:* selib.h:261 se_recv S32 se_recv(SOCKET sock, void buf, U32 len, U32 timeout) Waits for data sent by peer. 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. / SharkSslCon_AlertSend @ SharkSslCon_AlertSend Returned when an SSL/TLS alert message must be sent to the peer side. Definition:* SharkSSL.h:668 /* 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; SHARKSSL_ALERT_CLOSE_NOTIFY #define SHARKSSL_ALERT_CLOSE_NOTIFY SHARKSSL_ALERT_CLOSE_NOTIFY. Definition:* SharkSSL.h:131 SHARKSSL_ALERT_LEVEL_WARNING #define SHARKSSL_ALERT_LEVEL_WARNING SSL/TLS warning message. Definition: SharkSSL.h:114 SharkSslCon_getAlertLevel U8 SharkSslCon_getAlertLevel(SharkSslCon o) This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo... SharkSslCon_getAlertDataLen #define SharkSslCon_getAlertDataLen(o) This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo... Definition:* SharkSSL.h:1341 SharkSslCon_getAlertDescription U8 SharkSslCon_getAlertDescription(SharkSslCon o) This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo... SharkSslCon_getAlertData #define SharkSslCon_getAlertData(o) This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo... Definition:* SharkSSL.h:1329 SharkSslCon_AllocationError @ SharkSslCon_AllocationError The memory pool is too small. Definition: SharkSSL.h:617 SharkSslCon_Error @ SharkSslCon_Error Indicates general errors, including configuration errors. Definition: SharkSSL.h:613 SharkSslCon_CertificateError @ SharkSslCon_CertificateError Unrecognized format of a provided certificate. Definition: SharkSSL.h:699 SharkSslCon_AlertRecv @ SharkSslCon_AlertRecv SharkSSL received an SSL/TLS alert message from the peer, which means that the peer either failed to ... Definition: SharkSSL.h:677 se_send S32 se_send(SOCKET sock, const void buf, U32 len) Sends data to the connected peer. 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: SharkSslCon_Encrypted @ SharkSslCon_Encrypted SharkSSL has successfully decrypted a chunk of data. Definition: SharkSSL.h:689 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_getEncData U8 SharkSslCon_getEncData(SharkSslCon o) This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCo... SharkSslCon_getEncDataLen U16 SharkSslCon_getEncDataLen(SharkSslCon o) This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCo... SharkSslCon_encryptMore U8 SharkSslCon_encryptMore(SharkSslCon *o) This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCo...
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.

Returns: the decrypt 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 length of the SharkSslCon input buffer.

The buffer is internally managed by SharkSSL and may dynamically grow as large as 16Kbytes. The SharkSslCon input buffer start size is set with parameter inBufStartSize when calling the SharkSsl_constructor.

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.

See SharkSslCon_Handshake for example code.

See also: SharkSslCon_getHandshakeDataLen

◆ 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_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_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.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
length	is number of handshake bytes sent to the peer (usually via TCP/IP).

See also: SharkSslCon_getHandshakeData

Detailed Description

Macros

Enumerations

Functions

Macro Definition Documentation

◆ SharkSslCon_getAlertData

◆ SharkSslCon_getAlertDataLen

Enumeration Type Documentation

◆ SharkSslCon_RetVal

Function Documentation

◆ SharkSslCon_copyDecData()

◆ SharkSslCon_decrypt()

◆ SharkSslCon_decryptMore()

◆ SharkSslCon_encrypt()

◆ SharkSslCon_encryptMore()

◆ SharkSslCon_getAlertDescription()

◆ SharkSslCon_getAlertLevel()

◆ SharkSslCon_getBuf()

◆ SharkSslCon_getBufLen()

◆ SharkSslCon_getDecData()

◆ SharkSslCon_getEncBufPtr()

◆ SharkSslCon_getEncData()

◆ SharkSslCon_getEncDataLen()

◆ SharkSslCon_getHandshakeData()

◆ SharkSslCon_getHandshakeDataLen()

◆ SharkSslCon_isHandshakeComplete()

◆ SharkSslCon_setHandshakeDataSent()