Detailed Description

The SharkSSL API.

more stuff here. Fixme.

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

SharkSslCon *	SharkSsl_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 SharkSslCertInfo *	SharkSslCon_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_setCertificateAuthorities (SharkSslCon o, const void caList)
	This function is used by client solutions that require server SSL certificate authentication. More...

SHARKSSL_API U8	SharkSslCon_setALPNProtocols (SharkSslCon o, const char protList)
	This function is used by client solutions to specify a list of application layer protocols according to RFC 7301 (ALPN). More...

SHARKSSL_API const char *	SharkSslCon_getALPNProtocol (SharkSslCon *o)
	This function is used by client solutions to return the application layer protocol selected by the server among the ones specified through SharkSslCon_setALPNProtocols. 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...

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

o	Uninitialized data of size sizeof(SharkSsl).
role	Select client or server SSL mode. See SharkSsl_Role for details.
cacheSize	The session resumption cache size. Setting this to zero disables the cache management code. See SSL Session Management for details.
inBufStartSize
outBufSize

parameter 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;
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_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

o	the SharkSsl object.
caList	list 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

o	the SharkSsl object. Setting this parameter to NULL is the same as calling macro SharkSslCon_terminate.
con	the 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_getALPNProtocol()

SHARKSSL_API const char * SharkSslCon_getALPNProtocol ( SharkSslCon * o )

This function is used by client solutions to return the application layer protocol selected by the server among the ones specified through SharkSslCon_setALPNProtocols.

This function has to be called after the handshake has been initiated.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.

Returns: NULL if none of the application layer protocols specified by the client have been selected by the server, or a pointer to the protocol name selected by the server - this pointer is to the string passed via the function SharkSslCon_setALPNProtocols; please be aware that the protocol name can be terminated by a NULL or a comma, according to the passed string.

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

◆ 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

o	the 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

o the SharkSslCon object returned by function SharkSsl_createCon.

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

o	the SharkSslCon object returned by function SharkSsl_createCon.
cipherSuite	is 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_setALPNProtocols()

SHARKSSL_API U8 SharkSslCon_setALPNProtocols	(	SharkSslCon *	o,
		const char *	protList
	)

This function is used by client solutions to specify a list of application layer protocols according to RFC 7301 (ALPN).

It must be called before the initial handshake has started.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
protList	a string of comma separated protocols. Do not specify a final comma at the end of the string. This string must be a constant string stored in ROM for the function SharkSslCon_getALPNProtocol to work properly.

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

SHARKSSL_API U8 SharkSslCon_setCertificateAuthorities	(	SharkSslCon *	o,
		const void *	caList
	)

This function is used by client solutions that require server SSL certificate authentication.

It implements the "Certificate Authorities" extension as per RFC 8446, section 4.2.4.

The function must be called before the initial handshake has started.

Parameters

o	the SharkSslCon object returned by function SharkSsl_createCon.
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.

Whenever the server is requested to provide an SSL certificate, this certificate must be signed using one of the CA certificates provided in the caList. The SSL handshake fails if the server's certificate is not trusted or not signed with a known CA certificate. In practice, for the specific connection, caList will take over the list associated with the SharkSSL object via SharkSsl_setCAList.

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

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

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

This function extends SharkSslCon_trustedCA and also checks that the domain name (including any wildcards) matches the domain name. The function also checks the certificate's date if the SharkSSL code is compiled with SHARKSSL_CHECK_DATE =1.

Parameters

o	the SharkSslCon object
name	is the domain name (common name)
cPtr	is 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 and its chain. You must typically also validate the domain name and the certificate's date. Function SharkSslCon_trusted extends the certificate validation and also includes domain name validation and date check.

See also: SharkSslCon_trusted

Detailed Description

Modules

Macros

Functions

Macro Definition Documentation

◆ SharkSslCon_terminate

Function Documentation

◆ SharkSsl_addCertificate()

◆ SharkSsl_constructor()

◆ SharkSsl_createCon()

◆ SharkSsl_destructor()

◆ SharkSsl_getCacheSize()

◆ SharkSsl_setCAList()

◆ SharkSsl_terminateCon()

◆ SharkSslCon_favorRSA()

◆ SharkSslCon_getALPNProtocol()

◆ SharkSslCon_getCertInfo()

◆ SharkSslCon_renegotiate()

◆ SharkSslCon_requestClientCert()

◆ SharkSslCon_selectCiphersuite()

◆ SharkSslCon_setALPNProtocols()

◆ SharkSslCon_setCertificateAuthorities()

◆ SharkSslCon_trusted()

◆ SharkSslCon_trustedCA()