SharkSSL™ Embedded SSL/TLS Stack
Core API

The transport agnostic SharkSSL API. More...

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_Certificate, 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 TRUE if the SSL handshake phase is completed. 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...
 
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...
 

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.

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

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:

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, and send the handshake data to the peer side.

selib.c code snippet:

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:

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 (buf == NULL) /* 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",
break;
case SharkSslCon_AlertRecv: /* Alert message received from peer. */
/* One can retrieve the alert level & description through:
* SharkSslCon_getAlertLevel(s)
* SharkSslCon_getAlertDescription(s)
*/
{
xprintf(("SharkSSL : Received closure alert \n"));
}
else
{
xprintf(("SharkSSL : Received alert, level %d, description %d\n",
}
break;
xprintf(("SharkSSL : Internal failure\n"));
break;
xprintf(("SharkSSL : Certificate error\n"));
break;
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:

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.
*/
{
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_Certificate 

Returned by function SharkSslCon_encrypt if SHARKSSL_ENABLE_CLONE_CERTINFO is disabled and when a complete certificate is received from the peer during the SSL handshake phase.

Fixme more...

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
othe SharkSslCon object returned by function SharkSsl_createCon.
bufa buffer provided by the caller
maxLenthe size of parameter 'buf'. SharkSSL will copy at most maxLen bytes to 'buf'.

Example:

for(;;)
{
switch (SharkSslCon_decrypt(s, (U16)readLen))
{
readLen = SharkSslCon_copyDecData(s, buf, maxLen);
// decrypted readLen bytes
{
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
othe SharkSslCon object returned by function SharkSsl_createCon.
readLenthe 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
othe SharkSslCon object returned by function SharkSsl_createCon.
bufthe 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.
maxLenis 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
othe SharkSslCon object returned by function SharkSsl_createCon.
bufPtris 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 TRUE if the SSL handshake phase is completed.

See state SharkSslCon_Handshake for example code.

SharkSslCon_AllocationError
@ SharkSslCon_AllocationError
The memory pool is too small.
Definition: SharkSSL.h:759
SharkSslCon_getEncData
U8 * SharkSslCon_getEncData(SharkSslCon *o)
This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCo...
se_recv
S32 se_recv(SOCKET *sock, void *buf, U32 len, U32 timeout)
Waits for data sent by peer.
SharkSslCon_NeedMoreData
@ SharkSslCon_NeedMoreData
Returned when SharkSSL holds an incomplete SSL/TLS record or when the connection is initially establi...
Definition: SharkSSL.h:796
SharkSslCon_getAlertDataLen
#define SharkSslCon_getAlertDataLen(o)
This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo...
Definition: SharkSSL.h:1444
se_send
S32 se_send(SOCKET *sock, const void *buf, U32 len)
Sends data to the connected peer.
SharkSslCon_decrypt
SharkSslCon_RetVal SharkSslCon_decrypt(SharkSslCon *o, U16 readLen)
Decrypt the received data copied into the SharkSslCon receive buffer (the buffer returned by SharkSsl...
SharkSslCon_Handshake
@ SharkSslCon_Handshake
Returned when an SSL/TLS handshake message has been received or is to be sent.
Definition: SharkSSL.h:783
SHARKSSL_ALERT_LEVEL_WARNING
#define SHARKSSL_ALERT_LEVEL_WARNING
SSL/TLS warning message.
Definition: SharkSSL.h:114
SharkSslCon_encryptMore
U8 SharkSslCon_encryptMore(SharkSslCon *o)
This function is used in conjunction with state SharkSslCon_Encrypted 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:1432
SharkSslCon_decryptMore
U8 SharkSslCon_decryptMore(SharkSslCon *o)
This function is used in conjunction with state SharkSslCon_Decrypted returned by function SharkSslCo...
SharkSslCon_Encrypted
@ SharkSslCon_Encrypted
SharkSSL has successfully decrypted a chunk of data.
Definition: SharkSSL.h:831
SharkSslCon_CertificateError
@ SharkSslCon_CertificateError
Unrecognized format of a provided certificate.
Definition: SharkSSL.h:848
SHARKSSL_ALERT_CLOSE_NOTIFY
#define SHARKSSL_ALERT_CLOSE_NOTIFY
SHARKSSL_ALERT_CLOSE_NOTIFY.
Definition: SharkSSL.h:131
SharkSslCon_AlertSend
@ SharkSslCon_AlertSend
Returned when an SSL/TLS alert message must be sent to the peer side.
Definition: SharkSSL.h:810
SharkSslCon_getDecData
SHARKSSL_API U16 SharkSslCon_getDecData(SharkSslCon *o, U8 **bufPtr)
Get a pointer to the decoded data.
xprintf
#define xprintf(data)
The macro xprintf expands to function _xprintf if the code is compiled with XPRINTF set to 1.
Definition: selib.h:256
SharkSslCon_getAlertDescription
U8 SharkSslCon_getAlertDescription(SharkSslCon *o)
This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo...
SharkSslCon_getBuf
U8 * SharkSslCon_getBuf(SharkSslCon *o)
Returns a pointer to the SharkSslCon input/receive buffer.
SharkSslCon_getEncDataLen
U16 SharkSslCon_getEncDataLen(SharkSslCon *o)
This function is used in conjunction with state SharkSslCon_Encrypted returned by function SharkSslCo...
SharkSslCon_copyDecData
U16 SharkSslCon_copyDecData(SharkSslCon *o, U8 *buf, U16 maxLen)
Copy decoded data to 'buf'.
SharkSslCon_Error
@ SharkSslCon_Error
Indicates general errors, including configuration errors.
Definition: SharkSSL.h:755
SharkSslCon_getBufLen
U16 SharkSslCon_getBufLen(SharkSslCon *o)
Returns the length of the SharkSslCon input buffer.
SharkSslCon_Decrypted
@ SharkSslCon_Decrypted
Returned when a block of received data has been successfully decrypted.
Definition: SharkSSL.h:770
SharkSslCon_getAlertLevel
U8 SharkSslCon_getAlertLevel(SharkSslCon *o)
This function is used in conjunction with state SharkSslCon_AlertSend returned by function SharkSslCo...
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:819