Diff: inc/SharkSSL.h

Revision:

0:e0adec41ad6b

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/SharkSSL.h	Wed Apr 06 00:46:36 2016 +0000
@@ -0,0 +1,2101 @@
+/*
+ *     ____             _________                __                _
+ *    / __ \___  ____ _/ /_  __(_)___ ___  ___  / /   ____  ____ _(_)____
+ *   / /_/ / _ \/ __ `/ / / / / / __ `__ \/ _ \/ /   / __ \/ __ `/ / ___/
+ *  / _, _/  __/ /_/ / / / / / / / / / / /  __/ /___/ /_/ / /_/ / / /__
+ * /_/ |_|\___/\__,_/_/ /_/ /_/_/ /_/ /_/\___/_____/\____/\__, /_/\___/
+ *                                                       /____/
+ *
+ *                 SharkSSL Embedded SSL/TLS Stack
+ ****************************************************************************
+ *   PROGRAM MODULE
+ *
+ *   $Id: SharkSSL.h 3863 2016-03-19 02:15:11Z wini $
+ *
+ *   COPYRIGHT:  Real Time Logic LLC, 2010 - 2013
+ *
+ *   This software is copyrighted by and is the sole property of Real
+ *   Time Logic LLC.  All rights, title, ownership, or other interests in
+ *   the software remain the property of Real Time Logic LLC.  This
+ *   software may only be used in accordance with the terms and
+ *   conditions stipulated in the corresponding license agreement under
+ *   which the software has been supplied.  Any unauthorized use,
+ *   duplication, transmission, distribution, or disclosure of this
+ *   software is expressly forbidden.
+ *
+ *   This Copyright notice may not be removed or modified without prior
+ *   written consent of Real Time Logic LLC.
+ *
+ *   Real Time Logic LLC. reserves the right to modify this software
+ *   without notice.
+ *
+ *               http://www.realtimelogic.com
+ *               http://www.sharkssl.com
+ ****************************************************************************
+ *
+ */
+#ifndef _SharkSsl_h
+#define _SharkSsl_h
+
+#include "TargConfig.h"      /* platform dependencies  */
+#include "SharkSSL_cfg.h"    /* SharkSSL configuration */
+#ifdef __cplusplus
+#include <stddef.h>          /* size_t for new, delete */
+#endif
+
+#ifndef SHARKSSL_API
+#define SHARKSSL_API
+#else  /* Barracuda */
+#define SHARKSSL_BA 1
+#include <ThreadLib.h>
+#include <BaServerLib.h>
+#endif
+
+#include "SharkSslCrypto.h"  /* Crypto API */
+
+/** \defgroup ECDSA ECDSA sign/verify functions
+\ingroup RayCryptoApi
+
+See [Signing and Verifying Binaries](@ref signing) for an example
+of how to use the ECDSA ECDSA sign/verify functions.
+
+*/
+
+
+
+
+/** \addtogroup SharkSslAlert
+@{
+
+Alert messages are generated by SharkSSL or the peer side on errors.
+
+Alert messages are one of: fatal or warning. A fatal error means that
+the connection must be closed.
+*/
+
+/** SSL/TLS warning message */
+#define SHARKSSL_ALERT_LEVEL_WARNING               1
+
+/** Fatal error message. Connection must be closed. */
+#define SHARKSSL_ALERT_LEVEL_FATAL                 2
+
+/** \defgroup SharkSslAlertMsg SSL/TLS Alert Messages
+\ingroup SharkSslAlert
+@{
+
+\brief Alert messages returned by function #SharkSslCon_getAlertDescription
+
+Alert messages are generated by SharkSSL when processing the incoming
+data fails. Alert messages can also be received from the peer side,
+when the peer fails to process the data.
+*/
+
+/** SHARKSSL_ALERT_CLOSE_NOTIFY */
+#define SHARKSSL_ALERT_CLOSE_NOTIFY                0
+/** SHARKSSL_ALERT_UNEXPECTED_MESSAGE */
+#define SHARKSSL_ALERT_UNEXPECTED_MESSAGE          10
+/** SHARKSSL_ALERT_BAD_RECORD_MAC */
+#define SHARKSSL_ALERT_BAD_RECORD_MAC              20
+/** SHARKSSL_ALERT_DECRYPTION_FAILED */
+#define SHARKSSL_ALERT_DECRYPTION_FAILED           21
+/** SHARKSSL_ALERT_RECORD_OVERFLOW */
+#define SHARKSSL_ALERT_RECORD_OVERFLOW             22
+/** SHARKSSL_ALERT_DECOMPRESSION_FAILURE */
+#define SHARKSSL_ALERT_DECOMPRESSION_FAILURE       30
+/** SHARKSSL_ALERT_HANDSHAKE_FAILURE */
+#define SHARKSSL_ALERT_HANDSHAKE_FAILURE           40
+/** SHARKSSL_ALERT_NO_CERTIFICATE */
+#define SHARKSSL_ALERT_NO_CERTIFICATE              41  /* SSL 3.0 only */
+/** SHARKSSL_ALERT_BAD_CERTIFICATE */
+#define SHARKSSL_ALERT_BAD_CERTIFICATE             42
+/** SHARKSSL_ALERT_UNSUPPORTED_CERTIFICATE */
+#define SHARKSSL_ALERT_UNSUPPORTED_CERTIFICATE     43
+/** SHARKSSL_ALERT_CERTIFICATE_REVOKED */
+#define SHARKSSL_ALERT_CERTIFICATE_REVOKED         44
+/** SHARKSSL_ALERT_CERTIFICATE_EXPIRED */
+#define SHARKSSL_ALERT_CERTIFICATE_EXPIRED         45
+/** SHARKSSL_ALERT_CERTIFICATE_UNKNOWN */
+#define SHARKSSL_ALERT_CERTIFICATE_UNKNOWN         46
+/** SHARKSSL_ALERT_ILLEGAL_PARAMETER */
+#define SHARKSSL_ALERT_ILLEGAL_PARAMETER           47
+/** SHARKSSL_ALERT_UNKNOWN_CA */
+#define SHARKSSL_ALERT_UNKNOWN_CA                  48
+/** SHARKSSL_ALERT_ACCESS_DENIED */
+#define SHARKSSL_ALERT_ACCESS_DENIED               49
+/** SHARKSSL_ALERT_DECODE_ERROR */
+#define SHARKSSL_ALERT_DECODE_ERROR                50
+/** SHARKSSL_ALERT_DECRYPT_ERROR */
+#define SHARKSSL_ALERT_DECRYPT_ERROR               51
+/** SHARKSSL_ALERT_EXPORT_RESTRICTION */
+#define SHARKSSL_ALERT_EXPORT_RESTRICTION          60
+/** SHARKSSL_ALERT_PROTOCOL_VERSION */
+#define SHARKSSL_ALERT_PROTOCOL_VERSION            70
+/** SHARKSSL_ALERT_INSUFFICIENT_SECURITY */
+#define SHARKSSL_ALERT_INSUFFICIENT_SECURITY       71
+/** SHARKSSL_ALERT_INTERNAL_ERROR */
+#define SHARKSSL_ALERT_INTERNAL_ERROR              80
+/** SHARKSSL_ALERT_USER_CANCELED */
+#define SHARKSSL_ALERT_USER_CANCELED               90
+/** SHARKSSL_ALERT_NO_RENEGOTIATION */
+#define SHARKSSL_ALERT_NO_RENEGOTIATION            100
+/** SHARKSSL_ALERT_UNKNOWN_PSK_IDENTITY */
+#define SHARKSSL_ALERT_UNKNOWN_PSK_IDENTITY        115
+
+/** @} */ /* end group SharkSslAlertMsg */ 
+/** @} */ /* end group SharkSslAlert */ 
+
+
+/** \defgroup SharkSslCiphers Supported Ciphersuites
+\ingroup SharkSslInfoAndCodes
+@{
+
+ \brief Supported Ciphersuites and values returned by
+SharkSslCon_getCiphersuite.
+*/
+
+/** TLS_NULL_WITH_NULL_NULL */
+#define TLS_NULL_WITH_NULL_NULL                       0x0000
+/** TLS_RSA_WITH_NULL_MD5 */
+#define TLS_RSA_WITH_NULL_MD5                         0x0001
+/** TLS_RSA_WITH_NULL_SHA */
+#define TLS_RSA_WITH_NULL_SHA                         0x0002
+/** TLS_RSA_WITH_RC4_128_MD5 */
+#define TLS_RSA_WITH_RC4_128_MD5                      0x0004
+/** TLS_RSA_WITH_RC4_128_SHA */
+#define TLS_RSA_WITH_RC4_128_SHA                      0x0005
+/** TLS_RSA_WITH_DES_CBC_SHA */
+#define TLS_RSA_WITH_DES_CBC_SHA                      0x0009
+/** TLS_RSA_WITH_3DES_EDE_CBC_SHA */
+#define TLS_RSA_WITH_3DES_EDE_CBC_SHA                 0x000A
+/** TLS_DHE_RSA_WITH_DES_CBC_SHA */
+#define TLS_DHE_RSA_WITH_DES_CBC_SHA                  0x0015
+/** TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA */
+#define TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA             0x0016
+/** TLS_RSA_WITH_AES_128_CBC_SHA */
+#define TLS_RSA_WITH_AES_128_CBC_SHA                  0x002F
+/** TLS_DHE_RSA_WITH_AES_128_CBC_SHA */
+#define TLS_DHE_RSA_WITH_AES_128_CBC_SHA              0x0033
+/** TLS_RSA_WITH_AES_256_CBC_SHA */
+#define TLS_RSA_WITH_AES_256_CBC_SHA                  0x0035
+/** TLS_DHE_RSA_WITH_AES_256_CBC_SHA */
+#define TLS_DHE_RSA_WITH_AES_256_CBC_SHA              0x0039
+/** TLS_RSA_WITH_NULL_SHA256 */
+#define TLS_RSA_WITH_NULL_SHA256                      0x003B
+/** TLS_RSA_WITH_AES_128_CBC_SHA256 */
+#define TLS_RSA_WITH_AES_128_CBC_SHA256               0x003C
+/** TLS_RSA_WITH_AES_256_CBC_SHA256 */
+#define TLS_RSA_WITH_AES_256_CBC_SHA256               0x003D
+/** TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 */
+#define TLS_DHE_RSA_WITH_AES_128_CBC_SHA256           0x0067
+/** TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 */
+#define TLS_DHE_RSA_WITH_AES_256_CBC_SHA256           0x006B
+/** TLS_PSK_WITH_RC4_128_SHA */
+#define TLS_PSK_WITH_RC4_128_SHA                      0x008A
+/** TLS_PSK_WITH_3DES_EDE_CBC_SHA */
+#define TLS_PSK_WITH_3DES_EDE_CBC_SHA                 0x008B
+/** TLS_PSK_WITH_AES_128_CBC_SHA */
+#define TLS_PSK_WITH_AES_128_CBC_SHA                  0x008C
+/** TLS_PSK_WITH_AES_256_CBC_SHA */
+#define TLS_PSK_WITH_AES_256_CBC_SHA                  0x008D
+/** TLS_RSA_WITH_AES_128_GCM_SHA256 */
+#define TLS_RSA_WITH_AES_128_GCM_SHA256               0x009C
+/** TLS_RSA_WITH_AES_256_GCM_SHA384 */
+#define TLS_RSA_WITH_AES_256_GCM_SHA384               0x009D
+/** TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 */
+#define TLS_DHE_RSA_WITH_AES_128_GCM_SHA256           0x009E
+/** TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 */
+#define TLS_DHE_RSA_WITH_AES_256_GCM_SHA384           0x009F
+/** TLS_PSK_WITH_AES_128_GCM_SHA256 */
+#define TLS_PSK_WITH_AES_128_GCM_SHA256               0x00A8
+/** TLS_PSK_WITH_AES_256_GCM_SHA384 */
+#define TLS_PSK_WITH_AES_256_GCM_SHA384               0x00A9
+/** TLS_PSK_WITH_AES_128_CBC_SHA256 */
+#define TLS_PSK_WITH_AES_128_CBC_SHA256               0x00AE
+/** TLS_PSK_WITH_AES_256_CBC_SHA384 */
+#define TLS_PSK_WITH_AES_256_CBC_SHA384               0x00AF
+/** TLS_ECDH_ECDSA_WITH_NULL_SHA */
+#define TLS_ECDH_ECDSA_WITH_NULL_SHA                  0xC001
+/** TLS_ECDH_ECDSA_WITH_RC4_128_SHA */
+#define TLS_ECDH_ECDSA_WITH_RC4_128_SHA               0xC002
+/** TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA */
+#define TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA          0xC003
+/** TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA */
+#define TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA           0xC004
+/** TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA */
+#define TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA           0xC005
+/** TLS_ECDHE_ECDSA_WITH_NULL_SHA */
+#define TLS_ECDHE_ECDSA_WITH_NULL_SHA                 0xC006
+/** TLS_ECDHE_ECDSA_WITH_RC4_128_SHA */
+#define TLS_ECDHE_ECDSA_WITH_RC4_128_SHA              0xC007
+/** TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA */
+#define TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA         0xC008
+/** TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA */
+#define TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA          0xC009
+/** TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA */
+#define TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA          0xC00A
+/** TLS_ECDH_RSA_WITH_NULL_SHA */
+#define TLS_ECDH_RSA_WITH_NULL_SHA                    0xC00B
+/** TLS_ECDH_RSA_WITH_RC4_128_SHA */
+#define TLS_ECDH_RSA_WITH_RC4_128_SHA                 0xC00C
+/** TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA */
+#define TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA            0xC00D
+/** TLS_ECDH_RSA_WITH_AES_128_CBC_SHA */
+#define TLS_ECDH_RSA_WITH_AES_128_CBC_SHA             0xC00E
+/** TLS_ECDH_RSA_WITH_AES_256_CBC_SHA */
+#define TLS_ECDH_RSA_WITH_AES_256_CBC_SHA             0xC00F
+/** TLS_ECDHE_RSA_WITH_NULL_SHA */
+#define TLS_ECDHE_RSA_WITH_NULL_SHA                   0xC010
+/** TLS_ECDHE_RSA_WITH_RC4_128_SHA */
+#define TLS_ECDHE_RSA_WITH_RC4_128_SHA                0xC011
+/** TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA */
+#define TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA           0xC012
+/** TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA */
+#define TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA            0xC013
+/** TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA */
+#define TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA            0xC014
+/** TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 */
+#define TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256       0xC023
+/** TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 */
+#define TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384       0xC024
+/** TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 */
+#define TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256        0xC025
+/** TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 */
+#define TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384        0xC026
+/** TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 */
+#define TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256         0xC027
+/** TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 */
+#define TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384         0xC028
+/** TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 */
+#define TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256          0xC029
+/** TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 */
+#define TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384          0xC02A
+/** TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 */
+#define TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       0xC02B
+/** TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 */
+#define TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       0xC02C
+/** TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 */
+#define TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256        0xC02D
+/** TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 */
+#define TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384        0xC02E
+/** TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 */
+#define TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256         0xC02F
+/** TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 */
+#define TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         0xC030
+/** TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 */
+#define TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256          0xC031
+/** TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 */
+#define TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384          0xC032
+/** TLS_RSA_WITH_AES_128_CCM */
+#define TLS_RSA_WITH_AES_128_CCM                      0xC09C
+/** TLS_RSA_WITH_AES_256_CCM */
+#define TLS_RSA_WITH_AES_256_CCM                      0xC09D
+/** TLS_DHE_RSA_WITH_AES_128_CCM */
+#define TLS_DHE_RSA_WITH_AES_128_CCM                  0xC09E
+/** TLS_DHE_RSA_WITH_AES_256_CCM */
+#define TLS_DHE_RSA_WITH_AES_256_CCM                  0xC09F
+/** TLS_RSA_WITH_AES_128_CCM_8 */
+#define TLS_RSA_WITH_AES_128_CCM_8                    0xC0A0
+/** TLS_RSA_WITH_AES_256_CCM_8 */
+#define TLS_RSA_WITH_AES_256_CCM_8                    0xC0A1
+/** TLS_DHE_RSA_WITH_AES_128_CCM_8 */
+#define TLS_DHE_RSA_WITH_AES_128_CCM_8                0xC0A2
+/** TLS_DHE_RSA_WITH_AES_256_CCM_8 */
+#define TLS_DHE_RSA_WITH_AES_256_CCM_8                0xC0A3
+/** TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 */
+#define TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   0xCC13
+/** TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 */
+#define TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCC14
+/** TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 */
+#define TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256     0xCC15
+
+/** @} */ /* end group SharkSslCiphers */ 
+
+
+/** \defgroup SharkSslProtocol SSL and TLS protocol version
+\ingroup SharkSslInfoAndCodes
+@{
+ \brief Return values from function #SharkSslCon_getProtocol.
+*/
+
+/** SHARKSSL_PROTOCOL_UNKNOWN */
+#define SHARKSSL_PROTOCOL_UNKNOWN                  0x00
+/** SHARKSSL_PROTOCOL_SSL_3_0 */
+#define SHARKSSL_PROTOCOL_SSL_3_0                  0x30
+/** SHARKSSL_PROTOCOL_TLS_1_0 */
+#define SHARKSSL_PROTOCOL_TLS_1_0                  0x31
+/** SHARKSSL_PROTOCOL_TLS_1_1 */
+#define SHARKSSL_PROTOCOL_TLS_1_1                  0x32 
+/** SHARKSSL_PROTOCOL_TLS_1_2 */
+#define SHARKSSL_PROTOCOL_TLS_1_2                  0x33
+
+/** @} */ /* end group SharkSslProtocol */ 
+
+
+#if (SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA)
+#ifndef BA_API  /* standalone SharkSSL */
+#define BA_API SHARKSSL_API
+#ifdef _SHARKSSL_C_
+#define SingleListCode 1
+#endif
+#endif
+#include "SingleList.h"
+#endif
+
+
+#if SHARKSSL_ENABLE_SESSION_CACHE || SHARKSSL_NOPACK
+
+/** @addtogroup SharkSslSessionApi
+@{
+*/
+
+/** SharkSslSession is an opaque handle returned by function
+    #SharkSslCon_acquireSession.
+ */
+typedef struct SharkSslSession SharkSslSession;
+
+/** @} */ /* end group SharkSslSessionApi */ 
+
+#ifndef _DOXYGEN
+typedef struct SharkSslSessionCache
+{
+   SharkSslSession *cache;
+   ThreadMutexBase  cacheMutex;
+   U16 cacheSize;
+} SharkSslSessionCache;
+#endif
+#endif
+
+
+/** \addtogroup SharkSslInfoAndCodes
+@{
+*/
+
+/** Select one of client or server mode when creating a #SharkSsl
+    object.
+
+    __Note:__ A SharkSsl instance in server mode requires that you
+    install at a minimum one certificate by calling function
+    #SharkSsl_addCertificate.
+*/
+typedef enum
+{
+   SharkSsl_Unspecified,  /*!< Invalid value */
+   SharkSsl_Server,       /*!< Select SSL server mode */
+   SharkSsl_Client        /*!< Select SSL client mode */
+} SharkSsl_Role;
+
+/** @} */ /* end group SharkSslInfoAndCodes */
+
+
+#if (SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA)
+/** \addtogroup SharkSslInfoAndCodes
+@{
+*/
+
+/** The SharkSSL Certificate is in a binary format optimized for speed
+    and size. The certificate can be created by calling #sharkssl_PEM
+    or by using the command line tool
+    [SharkSslParseCert](\ref SharkSslParseCert)
+ */
+typedef const U8 *SharkSslCert;
+
+#if SHARKSSL_ENABLE_CA_LIST
+/** The SharkSSL Certificate Authority (CA) List is in a binary format
+    optimized for speed and size. The list can be created by calling
+    #SharkSslCertStore_assemble or by using the command line tool
+    [SharkSSLParseCAList](\ref SharkSSLParseCAList).
+ */
+typedef const U8 *SharkSslCAList;
+#endif
+
+/** @} */ /* end group SharkSslInfoAndCodes */
+#endif
+
+#if SHARKSSL_ENABLE_PSK || SHARKSSL_NOPACK
+/** \addtogroup SharkSslInfoAndCodes
+@{
+*/
+
+/** The SharkSSL PSK table is in an optimized binary format. 
+    The table can be created by using the command line tool
+    [SharkSslParsePSKTable](\ref SharkSSLParsePSKTable).
+ */
+typedef const U8 *SharkSslPSKTable;
+
+/** @} */ /* end group SharkSslInfoAndCodes */
+#endif
+
+#ifndef _DOXYGEN
+struct SharkSsl;
+#endif
+
+
+/* Non documented API used by SharkSslSCMgr when used indirectly by
+   Lua code in the Barracuda Application Server. The code manages
+   automatic destruction of SharkSslSCMgr.
+ */
+#ifndef _DOXYGEN
+struct SharkSslIntf;
+typedef void (*SharkSslIntf_Terminate)(struct SharkSslIntf* o,
+                                       struct SharkSsl* ssl); 
+typedef struct SharkSslIntf
+{
+   SharkSslIntf_Terminate terminate;
+} SharkSslIntf;
+#define SharkSslIntf_constructor(o,terminateFunc) (o)->terminate=terminateFunc
+#endif
+
+
+/** \addtogroup SharkSslInfoAndCodes
+@{
+*/
+
+/**  SharkSslCon is an opaque handle returned by function
+     #SharkSsl_createCon. 
+
+     The lifetime of a SharkSslCon object is as follows:
+
+     - Create a network connection and create a SharkSslCon object by
+       calling #SharkSsl_createCon
+
+     - Use the SharkSslCon functions to encode and decode data sent
+       and received over the network. See #SharkSslCon_encrypt and
+       #SharkSslCon_decrypt for more information.
+
+     - When you are ready to close the connection: close the network
+       connection and call function #SharkSsl_terminateCon
+
+   \sa  SharkSsl
+*/
+typedef struct SharkSslCon SharkSslCon;
+
+
+/** A SharkSsl object is the coordinator for managing #SharkSslCon
+    objects (See #SharkSsl_constructor for details).
+*/
+typedef struct
+SharkSsl
+{
+#ifdef __cplusplus
+   void *operator new(size_t s) { return ::baMalloc(s); }
+   void operator delete(void* d) { if(d) ::baFree(d); }
+   void *operator new(size_t, void *place) { return place; }
+   void operator delete(void*, void *) { }
+
+   SharkSsl() {};
+
+   SharkSsl(SharkSsl_Role role,
+            U16 cacheSize         = 0,
+            U16 inBufStartSize    = 4096,
+            U16 outBufSize        = 4096
+            );
+
+   ~SharkSsl();
+   SharkSslCon *createCon(void);
+   U8 setCAList(SharkSslCAList caList);
+   U8 addCertificate(SharkSslCert cert);
+   void terminateCon(SharkSslCon *sslCon);
+#endif
+   #if (SHARKSSL_SSL_SERVER_CODE && SHARKSSL_SSL_CLIENT_CODE) || SHARKSSL_NOPACK
+   SharkSsl_Role role;
+   #endif
+   U16 outBufSize;
+   U16 inBufStartSize;
+   U16 nCon;
+   #if (SHARKSSL_ENABLE_RSA || (SHARKSSL_ENABLE_ECDSA))  || SHARKSSL_NOPACK
+   SingleList certList;
+   #if SHARKSSL_ENABLE_CA_LIST  || SHARKSSL_NOPACK
+   SharkSslCAList caList;
+   #endif
+   #endif
+   #if SHARKSSL_ENABLE_PSK  || SHARKSSL_NOPACK
+   SharkSslPSKTable tablePSK;
+   #endif
+   #if SHARKSSL_ENABLE_SESSION_CACHE  || SHARKSSL_NOPACK
+   SharkSslSessionCache sessionCache;
+   /* Reserved for use with one SharkSslSCMgr object  */
+   SharkSslIntf* intf;
+   #endif
+} SharkSsl;
+
+/** @} */ /* end group SharkSslInfoAndCodes */
+
+/** @addtogroup SharkSslCoreApi
+@{
+*/
+
+/** The #SharkSslCon_decrypt and #SharkSslCon_encrypt return values.
+ */
+typedef enum
+{
+   /** Indicates general errors, including configuration errors.
+    */
+   SharkSslCon_Error = 1, 
+
+   /** The memory pool is too small.
+    */
+   SharkSslCon_AllocationError,
+
+   /** Returned when a block of received data has been successfully decrypted.
+
+       __selib.c code snippet:__
+       \dontinclude selib.c
+       \skipline case SharkSslCon_Decrypted:
+       \until return
+
+       \sa SharkSslCon_getDecData
+    */
+   SharkSslCon_Decrypted,
+
+   /** 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:__
+       \dontinclude selib.c
+       \skipline case SharkSslCon_Handshake:
+       \until xprintf(("handshake complete"));
+    */
+   SharkSslCon_Handshake,
+
+   /** 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:__
+       \dontinclude selib.c
+       \skipline case SharkSslCon_NeedMoreData:
+       \until decrypt next record
+
+       \sa #SharkSslCon_getBuf and #SharkSslCon_getBufLen
+    */
+   SharkSslCon_NeedMoreData,
+
+   /** Returned when an [SSL/TLS alert message](@ref SharkSslAlertMsg)
+       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:__
+       \dontinclude selib.c
+       \skipline case SharkSslCon_AlertSend:
+       \until return
+
+       \sa #SharkSslCon_getAlertData and #SharkSslCon_getAlertDataLen
+   */
+   SharkSslCon_AlertSend,
+
+   /** SharkSSL received an [SSL/TLS alert message](@ref SharkSslAlertMsg)
+       from the peer, which means that the peer either failed to
+       decode the message from SharkSSL or the peer entered an
+       exception state.
+
+       \sa SharkSslCon_getAlertLevel and SharkSslCon_getAlertDescription
+    */
+   SharkSslCon_AlertRecv,
+
+   /** 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:__
+       \dontinclude selib.c
+       \skipline case SharkSslCon_Encrypted:
+       \until return maxLen
+   */
+   SharkSslCon_Encrypted,
+
+   /** 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_HandshakeNotComplete,
+
+   /** 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_Certificate,
+
+   /** Unrecognized format of a provided certificate.
+    */
+   SharkSslCon_CertificateError
+
+} SharkSslCon_RetVal;
+
+/** @} */ /* end group SharkSslCoreApi */
+
+#if (SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA)
+
+/** \defgroup SharkSslCertInfo Peer's certificate information
+\ingroup SharkSslInfoAndCodes
+
+\brief Certificate information returned by #SharkSslCon_getCertInfo
+
+@{
+*/
+
+/** Certificate KeyUsage and ExtendedKeyUsage flags and relative
+    pseudofunctions
+ */
+#if SHARKSSL_ENABLE_CERT_KEYUSAGE
+#define SHARKSSL_CERT_KEYUSAGE_DIGITALSIGNATURE     0x00000001
+#define SHARKSSL_CERT_KEYUSAGE_NONREPUDIATION       0x00000002
+#define SHARKSSL_CERT_KEYUSAGE_KEYENCIPHERMENT      0x00000004
+#define SHARKSSL_CERT_KEYUSAGE_DATAENCIPHERMENT     0x00000008
+#define SHARKSSL_CERT_KEYUSAGE_KEYAGREEMENT         0x00000010
+#define SHARKSSL_CERT_KEYUSAGE_KEYCERTSIGN          0x00000020
+#define SHARKSSL_CERT_KEYUSAGE_CRLSIGN              0x00000040
+#define SHARKSSL_CERT_KEYUSAGE_ENCIPHERONLY         0x00000080 
+#define SHARKSSL_CERT_KEYUSAGE_DECIPHERONLY         0x00000100
+#define SHARKSSL_CERT_KEYUSAGE_PRESENT              0x00000200
+#define SHARKSSL_CERT_KEYUSAGE_CRITICAL             0x00000400
+
+#define SHARKSSL_CERT_KEYPURPOSE_SERVERAUTH         0x00010000
+#define SHARKSSL_CERT_KEYPURPOSE_CLIENTAUTH         0x00020000
+#define SHARKSSL_CERT_KEYPURPOSE_CODESIGNING        0x00040000
+#define SHARKSSL_CERT_KEYPURPOSE_EMAILPROTECTION    0x00080000
+#define SHARKSSL_CERT_KEYPURPOSE_TIMESTAMPING       0x00100000
+#define SHARKSSL_CERT_KEYPURPOSE_OCSPSIGNING        0x00200000
+
+#define SharkSslCertInfo_KeyFlagSet(o,f)            ((o)->keyUsagePurposes & f)
+
+/** The following pseudo-functions return a non-zero value
+    if the corresponding flag is set 
+ */
+#define SharkSslCertInfo_isKeyUsagePresent(o)       SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_PRESENT)
+#define SharkSslCertInfo_isKeyUsageCritical(o)      SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_CRITICAL)
+#define SharkSslCertInfo_KU_digitalSignature(o)     SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_DIGITALSIGNATURE)
+#define SharkSslCertInfo_KU_nonRepudiation(o)       SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_NONREPUDIATION)
+#define SharkSslCertInfo_KU_keyEncipherment(o)      SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_KEYENCIPHERMENT)
+#define SharkSslCertInfo_KU_dataEncipherment(o)     SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_DATAENCIPHERMENT)
+#define SharkSslCertInfo_KU_keyAgreement(o)         SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_KEYAGREEMENT)
+#define SharkSslCertInfo_KU_keyCertSign(o)          SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_KEYCERTSIGN)
+#define SharkSslCertInfo_KU_cRLSign(o)              SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_CRLSIGN)
+#define SharkSslCertInfo_KU_encipherOnly(o)         SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_ENCIPHERONLY)
+#define SharkSslCertInfo_KU_decipherOnly(o)         SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYUSAGE_DECIPHERONLY)
+
+#define SharkSslCertInfo_kp_serverAuth(o)           SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYPURPOSE_SERVERAUTH)
+#define SharkSslCertInfo_kp_clientAuth(o)           SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYPURPOSE_CLIENTAUTH)
+#define SharkSslCertInfo_kp_codeSigning(o)          SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYPURPOSE_CODESIGNING)
+#define SharkSslCertInfo_kp_emailProtection(o)      SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYPURPOSE_EMAILPROTECTION)
+#define SharkSslCertInfo_kp_timeStamping(o)         SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYPURPOSE_TIMESTAMPING)
+#define SharkSslCertInfo_kp_OCSPSigning(o)          SharkSslCertInfo_KeyFlagSet(o, SHARKSSL_CERT_KEYPURPOSE_OCSPSIGNING)
+#endif
+
+
+/** Certificate Distinguished Name
+
+    Example from certcheck.c:
+
+    \dontinclude certcheck.c
+    \skip  Begin Cert Info
+    \until End Cert Info
+
+    \sa SharkSslCertInfo
+
+ */
+typedef struct SharkSslCertDN
+{
+   const U8 *countryName; /**< ISO3166 country code */
+   const U8 *province;  /**< State or Province */
+   const U8 *locality; /**< The city or town name */ 
+   const U8 *organization; /**< Organization Name (company or department) */
+   const U8 *unit; /**< Organizational Unit (OU: department or organization unit) */
+   /** Common Name is the Host + Domain Name (example:
+       www.mycompany.com, where www is host and mycompany.com is Domain
+       Name) */
+   const U8 *commonName;
+   const U8 *emailAddress;
+
+   U8 countryNameLen;   /** length in bytes of the field "country" */
+   U8 provinceLen;      /** length in bytes of the field "province" */
+   U8 localityLen;      /** length in bytes of the field "locality" */
+   U8 organizationLen;  /** length in bytes of the field "organization" */
+   U8 unitLen;          /** length in bytes of the field "unit" */
+   U8 commonNameLen;    /** length in bytes of the field "common name" */
+   U8 emailAddressLen;    /** length in bytes of the field "emailAddress" */
+} SharkSslCertDN;
+
+#define SharkSslCertDN_constructor(o) memset(o,0,sizeof(SharkSslCertDN))
+
+#define SharkSslCertDN_setCountryName(o, countryNameMA) \
+   (o)->countryName=(const U8*)countryNameMA,(o)->countryNameLen=(U8)strlen(countryNameMA)
+#define SharkSslCertDN_setProvince(o, provinceMA) \
+   (o)->province=(const U8*)provinceMA,(o)->provinceLen=(U8)strlen(provinceMA)
+#define SharkSslCertDN_setLocality(o, localityMA) \
+   (o)->locality=(const U8*)localityMA,(o)->localityLen=(U8)strlen(localityMA)
+#define SharkSslCertDN_setOrganization(o, organizationMA) \
+   (o)->organization=(const U8*)organizationMA,(o)->organizationLen=(U8)strlen(organizationMA)
+#define SharkSslCertDN_setUnit(o, unitMA) \
+   (o)->unit=(const U8*)unitMA,(o)->unitLen=(U8)strlen(unitMA)
+#define SharkSslCertDN_setCommonName(o, commonNameMA) \
+   (o)->commonName=(const U8*)commonNameMA,(o)->commonNameLen=(U8)strlen(commonNameMA)
+
+
+/** The peer's certificate information returned by #SharkSslCon_getCertInfo.
+    \sa SharkSslCertDN
+ */
+typedef struct SharkSslCertInfo
+{
+     /** Length of 'sn' (serial number) */
+   U16 snLen;
+
+   /**  Certificate version is offset at 0 so add +1 for actual
+        version number.
+   */
+   U8  version; 
+
+   /** The Certificate Authority flag (CA) is set to one if the
+       certificate is a CA i.e. a root certificate.
+    */
+   U8 CAflag;
+
+   /** Binary serial number. The length is provided in 'snLen'
+    */
+   U8 *sn;
+
+   /** Certificate is valid from date (in UTCTime format: YYMMDDHHMMSSZ)
+    */
+   U8 *timeFrom;
+
+   /** Certificate expiration date (in UTCTime format: YYMMDDHHMMSSZ)
+    */
+   U8 *timeTo;
+
+   /** The entity who has signed and issued the certificate (<a 
+       href="http://tools.ietf.org/html/rfc2459#section-4.1.2.4"
+       >RFC2459 4.1.2.4</a>)
+    */
+   SharkSslCertDN issuer;
+
+   /** The entity associated with the public key (<a 
+       href="http://tools.ietf.org/html/rfc2459#section-4.1.2.6"
+       >RFC2459 4.1.2.6</a>).
+    */
+   SharkSslCertDN subject;
+
+   /** Subject Alternative DNS Names, if set, is a pointer to a list
+       of alternative names. Each entry in the list is prefixed with
+       a 1-byte length, followed by a string of 'length' bytes; 
+       the list ends with a zero length. 
+       The following example is from certcheck.c:
+
+       \dontinclude certcheck.c
+       \skipline U8 *tp
+       \until xprintf(("\n"))
+    */
+   U8 *subjectAltDNSNames;
+
+   #if SHARKSSL_ENABLE_CERT_KEYUSAGE
+   /** KeyUsage & ExtendedKeyUsage (key purposes) flags. 
+       Verify that the KeyUsage extension is present through the 
+         SharkSslCertInfo_isKeyUsagePresent(o) pseudo-function, 
+       then verify all the flags through the pseudo-functions:
+         SharkSslCertInfo_KU_digitalSignature(o)
+         SharkSslCertInfo_KU_nonRepudiation(o)
+         SharkSslCertInfo_KU_keyEncipherment(o)
+         SharkSslCertInfo_KU_dataEncipherment(o)
+         SharkSslCertInfo_KU_keyAgreement(o)
+         SharkSslCertInfo_KU_keyCertSign(o)
+         SharkSslCertInfo_KU_cRLSign(o)
+         SharkSslCertInfo_KU_encipherOnly(o)
+         SharkSslCertInfo_KU_decipherOnly(o)
+
+       Verify the ExtendedKeyUsage purposes through the following:
+         SharkSslCertInfo_kp_serverAuth(o)
+         SharkSslCertInfo_kp_clientAuth(o)
+         SharkSslCertInfo_kp_codeSigning(o)
+         SharkSslCertInfo_kp_emailProtection(o)
+         SharkSslCertInfo_kp_timeStamping(o)
+         SharkSslCertInfo_kp_OCSPSigning(o)
+    */ 
+   U32 keyUsagePurposes; 
+   #endif
+
+   /** Pointer to parent node when the SharkSslCertInfo object is part of
+       a certificate chain. You walk up the chain until you reach the root.
+   */
+   struct SharkSslCertInfo *parent;
+} SharkSslCertInfo;
+
+/** @} */ /* end group SharkSslCertInfo */ 
+#endif
+
+/** @addtogroup SharkSslApi
+@{
+*/
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** A SharkSsl object is the coordinator for managing SharkSslCon
+    objects.
+
+    You must at a minimum create one SharkSsl object. A more advanced
+    configuration may include several SharkSsl objects. For example, a
+    system that includes both a client and server SSL stack must
+    create and initialize two SharkSsl objects.
+
+    \param o Uninitialized data of size sizeof(SharkSsl).
+
+    \param role Select client or server SSL mode. See #SharkSsl_Role
+    for details.
+
+    \param cacheSize The session resumption cache size. Setting this
+    to zero disables the cache management code. See
+    [SSL Session Management](@ref SharkSslSessionApi) for details.
+
+    \param inBufStartSize
+    \param outBufSize
+
+    parameter must be provided if you plan on using function
+    #SharkSslCon_trustedCA or #SharkSslCon_trusted. See
+    #SharkSslCAList for details.
+
+    \sa #SharkSsl_addCertificate, #SharkSsl_setCAList,
+    SharkSsl_createCon, and SharkSsl_terminateCon.
+ */
+SHARKSSL_API void  SharkSsl_constructor(
+                      SharkSsl *o,
+                      SharkSsl_Role role,
+                      U16 cacheSize,
+                      U16 inBufStartSize,
+                      U16 outBufSize
+                      );
+
+/** Close the SharkSsl object. Closing a SharkSsl object is not
+    common in embedded devices. You would normally keep the SharkSsl
+    object for the lifetime of the application. You must make sure
+    all #SharkSslCon objects are terminated by calling
+    #SharkSslCon_terminate for each active connection prior to calling
+    the SharkSsl_destructor.
+ */
+SHARKSSL_API void  SharkSsl_destructor(SharkSsl *o);
+
+
+/** Create a #SharkSslCon object. You must create one SharkSslCon
+    object for each active network connection that requires encryption.
+
+    The following code snippet is from the
+    [example programs](\ref SharkExamples).
+    \code
+int rc;
+SharkSslCon* scon;
+if( (rc=se_connect(&sock, "realtimelogic.com", 443)) == 0) // open socket
+{
+   if( (scon = SharkSsl_createCon(&sharkSsl)) != NULL)
+   {
+      // success
+   \endcode
+
+    \return a SharkSslCon object or NULL if memory is exhausted.
+
+    \sa SharkSsl_terminateCon and SharkSslCon_terminate
+ */
+SharkSslCon *SharkSsl_createCon(SharkSsl *o);
+
+
+/** Terminate a SharkSslCon object created by function SharkSsl_createCon.
+
+    \param o the SharkSsl object. Setting this parameter to NULL is
+    the same as calling macro #SharkSslCon_terminate.
+
+    \param con the SharkSslCon object to reclaim.
+
+    Code snippet from the example code: sessioncache.c 
+
+       \dontinclude sessioncache.c
+       \skipline Release resources
+       \until se_close
+
+ */
+void SharkSsl_terminateCon(const SharkSsl *o, SharkSslCon* con);
+
+
+#if SHARKSSL_ENABLE_SESSION_CACHE
+
+/** Returns the SharkSsl session cache size.
+    \sa SharkSsl_constructor (parameter cacheSize) and
+    #SHARKSSL_ENABLE_SESSION_CACHE
+*/
+SHARKSSL_API U16   SharkSsl_getCacheSize(SharkSsl *o);
+
+#define SharkSsl_setIntf(o, sharkSslIntf) (o)->intf=sharkSslIntf
+#define SharkSsl_getIntf(o) (o)->intf
+
+#endif
+
+
+/** The SharkSslCon object must be reclaimed when you close the
+ * network connection.
+
+    \sa #SharkSsl_createCon
+    \sa SharkSsl_terminateCon
+ */ 
+#define SharkSslCon_terminate(o) SharkSsl_terminateCon(0, o)
+
+/** @addtogroup SharkSslCoreApi
+@{
+*/
+
+/** 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.
+
+    \param o the SharkSslCon object returned by function #SharkSsl_createCon.
+
+    \param readLen the length of the received network data copied into
+    the buffer returned by #SharkSslCon_getBuf.
+
+    \return the decrypt state information #SharkSslCon_RetVal.
+
+    \sa SharkSslCon_getBuf, SharkSslCon_getBufLen, SharkSslCon_encrypt
+ */
+SharkSslCon_RetVal SharkSslCon_decrypt(SharkSslCon *o, U16 readLen);
+
+
+/** 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.
+
+    \param o the SharkSslCon object returned by function #SharkSsl_createCon.
+
+    \param 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.
+
+    \param maxLen is the length of 'buf' or the length of the data
+    data copied directly to the SharkSslCon send buffer.
+
+    \return the decrypt state information #SharkSslCon_RetVal.
+
+    \sa SharkSslCon_getEncBufPtr, SharkSslCon_getEncBufSize, SharkSslCon_decrypt
+ */
+SharkSslCon_RetVal SharkSslCon_encrypt(SharkSslCon *o, U8 *buf, U16 maxLen);
+
+
+/** Returns TRUE if the SSL handshake phase is completed. See
+    state #SharkSslCon_Handshake for example code.
+*/
+U8 SharkSslCon_isHandshakeComplete(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.
+ */
+U8  SharkSslCon_encryptMore(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.
+
+ */
+U8  SharkSslCon_decryptMore(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:
+    \code
+   readLen = recv(mysocket, SharkSslCon_getBuf(s),SharkSslCon_getBufLen(s), 0);
+   \endcode
+    \sa SharkSslCon_getBufLen and SharkSslCon_getDecData
+ */
+U8 *SharkSslCon_getBuf(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.
+
+    \sa SharkSslCon_getBuf
+ */
+U16 SharkSslCon_getBufLen(SharkSslCon *o);
+
+/** Copy decoded data to 'buf'. Provides an alternative to using the
+    zero copy API and the buffer returned by #SharkSslCon_getDecData.
+
+    \param o the SharkSslCon object returned by function #SharkSsl_createCon.
+    \param buf a buffer provided by the caller
+    \param maxLen the size of parameter 'buf'. SharkSSL will copy at
+    most maxLen bytes to 'buf'.
+
+    Example:
+    \code
+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
+    \endcode
+    \sa SharkSslCon_getDecData
+ */
+U16 SharkSslCon_copyDecData(SharkSslCon *o, U8 *buf, U16 maxLen);
+
+
+/** Get a pointer to the decoded data.
+
+    See #SharkSslCon_Decrypted for example code.
+
+    \param o the SharkSslCon object returned by function #SharkSsl_createCon.
+    \param bufPtr is set to the beginning of the decoded data.
+    \returns Number of bytes decoded.
+    \sa SharkSslCon_copyDecData
+ */
+SHARKSSL_API U16 SharkSslCon_getDecData(SharkSslCon *o, U8 **bufPtr);
+
+
+/** 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.
+
+    \sa SharkSslCon_getHandshakeDataLen
+ */
+U8 *SharkSslCon_getHandshakeData(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.
+
+    \sa SharkSslCon_getHandshakeData
+ */
+U16 SharkSslCon_getHandshakeDataLen(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.
+
+    \sa SharkSslCon_getEncDataLen and SharkSslCon_encryptMore
+ */
+U8 *SharkSslCon_getEncData(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.
+
+    \sa SharkSslCon_getEncData and SharkSslCon_encryptMore
+ */
+U16 SharkSslCon_getEncDataLen(SharkSslCon *o);
+
+
+/** This function is used in conjunction with #SharkSslCon_encrypt
+    when using the zero copy send API.
+
+    \return a pointer to the internal SharkSslCon send buffer. 
+    \sa SharkSslCon_getEncBufSize.
+ */
+U8 *SharkSslCon_getEncBufPtr(SharkSslCon *o);
+
+
+/** Returns the length of the buffer returned by #SharkSslCon_getEncBufPtr
+ */
+U16 SharkSslCon_getEncBufSize(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
+
+    \sa #SharkSslCon_getAlertDescription and #SharkSslCon_getAlertData
+ */
+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 the [SSL/TLS alert message](@ref SharkSslAlertMsg)
+
+    \sa #SharkSslCon_getAlertLevel and #SharkSslCon_getAlertData
+ */
+U8  SharkSslCon_getAlertDescription(SharkSslCon *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.
+
+    \sa #SharkSslCon_getAlertDataLen
+ */
+#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 the length of the alert data that must be
+    sent to the peer side.
+
+    \sa #SharkSslCon_getAlertData
+ */
+#define SharkSslCon_getAlertDataLen(o) SharkSslCon_getEncDataLen(o)
+
+/** @} */ /* end group SharkSslCoreApi */ 
+
+#if SHARKSSL_ENABLE_INFO_API
+
+/** Returns the active session's [chiper suite](@ref Ciphersuites)
+ */
+SHARKSSL_API U16 SharkSslCon_getCiphersuite(SharkSslCon *o);
+
+/** Returns the active session's [protocol version](@ref SharkSslProtocol)
+ */
+SHARKSSL_API U8  SharkSslCon_getProtocol(SharkSslCon *o);
+
+#endif
+
+#if SHARKSSL_ENABLE_SNI
+
+#if SHARKSSL_SSL_CLIENT_CODE
+/** set Server Name Indication for TLS client connections
+ */
+SHARKSSL_API U8  SharkSslCon_setSNI(SharkSslCon *o, const char *name, U16 length); 
+#endif
+
+#endif
+
+
+#if (SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA)
+#if (SHARKSSL_SSL_CLIENT_CODE && SHARKSSL_ENABLE_CLIENT_AUTH)
+/** Returns TRUE if the server requested a certificate from the client
+    to verify that the client's identity (authentication)
+ */
+U8  SharkSslCon_certificateRequested(SharkSslCon *o);
+#endif
+
+/** Returns the peer's certificate if the handshaking has
+    completed. The certificate is available at any time if the code is
+    compiled with #SHARKSSL_ENABLE_CLONE_CERTINFO enabled. The
+    certificate is only available when #SharkSslCon_decrypt returns the
+    state #SharkSslCon_Certificate if the certificate cloning code is
+    not enabled.
+ */
+SHARKSSL_API SharkSslCertInfo  *SharkSslCon_getCertInfo(SharkSslCon *o);
+
+
+/** Add a certificate to the SharkSsl object. A SharkSsl object in
+    [server mode](\ref #SharkSsl_Server) is required to have at least
+    one certificate.
+
+    __Note:__ You must install the certificate(s) before using the
+    SharkSsl object -- i.e. before calling #SharkSsl_createCon.
+
+    \returns TRUE on success or FALSE on error. The function
+    fails if you have existing connections in the SharkSsl object.
+ */
+SHARKSSL_API U8 SharkSsl_addCertificate(SharkSsl *o, SharkSslCert cert);
+
+#if SHARKSSL_ENABLE_CA_LIST
+
+/** Set a Certificate Authority (CA) list so the SharkSSL object can
+    permform certificate validation on the peer's certificate.
+    
+    \param o the SharkSsl object.
+
+    \param caList list created by calling #SharkSslCertStore_assemble
+    or by using the command line tool
+    [SharkSSLParseCAList](\ref SharkSSLParseCAList)
+
+    __Note:__ You can only set one CA list, thus the CA list must
+    include all root certificates required for your system.
+
+    The example program certcheck.c includes code that shows how to
+    perform complete certificate validation of the connected servers.
+
+    \return TRUE if the CA list was successfully installed or FALSE if
+    another CA list has previously been installed.
+
+    \sa #SharkSslCAList and SharkSslCon_trusted.
+ */
+SHARKSSL_API U8  SharkSsl_setCAList(SharkSsl *o, SharkSslCAList caList);
+
+/** Returns TRUE if the certificate is valid and is signed with a root
+    certificate trusted by SharkSSL. Root certificates can optionally
+    be installed with parameter #SharkSslCAList when calling
+    #SharkSsl_constructor.
+
+    Note, the function only validates the certificate. You must
+    typically also validate the domain name. Function
+    #SharkSslCon_trusted extends the certificate validation and also
+    includes domain name validation.
+
+    \sa SharkSslCon_trusted
+ */
+SHARKSSL_API U8  SharkSslCon_trustedCA(SharkSslCon *o);
+
+U8  SharkSslCon_isCAListEmpty(SharkSslCon *o);
+#endif  /* SHARKSSL_ENABLE_CA_LIST */
+
+#if (SHARKSSL_SSL_SERVER_CODE && SHARKSSL_ENABLE_RSA)
+/** Description to be added.
+ */
+
+/* to be used as 'flag' param */
+#define SHARKSSL_SET_FAVOR_RSA      1  
+#define SHARKSSL_CLEAR_FAVOR_RSA    0
+
+/** A SharkSSL server can have multiple certificates, such as RSA
+    certificates with various strengths, and Elliptic Curve
+    Certificates (ECC). A SharkSSL server connection will select the
+    strongest cipher combination supported by the server and the
+    client. In general, the ECC certificate will be preferred by the
+    server connection, if supported by the client. Most browsers today
+    support ECC, however, Certificate Authorities do not typically
+    support ECC.
+
+    The purpose with function SharkSslCon_favorRSA is to favor RSA
+    certificates over ECC when a client such as browser supports both
+    ECC and RSA. An M2M device can then force the use of ECC by
+    calling function SharkSslCon_selectCiphersuite, or at compile time
+    by removing RSA support. This enables devices to use ECC, with
+    self signed Certificate Authority certificates and browsers to use
+    RSA certificates signed by well known Certificate Authorities.
+ */
+U8  SharkSslCon_favorRSA(SharkSslCon *o, U8 flag);
+#endif  /* SHARKSSL_SSL_SERVER_CODE */
+#endif  /* SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA */
+
+#if SHARKSSL_ENABLE_PSK
+/** To be documented 
+ */
+SHARKSSL_API U8 SharkSsl_setPSKTable(SharkSsl *o, SharkSslPSKTable tablePSK);
+#endif  /* SHARKSSL_ENABLE_PSK */
+
+#if SHARKSSL_SSL_CLIENT_CODE 
+U8  SharkSslCon_selectProtocol(SharkSslCon *o, U8 protocol);
+#endif
+
+/** @addtogroup SharkSslSessionApi
+@{
+*/
+
+#if SHARKSSL_ENABLE_SESSION_CACHE
+
+/** Release a session created by function #SharkSslCon_acquireSession.
+ */
+SHARKSSL_API U8    SharkSslSession_release(SharkSslSession *o, SharkSsl *s);
+
+#if SHARKSSL_SSL_SERVER_CODE
+/** experimental 
+ */
+SHARKSSL_API U8    SharkSslCon_releaseSession(SharkSslCon *o);
+#endif
+
+#if SHARKSSL_SSL_CLIENT_CODE 
+
+/** Request a SharkSslSession object from the client's session pool.
+
+    \returns a SharkSslSession object on success or NULL if the
+    session cache pool is exhausted. See parameter 'cacheSize' in
+    function SharkSsl_constructor for more information on the cache
+    size.
+  */
+SHARKSSL_API SharkSslSession *SharkSslCon_acquireSession(SharkSslCon *o);
+
+
+/** Resume an existing session.
+    \param o the SharkSslCon object.
+    \param s a session object created by function #SharkSslCon_acquireSession.
+
+    \returns TRUE on success or FALSE if the session cannot be resumed.
+ */
+SHARKSSL_API U8 SharkSslCon_resumeSession(SharkSslCon *o, SharkSslSession *s); 
+
+/** Returns the last time the session was accessed. Delta time can be
+    calculated as follows: baGetUnixTime() -
+    SharkSslSession_getLatestAccessTime(ss);
+ */
+SHARKSSL_API U32   SharkSslSession_getLatestAccessTime(SharkSslSession *o);
+#endif
+#endif
+
+/** @} */ /* end group SharkSslSessionApi */
+
+#if (SHARKSSL_SSL_SERVER_CODE && SHARKSSL_ENABLE_CLIENT_AUTH && \
+    (SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA))
+/** This function is used by server solutions that require client SSL
+    certificate authentication. For example, it can be used by an
+    HTTPS server that requires the client to authenticate using a
+    certificate signed with a Certificate Authority (CA) known to the
+    server. The second parameter, caList specifies one or several CA
+    certificates the server uses when validating the client
+    certificate.
+
+    The function must be called before the initial handshake has
+    started or just after calling SharkSslCon_renegotiate. Calling
+    SharkSslCon_requestClientCert after #SharkSslCon_renegotiate
+    enables an existing session to request client authentication at a
+    later stage. For example, a server may require that the client
+    authenticates when the user navigates to a protected web page.
+
+    \param o the SharkSslCon object returned by function #SharkSsl_createCon.
+
+    \param caList the SharkSSL CA list is in a binary format optimized
+    for speed and size. The list can be created by calling
+    #SharkSslCertStore_assemble or by using the command line tool
+    [SharkSSLParseCAList](\ref SharkSSLParseCAList). The client is
+    then requested to provide an SSL certificate and this certificate
+    must be signed using one of the CA certificates provided in the
+    caList. The SSL handshake or rehandshake fails if the client's
+    certificate is not trusted or not signed with a known CA
+    certificate.
+
+    \return TRUE (1) if the request is accepted. Returns FALSE (0) if
+    the SharkSSL connection is already going through or done with a
+    handshaking phase.
+ */
+SHARKSSL_API U8 SharkSslCon_requestClientCert(
+   SharkSslCon *o, const void *caList);
+#endif
+
+#if ((SHARKSSL_SSL_SERVER_CODE || SHARKSSL_SSL_CLIENT_CODE) && \
+     SHARKSSL_ENABLE_SELECT_CIPHERSUITE)
+/**
+This function enables you to limit the number of ciphers at
+runtime. Cipher suites can be enabled/disabled at compile time, but
+your application may require that you also allow only specific ciphers
+at runtime. By default, all ciphers enabled at compile time can be
+used by SharkSSL. Calling this function disables the use of all
+ciphers except the selected cipher. You can call this function up to N
+times and re-enable N ciphers. N is by default set to 8 at compile
+time. You can change the N value by setting macro
+#SHARKSSL_SELECT_CIPHERSUITE_LIST_DEPTH.
+
+The function must be called before the initial handshake has completed
+or just after calling SharkSslCon_renegotiate. Calling
+SharkSslCon_selectCiphersuite and then #SharkSslCon_renegotiate
+enables an existing session to change cipher.
+
+<b>Example:</b><br>
+SharkSslCon_selectCiphersuite(myCon, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384)
+
+\param o the SharkSslCon object returned by function #SharkSsl_createCon.
+
+\param cipherSuite is one of the [supported ciphers](\ref SharkSslCiphers)
+enabled at compile time.
+
+\return TRUE (1) if the request is accepted. Returns FALSE (0) if the
+SharkSSL connection is currently in the handshaking phase, if the
+selected cipher was not enabled at compile time, or if called more
+than N times.
+*/
+SHARKSSL_API U8 SharkSslCon_selectCiphersuite(SharkSslCon *o, U16 cipherSuite);
+
+/** Clears the selection, thus enabling all ciphers.
+ */
+SHARKSSL_API U8 SharkSslCon_clearCiphersuiteSelection(SharkSslCon *o); 
+#endif
+
+#if (SHARKSSL_SSL_SERVER_CODE && SHARKSSL_ENABLE_SECURE_RENEGOTIATION)
+/** This function enables you to renegotiate an already established
+    SSL/TLS connection. Renegotiation is also known as
+    rehandshake. The function informs the SharkSSL state machine for
+    the active connection that you wish to renegotiate the
+    connection. The actual renegotiation is initiated and performed
+    the next time you call #SharkSslCon_decrypt.
+
+    The function is typically used in combination with
+    #SharkSslCon_requestClientCert, when requesting client SSL
+    certificate authentication on an existing connection. The function
+    can also be used in combination with
+    #SharkSslCon_selectCiphersuite, to force a change in the cipher
+    being used.
+
+    \param o the SharkSslCon object returned by function #SharkSsl_createCon.
+
+    \return TRUE (1) if the request is accepted. Returns FALSE (0) if
+    the SharkSSL connection is currently in the handshaking phase.
+*/
+SHARKSSL_API U8 SharkSslCon_renegotiate(SharkSslCon *o);
+#endif
+
+/** @} */ /* end group SharkSslApi */ 
+
+
+#if SHARKSSL_ENABLE_PEM_API
+/** @addtogroup RayCryptoApi
+@{
+*/
+
+
+/** Return values from function #sharkssl_PEM
+ */
+typedef enum
+{
+   /** OK */
+   SHARKSSL_PEM_OK = 0,
+
+   /** OK_PUBLIC */
+   SHARKSSL_PEM_OK_PUBLIC = 1,
+
+   /** ALLOCATION_ERROR */
+   SHARKSSL_PEM_ALLOCATION_ERROR = - 3000,
+
+   /** KEY_PARSE_ERROR */
+   SHARKSSL_PEM_KEY_PARSE_ERROR,
+
+   /** KEY_WRONG_IV */
+   SHARKSSL_PEM_KEY_WRONG_IV,
+
+   /** KEY_WRONG_LENGTH */
+   SHARKSSL_PEM_KEY_WRONG_LENGTH,
+
+   /** KEY_PASSPHRASE_REQUIRED */
+   SHARKSSL_PEM_KEY_PASSPHRASE_REQUIRED,
+
+   /** KEY_UNRECOGNIZED_FORMAT */
+   SHARKSSL_PEM_KEY_UNRECOGNIZED_FORMAT,
+
+   /** KEY_UNSUPPORTED_FORMAT */
+   SHARKSSL_PEM_KEY_UNSUPPORTED_FORMAT,
+
+   /** KEY_UNSUPPORTED_MODULUS_LENGTH */
+   SHARKSSL_PEM_KEY_UNSUPPORTED_MODULUS_LENGTH,
+
+   /** KEY_UNSUPPORTED_ENCRYPTION_TYPE */
+   SHARKSSL_PEM_KEY_UNSUPPORTED_ENCRYPTION_TYPE,
+
+   /** KEY_CERT_MISMATCH */
+   SHARKSSL_PEM_KEY_CERT_MISMATCH,
+
+   /** CERT_UNRECOGNIZED_FORMAT */
+   SHARKSSL_PEM_CERT_UNRECOGNIZED_FORMAT,
+
+   /** CERT_UNSUPPORTED_TYPE */
+   SHARKSSL_PEM_CERT_UNSUPPORTED_TYPE,
+
+   /** KEY_UNSUPPORTED_VERSION */
+   SHARKSSL_PEM_KEY_UNSUPPORTED_VERSION,
+
+   /** INTERNAL ERROR */
+   SHARKSSL_PEM_INTERNAL_ERROR
+} sharkssl_PEM_RetVal;
+
+
+/** fixme doc
+ */
+SHARKSSL_API sharkssl_PEM_RetVal sharkssl_PEM(
+   const char *certPEM, const char *keyPEM, 
+   const char *passphrase, SharkSslCert *sharkSslCert);
+
+/** @} */ /* end group RayCryptoApi */
+#endif
+
+#if SHARKSSL_ENABLE_RSA
+
+/** \addtogroup SharkSslInfoAndCodes
+@{
+*/
+
+/** SHARKSSL_RSA_NO_PADDING for raw RSA encryption (insecure).
+ */
+#define SHARKSSL_RSA_NO_PADDING      0
+
+
+/** SHARKSSL_RSA_PKCS1_PADDING for
+    [PKCS #1 v1.5](http://tools.ietf.org/html/rfc2313).
+*/
+#define SHARKSSL_RSA_PKCS1_PADDING   1
+
+
+/** Return values from functions #sharkssl_RSA_public_encrypt,
+    #sharkssl_RSA_private_decrypt, #sharkssl_RSA_public_decrypt,
+    #sharkssl_RSA_private_encrypt
+ */
+typedef enum
+{
+   /** OK */
+   SHARKSSL_RSA_OK = 0,
+
+   /** ALLOCATION_ERROR */
+   SHARKSSL_RSA_ALLOCATION_ERROR = -3000,
+
+   /** INTERNAL_ERROR */
+   SHARKSSL_RSA_INTERNAL_ERROR = -3100,
+
+   /** WRONG_PARAMETERS */
+   SHARKSSL_RSA_WRONG_PARAMETERS,
+
+   /** WRONG_KEY_FORMAT */
+   SHARKSSL_RSA_WRONG_KEY_FORMAT,
+
+   /** WRONG_KEY_LENGTH */
+   SHARKSSL_RSA_WRONG_KEY_LENGTH,
+
+   /** INPUT_DATA_LENGTH_TOO_BIG */
+   SHARKSSL_RSA_INPUT_DATA_LENGTH_TOO_BIG,
+
+   /** INPUT_DATA_LENGTH_AND_KEY_LENGTH_MISMATCH */
+   SHARKSSL_RSA_INPUT_DATA_LENGTH_AND_KEY_LENGTH_MISMATCH,
+
+   /** PKCS1_PADDING_ERROR */
+   SHARKSSL_RSA_PKCS1_PADDING_ERROR
+} sharkssl_RSA_RetVal;
+#endif
+
+/** @} */ /* end group SharkSslInfoAndCodes */ 
+
+#if SHARKSSL_ENABLE_RSA_API
+
+/** \defgroup RSA RSA encrypt/decrypt functions
+\ingroup RayCryptoApi
+
+@{
+*/
+
+/** SharkSslRSAKey is an alias for the #SharkSslCert type and is a
+    private/public key converted by sharkssl_PEM_to_RSAKey or the
+    command line tool [SharkSslParseKey](\ref SharkSslParseKey).
+ */
+typedef U8* SharkSslRSAKey;
+
+#if SHARKSSL_ENABLE_PEM_API
+/** Convert an RSA private or public key in PEM format to the
+    #SharkSslRSAKey format.
+ 
+    Note: the converted value must be released by calling
+    SharkSslRSAKey_free, when no longer needed.
+
+    example:
+    \code
+   {
+      SharkSslRSAKey RSAKey;   
+      ...
+      RSAKey = sharksslPEM_to_RSAKey(key, pass);
+      if (RSAKey)
+      {
+         ...
+         void SharkSslRSAKey_free(RSAKey);
+      }
+   }
+   \endcode
+
+   \return the private/public key in #SharkSslRSAKey format or NULL if
+   the conversion fails.
+  */
+SHARKSSL_API SharkSslRSAKey sharkssl_PEM_to_RSAKey(
+   const char *PEMKey, const char *passphrase);
+
+/** Extract the public key form a certificate in PEM format
+
+    Note: the converted value must be released by calling
+    SharkSslRSAKey_free, when no longer needed.
+
+    example:
+    \code
+   {
+      SharkSslRSAKey RSAKey;   
+      ...
+      RSAKey = sharkssl_PEM_extractPublicKey(cert);
+      if (RSAKey)
+      {
+         ...
+         void SharkSslRSAKey_free(RSAKey);
+      }
+   }
+   \endcode
+
+   \return the certificate's public key in #SharkSslRSAKey format 
+   or NULL if the conversion fails.
+
+ */
+SHARKSSL_API SharkSslRSAKey
+sharkssl_PEM_extractPublicKey(const char *certPEM);
+
+/** Release a SharkSslRSAKey allocated by functions #sharkssl_PEM_to_RSAKey
+    and sharkssl_PEM_extractPublicKey.
+ */
+SHARKSSL_API void SharkSslRSAKey_free(SharkSslRSAKey key);
+#endif
+
+#if SHARKSSL_ENABLE_RSA
+
+/** Returns the private or public key's modulus size in bytes.
+ */
+SHARKSSL_API U16 SharkSslRSAKey_size(SharkSslRSAKey key);
+
+/** Encrypt data using the public key or private key. The private key
+    includes the public key an can for this reason be used for
+    encrypting the data.
+
+    \param in the plaintext
+
+    \param len is the length/size of parameter 'in'. This length must be
+    exactly #SharkSslRSAKey_size (key) when selecting
+    #SHARKSSL_RSA_NO_PADDING or a value between 1 and
+    (#SharkSslRSAKey_size (key) - 11) when selecting
+    SHARKSSL_RSA_PKCS1_PADDING.
+
+    \param out the encrypted ciphertext is copied to this buffer. The
+    size of this buffer must be no less than #SharkSslRSAKey_size (key)
+
+    \param key is the public key in SharkSslRSAKey format.
+
+   \param padding is one of #SHARKSSL_RSA_PKCS1_PADDING or
+   #SHARKSSL_RSA_NO_PADDING
+
+   \return the size of the encrypted ciphertext, or -1 if any error occurs
+ */
+SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_encrypt(
+   U16 len, U8 *in, U8 *out, SharkSslRSAKey key, U8 padding);
+
+
+/** Decrypt ciphertext using the private key.
+
+    \param len is the length/size of parameter 'in'. This length must be
+    exactly #SharkSslRSAKey_size (key).
+
+    \param in the ciphertext
+
+    \param out the decrypted ciphertext is copied to this buffer. The
+    size of this buffer must be no less than #SharkSslRSAKey_size (key)
+
+    \param privkey is the private key in SharkSslRSAKey format.
+
+   \param padding is one of #SHARKSSL_RSA_PKCS1_PADDING or
+   #SHARKSSL_RSA_NO_PADDING
+
+   \return the size of the decrypted ciphertext, or -1 if any error occurs
+ */
+SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_decrypt(
+   U16 len, U8 *in, U8 *out, SharkSslRSAKey privkey, U8 padding);
+
+
+/** Sign a message digest using the private key. 
+
+    \param in commonly, an algorithm identifier followed by a message digest
+
+    \param len is the length/size of parameter 'in'. This length must be
+    exactly #SharkSslRSAKey_size (key) when selecting
+    #SHARKSSL_RSA_NO_PADDING or a value between 1 and
+    (#SharkSslRSAKey_size (key) - 11) when selecting
+    SHARKSSL_RSA_PKCS1_PADDING.
+
+    \param out the signature is copied to this buffer. The size
+    of this buffer must be no less than #SharkSslRSAKey_size (key)
+
+    \param privkey is the private key in SharkSslRSAKey format.
+
+   \param padding is one of #SHARKSSL_RSA_PKCS1_PADDING or
+   #SHARKSSL_RSA_NO_PADDING
+
+   \return the size of the signature, or -1 if any error occurs
+ */
+SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_encrypt(
+   U16 len, U8 *in, U8 *out, SharkSslRSAKey privkey, U8 padding);
+
+
+/** Bring back a message digest using the public key or private key. 
+    The private key includes the public key an can for this reason be used for
+    this operation.
+
+    \param in the RSA signature
+
+    \param len is the length/size of parameter 'in'. This length must be
+    exactly #SharkSslRSAKey_size (key).
+
+    \param out the message digest is copied to this buffer. The size
+    of this buffer must be no less than #SharkSslRSAKey_size (key)
+
+    \param key is the public key in SharkSslRSAKey format.
+
+   \param padding is one of #SHARKSSL_RSA_PKCS1_PADDING or
+   #SHARKSSL_RSA_NO_PADDING
+
+   \return the size of the obtained message digest, or -1 if any error occurs
+ */
+SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_decrypt(
+   U16 len, U8 *in, U8 *out, SharkSslRSAKey key, U8 padding);
+
+#endif
+
+/** @} */ /* end group RSA */
+#endif
+
+
+/** To be used as hashlen parameter in sharkssl_ECDSA_ functions
+    These are the hash lengths for the functions implemented in SharkSSL/RayCrypto
+
+    SHARKSSL_MD5_HASH_LEN
+    SHARKSSL_SHA1_HASH_LEN
+    SHARKSSL_SHA256_HASH_LEN
+    SHARKSSL_SHA384_HASH_LEN
+    SHARKSSL_SHA512_HASH_LEN
+    SHARKSSL_POLY1305_HASH_LEN
+ */
+
+
+#if SHARKSSL_USE_ECC
+
+/*
+ * use as curveID parameter
+ */
+#define SHARKSSL_EC_CURVE_ID_SECP192R1  19
+#define SHARKSSL_EC_CURVE_ID_SECP224R1  21
+#define SHARKSSL_EC_CURVE_ID_SECP256R1  23
+#define SHARKSSL_EC_CURVE_ID_SECP384R1  24
+#define SHARKSSL_EC_CURVE_ID_SECP521R1  25
+
+
+/** 
+    @ingroup ECDSA
+    SharkSslECCKey is an alias for the #SharkSslCert type and is a
+    private/public key converted by #sharkssl_PEM_to_ECCKey or the
+    command line tool [SharkSslParseKey](\ref SharkSslParseKey).
+ */
+typedef U8* SharkSslECCKey;
+
+#if SHARKSSL_ENABLE_PEM_API
+/** 
+    @ingroup ECDSA
+    Convert an ECC private or public key in PEM format to the
+    #SharkSslECCKey format.
+ 
+    Note: the converted value must be released by calling
+    SharkSslECCKey_free, when no longer needed.
+
+    example:
+    \code
+   {
+      SharkSslECCKey ECCKey;   
+      ...
+      ECCKey = sharksslPEM_to_ECCKey(key, pass);
+      if (ECCKey)
+      {
+         ...
+         void SharkSslECCKey_free(ECCKey);
+      }
+   }
+   \endcode
+
+   \return the private/public key in #SharkSslECCKey format or NULL if
+   the conversion fails.
+  */
+SHARKSSL_API SharkSslECCKey sharkssl_PEM_to_ECCKey(
+   const char *PEMKey, const char *passphrase);
+#endif
+
+
+#if SHARKSSL_ENABLE_ECCKEY_CREATE
+int SharkSslECCKey_create(SharkSslECCKey *key, U16 curveID);
+#endif
+
+
+#if (SHARKSSL_ENABLE_PEM_API || SHARKSSL_ENABLE_ECCKEY_CREATE)
+/** Release a SharkSslECCKey allocated by functions #sharkssl_PEM_to_ECCKey
+    or #SharkSslECCKey_create
+ */
+SHARKSSL_API void SharkSslECCKey_free(SharkSslECCKey key);
+#endif
+
+/** \addtogroup SharkSslInfoAndCodes
+@{
+*/
+
+
+#if (SHARKSSL_ENABLE_ECDSA && SHARKSSL_ENABLE_ECDSA_API)
+/** Return values from functions #sharkssl_ECDSA_sign_hash,
+    #sharkssl_ECDSA_verify_hash
+ */
+typedef enum
+{
+   /** OK */
+   SHARKSSL_ECDSA_OK = 0,
+
+   /** ALLOCATION_ERROR */
+   SHARKSSL_ECDSA_ALLOCATION_ERROR = -3200,
+
+   /** INTERNAL_ERROR */
+   SHARKSSL_ECDSA_INTERNAL_ERROR = -3300,
+
+   /** WRONG_PARAMETERS */
+   SHARKSSL_ECDSA_WRONG_PARAMETERS,
+
+   /** WRONG_KEY_FORMAT */
+   SHARKSSL_ECDSA_WRONG_KEY_FORMAT,
+
+   /** KEY_IS_NOT_PRIVATE */
+   SHARKSSL_ECDSA_KEY_NOT_PRIVATE,
+
+   /** KEY_IS_NOT_PUBLIC */
+   SHARKSSL_ECDSA_KEY_NOT_PUBLIC,
+
+   /** SIGLEN_TOO_SMALL */
+   SHARKSSL_ECDSA_SIGLEN_TOO_SMALL,
+
+   /** VERIFICATION_FAIL */
+   SHARKSSL_ECDSA_VERIFICATION_FAIL,
+
+   /** WRONG SIGNATURE */
+   SHARKSSL_ECDSA_WRONG_SIGNATURE
+} sharkssl_ECDSA_RetVal;
+
+/** @} */ /* end group SharkSslInfoAndCodes */ 
+
+/** @addtogroup ECDSA
+@{
+*/
+
+
+#if (!SHARKSSL_ECDSA_ONLY_VERIFY)
+/** Returns the maximum length (in bytes) of a DER-encoded ECDSA 
+    signature generated with the private key 'privkey'. This function 
+    is typically used in combination with #sharkssl_ECDSA_sign_hash to
+    compute the maximum length of the signature and to allocate a 
+    buffer large enough to hold the signature 'sig'.
+
+    \param privkey is the private key in SharkSslECCKey format.
+ */
+SHARKSSL_API U16 sharkssl_ECDSA_siglen(SharkSslECCKey privkey);
+
+/** Generate the signature using the ECC private key and a hash. 
+
+    \param privkey is the private key in #SharkSslECCKey format.
+
+    \param sig is a pointer to the buffer where the DER-encoded ECDSA
+     signature will be generated. The size of this buffer must not be
+     smaller than the value returned by #sharkssl_ECDSA_siglen for
+     param 'privkey'. The length of this buffer, which may be larger
+     than required, is provided in the next parameter (siglen).
+
+    \param siglen is parameter "sig"'s length and is provided as an
+     input parameter. The signature length will be returned as output
+     parameter.
+
+    \param hash the message digest obtained from a hash function
+     e.g. SHA256. 
+
+    \param hashlen the length of the message digest (see above).
+
+    \return SHARKSSL_ECDSA_OK if the signature generation is succesful, 
+     or one of the #sharkssl_ECDSA_RetVal error codes.
+ */
+SHARKSSL_API sharkssl_ECDSA_RetVal sharkssl_ECDSA_sign_hash(
+   SharkSslECCKey privkey, U8 *sig, U16 *siglen, U8 *hash, U8 hashlen);
+#endif
+
+/** Verify a message using the ECC public key and a hash algorithm. 
+
+    \param pubkey is the public key in SharkSslECCKey format.
+
+    \param sig is a pointer to the DER-encoded ECDSA signature 
+     that is to be verified.
+
+    \param siglen is parameter "sig"'s length.
+
+    \param hash the message digest obtained from a hash function
+     e.g. SHA256. 
+
+    \param hashlen the length of the message digest (see above).
+
+    \return SHARKSSL_ECDSA_OK if the signature verification is succesful, 
+     or one of the #sharkssl_ECDSA_RetVal error codes.
+ */
+SHARKSSL_API sharkssl_ECDSA_RetVal sharkssl_ECDSA_verify_hash(
+   SharkSslECCKey pubkey, U8 *sig, U16 siglen, U8 *hash, U8 hashlen);
+
+#endif
+
+/** @} */ /* end group ECC */
+#endif
+
+
+#if (SHARKSSL_ENABLE_CA_LIST && SHARKSSL_ENABLE_CERTSTORE_API)
+
+/** @addtogroup SharkSslCertApi
+@{
+*/
+
+
+#ifndef BA_API  /* standalone SharkSSL */
+#define BA_API SHARKSSL_API
+typedef U8 BaBool;
+#endif
+#include "DoubleList.h"
+
+/** SharkSslCertStore is a container object used when assembling a
+    #SharkSslCAList. See #SharkSslCertStore_assemble for details.
+ */
+typedef struct SharkSslCertStore
+{
+   DoubleList certList;
+   SharkSslCAList caList;
+   U16 elements;  /* number of elements in list */
+} SharkSslCertStore;
+
+/** Initialize a SharkSslCertStore object. See #SharkSslCertStore for
+    details.  The object must reside in memory as long as the produced
+    SharkSslCAList is used by a SharkSSL object.
+
+    \param o Uninitialized data of size sizeof(SharkSsl).
+
+    \sa #SharkSslCertStore_assemble.
+*/
+SHARKSSL_API void  SharkSslCertStore_constructor(SharkSslCertStore *o);
+
+/** Cleanup all memory used by the SharkSslCAList object. 
+ */
+SHARKSSL_API void  SharkSslCertStore_destructor(SharkSslCertStore* o);
+
+/** Alias for SharkSslCertStore_destructor */
+#define            SharkSslCertStore_release(o) SharkSslCertStore_destructor(o)
+
+/** add a certificate in PEM or p7b format to the CA store. A
+    convenient way to get CA's is to export the certificates from a
+    browser in PEM or p7b format. The p7b format is a container format
+    that can contain many CA's.
+
+    \param o the SharkSslCertStore object.
+    \param cert is a one PEM cert or multiple certs in p7b format.
+    \param certlen is the length of parameter 'cert'
+    \sa SharkSslCertStore_assemble.
+    \return the number of certificates successfully parsed and added to
+    the certificate store or a negative value if memory could not be allocated.
+ */
+SHARKSSL_API U16   SharkSslCertStore_add(
+   SharkSslCertStore *o, const char *cert, U32 certlen);
+
+/** Assemble all certificates added by calling #SharkSslCertStore_add.
+    The SharkSslCertStore object can be released as soon as the
+    #SharkSslCAList is assembled.
+
+    \param o the SharkSslCertStore object
+    \param outList is the SharkSslCAList out value
+    \return TRUE on success or FALSE if memory could not be allocated
+    \sa #SharkSslCertStore_destructor and #SharkSsl_setCAList
+ */
+SHARKSSL_API U8  SharkSslCertStore_assemble(
+   SharkSslCertStore *o, SharkSslCAList *outList);
+
+/** @} */ /* end group SharkSslCertApi */ 
+#endif  /* SHARKSSL_ENABLE_CA_LIST && SHARKSSL_ENABLE_CERTSTORE_API */
+
+
+
+
+
+#ifdef __cplusplus
+}
+
+inline SharkSsl::SharkSsl(
+   SharkSsl_Role role, U16 cacheSize, U16 inBufStartSize, U16 outBufSize) {
+   SharkSsl_constructor(this, role, cacheSize, inBufStartSize, outBufSize);
+}
+inline SharkSsl::~SharkSsl() {
+   SharkSsl_destructor(this);
+}
+inline SharkSslCon *SharkSsl::createCon(void) {
+   return SharkSsl_createCon(this);
+}
+inline void SharkSsl::terminateCon(SharkSslCon *sslCon) {
+   SharkSsl_terminateCon(this, sslCon);
+}
+
+#if (SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA)
+inline U8 SharkSsl::addCertificate(SharkSslCert cert) {
+   return SharkSsl_addCertificate(this, cert);
+}
+#if SHARKSSL_ENABLE_CA_LIST
+inline U8 SharkSsl::setCAList(SharkSslCAList caList) {
+   return SharkSsl_setCAList(this, caList);
+}
+#endif  /* SHARKSSL_ENABLE_CA_LIST */
+#endif  /* SHARKSSL_ENABLE_RSA || SHARKSSL_ENABLE_ECDSA */
+
+#if SHARKSSL_ENABLE_PSK
+inline U8 SharkSsl::setPSKTable(SharkSslPSKTable tablePSK) {
+   return SharkSsl_setPSKTable(this, tablePSK);
+}
+#endif  /* SHARKSSL_ENABLE_PSK */
+
+#endif  /* __cplusplus */
+
+
+#endif