SharkSSL™ Embedded SSL/TLS Stack
SharkSSL API

The SharkSSL API. More...

Modules

 SharkSsl Configuration (macros)
 Add/remove SharkSSL features and/or optimize for speed versus size.
 
 Core API
 The transport agnostic SharkSSL API.
 
 SSL Session Management
 SSL Session resumption can significantly speed up the SSL handshaking.
 
 Certificate Management API
 Optional high level certificate management API.
 
 SharkSsl info and status
 SharkSsl information classes and return values.
 

Macros

#define SharkSslCon_terminate(o)   SharkSsl_terminateCon(0, o)
 The SharkSslCon object must be reclaimed when you close the network connection. More...
 
#define SHARKSSL_SET_FAVOR_RSA   1
 Description to be added.
 

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. More...
 
SHARKSSL_API void SharkSsl_destructor (SharkSsl *o)
 Close the SharkSsl object. More...
 
SharkSslConSharkSsl_createCon (SharkSsl *o)
 Create a SharkSslCon object. More...
 
void SharkSsl_terminateCon (const SharkSsl *o, SharkSslCon *con)
 Terminate a SharkSslCon object created by function SharkSsl_createCon. More...
 
SHARKSSL_API U16 SharkSsl_getCacheSize (SharkSsl *o)
 Returns the SharkSsl session cache size. More...
 
SHARKSSL_API U16 SharkSslCon_getCiphersuite (SharkSslCon *o)
 Returns the active session's chiper suite.
 
SHARKSSL_API U8 SharkSslCon_getProtocol (SharkSslCon *o)
 Returns the active session's 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. More...
 
SHARKSSL_API U8 SharkSsl_addCertificate (SharkSsl *o, SharkSslCert cert)
 Add a certificate to the SharkSsl object. More...
 
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. More...
 
SHARKSSL_API U8 SharkSslCon_trustedCA (SharkSslCon *o)
 Returns TRUE if the certificate is valid and is signed with a root certificate trusted by SharkSSL. More...
 
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). More...
 
SHARKSSL_API U8 SharkSslCon_requestClientCert (SharkSslCon *o, const void *caList)
 This function is used by server solutions that require client SSL certificate authentication. More...
 
SHARKSSL_API U8 SharkSslCon_selectCiphersuite (SharkSslCon *o, U16 cipherSuite)
 This function enables you to limit the number of ciphers at runtime. More...
 
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. More...
 
SHARKSSL_API SharkSslConTrust SharkSslCon_trusted (SharkSslCon *o, const char *name, SharkSslCertInfo **cPtr)
 Returns the peer's "trust" status and certificate. More...
 

Detailed Description

The SharkSSL API.

more stuff here. Fixme.

Macro Definition Documentation

◆ SharkSslCon_terminate

#define SharkSslCon_terminate (   o)    SharkSsl_terminateCon(0, o)

The SharkSslCon object must be reclaimed when you close the network connection.

See also
SharkSsl_createCon
SharkSsl_terminateCon

Function Documentation

◆ SharkSsl_addCertificate()

SHARKSSL_API U8 SharkSsl_addCertificate ( SharkSsl o,
SharkSslCert  cert 
)

Add a certificate to the SharkSsl object.

A SharkSsl object in server mode 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_constructor()

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

◆ SharkSsl_createCon()

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.

int rc;
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_destructor()

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_getCacheSize()

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_setCAList()

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

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_terminateCon()

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

/* Release resources used by scon */
SharkSsl_terminateCon(&sharkSsl, scon);
}
se_close(&sock);

◆ SharkSslCon_favorRSA()

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.

◆ SharkSslCon_getCertInfo()

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.

◆ SharkSslCon_renegotiate()

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.

◆ SharkSslCon_requestClientCert()

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

◆ SharkSslCon_selectCiphersuite()

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

◆ SharkSslCon_trusted()

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

◆ 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
SharkSsl_createCon
SharkSslCon * SharkSsl_createCon(SharkSsl *o)
Create a SharkSslCon object.
SharkSslCon
struct SharkSslCon SharkSslCon
SharkSslCon is an opaque handle returned by function SharkSsl_createCon.
Definition: SharkSSL.h:692
se_connect
int se_connect(SOCKET *sock, const char *address, U16 port)
Initializes a SOCKET object connected to a remote host/address at a given port.
se_close
void se_close(SOCKET *sock)
Close a connected socket connection.
SharkSsl_terminateCon
void SharkSsl_terminateCon(const SharkSsl *o, SharkSslCon *con)
Terminate a SharkSslCon object created by function SharkSsl_createCon.