This package includes the SharkSSL lite library and header files.

Dependents:   WebSocket-Client-Example SharkMQ-LED-Demo

Embed: (wiki syntax)

« Back to documentation index

SharkSslApi

SharkSslApi

Modules

 SharkSslCoreApi
 SharkSslSessionApi

Functions

SHARKSSL_API void SharkSsl_constructor (SharkSsl *o, SharkSsl_Role role, U16 cacheSize, U16 inBufStartSize, U16 outBufSize)
 A SharkSsl object is the coordinator for managing SharkSslCon objects.
SHARKSSL_API void SharkSsl_destructor (SharkSsl *o)
 Close the SharkSsl object.
SharkSslConSharkSsl_createCon (SharkSsl *o)
 Create a SharkSslCon object.
void SharkSsl_terminateCon (const SharkSsl *o, SharkSslCon *con)
 Terminate a SharkSslCon object created by function SharkSsl_createCon.
SHARKSSL_API U16 SharkSsl_getCacheSize (SharkSsl *o)
 Returns the SharkSsl session cache size.
SHARKSSL_API U16 SharkSslCon_getCiphersuite (SharkSslCon *o)
 Returns the active session's [chiper suite](Ciphersuites)
SHARKSSL_API U8 SharkSslCon_getProtocol (SharkSslCon *o)
 Returns the active session's [protocol version](SSL and TLS protocol version)
SHARKSSL_API U8 SharkSslCon_setSNI (SharkSslCon *o, const char *name, U16 length)
 set Server Name Indication for TLS client connections
U8 SharkSslCon_certificateRequested (SharkSslCon *o)
 Returns TRUE if the server requested a certificate from the client to verify that the client's identity (authentication)
SHARKSSL_API SharkSslCertInfoSharkSslCon_getCertInfo (SharkSslCon *o)
 Returns the peer's certificate if the handshaking has completed.
SHARKSSL_API U8 SharkSsl_addCertificate (SharkSsl *o, SharkSslCert cert)
 Add a certificate to the SharkSsl object.
SHARKSSL_API U8 SharkSsl_setCAList (SharkSsl *o, SharkSslCAList caList)
 Set a Certificate Authority (CA) list so the SharkSSL object can permform certificate validation on the peer's certificate.
SHARKSSL_API U8 SharkSslCon_trustedCA (SharkSslCon *o)
 Returns TRUE if the certificate is valid and is signed with a root certificate trusted by SharkSSL.
U8 SharkSslCon_favorRSA (SharkSslCon *o, U8 flag)
 A SharkSSL server can have multiple certificates, such as RSA certificates with various strengths, and Elliptic Curve Certificates (ECC).
SHARKSSL_API U8 SharkSsl_setPSKTable (SharkSsl *o, SharkSslPSKTable tablePSK)
 To be documented.
SHARKSSL_API U8 SharkSslCon_requestClientCert (SharkSslCon *o, const void *caList)
 This function is used by server solutions that require client SSL certificate authentication.
SHARKSSL_API U8 SharkSslCon_selectCiphersuite (SharkSslCon *o, U16 cipherSuite)
 This function enables you to limit the number of ciphers at runtime.
SHARKSSL_API U8 SharkSslCon_clearCiphersuiteSelection (SharkSslCon *o)
 Clears the selection, thus enabling all ciphers.
SHARKSSL_API U8 SharkSslCon_renegotiate (SharkSslCon *o)
 This function enables you to renegotiate an already established SSL/TLS connection.
SHARKSSL_API SharkSslConTrust SharkSslCon_trusted (SharkSslCon *o, const char *name, SharkSslCertInfo **cPtr)
 Returns the peer's "trust" status and certificate.

Function Documentation

SHARKSSL_API U8 SharkSsl_addCertificate ( SharkSsl o,
SharkSslCert  cert 
)

Add a certificate to the SharkSsl object.

A SharkSsl object in [server mode](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 void SharkSsl_constructor ( SharkSsl o,
SharkSsl_Role  role,
U16  cacheSize,
U16  inBufStartSize,
U16  outBufSize 
)

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.

Parameters:
oUninitialized data of size sizeof(SharkSsl).
roleSelect client or server SSL mode. See SharkSsl_Role for details.
cacheSizeThe session resumption cache size. Setting this to zero disables the cache management code. See [SSL Session Management](SharkSslSessionApi) for details.
inBufStartSize
outBufSizeparameter must be provided if you plan on using function SharkSslCon_trustedCA or SharkSslCon_trusted. See SharkSslCAList for details.
See also:
SharkSsl_addCertificate, SharkSsl_setCAList, SharkSsl_createCon, and SharkSsl_terminateCon.
SharkSslCon* SharkSsl_createCon ( 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](SharkExamples).

int rc;
SharkSslCon* scon;
if( (rc=se_connect(&sock, "realtimelogic.com", 443)) == 0) // open socket
{
   if( (scon = SharkSsl_createCon(&sharkSsl)) != NULL)
   {
      // success
Returns:
a SharkSslCon object or NULL if memory is exhausted.
See also:
SharkSsl_terminateCon and SharkSslCon_terminate
SHARKSSL_API void SharkSsl_destructor ( SharkSsl o )

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 U16 SharkSsl_getCacheSize ( SharkSsl o )

Returns the SharkSsl session cache size.

See also:
SharkSsl_constructor (parameter cacheSize) and SHARKSSL_ENABLE_SESSION_CACHE
SHARKSSL_API U8 SharkSsl_setCAList ( SharkSsl o,
SharkSslCAList  caList 
)

Set a Certificate Authority (CA) list so the SharkSSL object can permform certificate validation on the peer's certificate.

Parameters:
othe SharkSsl object.
caListlist created by calling SharkSslCertStore_assemble or by using the command line tool [SharkSSLParseCAList](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.

Returns:
TRUE if the CA list was successfully installed or FALSE if another CA list has previously been installed.
See also:
SharkSslCAList and SharkSslCon_trusted.
SHARKSSL_API U8 SharkSsl_setPSKTable ( SharkSsl o,
SharkSslPSKTable  tablePSK 
)

To be documented.

void SharkSsl_terminateCon ( const SharkSsl o,
SharkSslCon con 
)

Terminate a SharkSslCon object created by function SharkSsl_createCon.

Parameters:
othe SharkSsl object. Setting this parameter to NULL is the same as calling macro SharkSslCon_terminate.
conthe SharkSslCon object to reclaim.

Code snippet from the example code: sessioncache.c

U8 SharkSslCon_certificateRequested ( SharkSslCon o )

Returns TRUE if the server requested a certificate from the client to verify that the client's identity (authentication)

SHARKSSL_API U8 SharkSslCon_clearCiphersuiteSelection ( SharkSslCon o )

Clears the selection, thus enabling all ciphers.

U8 SharkSslCon_favorRSA ( SharkSslCon o,
U8  flag 
)

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.

SHARKSSL_API SharkSslCertInfo* SharkSslCon_getCertInfo ( SharkSslCon o )

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 U16 SharkSslCon_getCiphersuite ( SharkSslCon o )

Returns the active session's [chiper suite](Ciphersuites)

SHARKSSL_API U8 SharkSslCon_getProtocol ( SharkSslCon o )

Returns the active session's [protocol version](SSL and TLS protocol version)

SHARKSSL_API U8 SharkSslCon_renegotiate ( SharkSslCon o )

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.

Parameters:
othe SharkSslCon object returned by function SharkSsl_createCon.
Returns:
TRUE (1) if the request is accepted. Returns FALSE (0) if the SharkSSL connection is currently in the handshaking phase.
SHARKSSL_API U8 SharkSslCon_requestClientCert ( SharkSslCon o,
const void *  caList 
)

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.

Parameters:
othe SharkSslCon object returned by function SharkSsl_createCon.
caListthe 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](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.
Returns:
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_selectCiphersuite ( SharkSslCon o,
U16  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.

Example:
SharkSslCon_selectCiphersuite(myCon, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384)

Parameters:
othe SharkSslCon object returned by function SharkSsl_createCon.
cipherSuiteis one of the [supported ciphers](Supported Ciphersuites) enabled at compile time.
Returns:
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_setSNI ( SharkSslCon o,
const char *  name,
U16  length 
)

set Server Name Indication for TLS client connections

SHARKSSL_API SharkSslConTrust SharkSslCon_trusted ( SharkSslCon o,
const char *  name,
SharkSslCertInfo **  cPtr 
)

Returns the peer's "trust" status and certificate.

Parameters:
othe SharkSslCon object
nameis the domain name (common name)
cPtris an optional pointer that will be set to the connections's SharkSslCertInfo object, if provided.
Returns:
SharkSslConTrust
See also:
SharkSslConTrust and SharkSslCon_trustedCA
SHARKSSL_API U8 SharkSslCon_trustedCA ( SharkSslCon o )

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.

See also:
SharkSslCon_trusted