Detailed Description

Optional high level certificate management API.

The Certificate Management API enables you to dynamically assemble certificates in a running system. The assembled data can then be used as input for a SharkSsl object and is installed by calling function SharkSsl_setCAList.

The following code snippet, which shows how to assemble a SharkSslCAList, is from the example code certcheck.c:

      fCA_content = (U8*)baMalloc(fstat.st_size);
      if (fCA_content)
      {
         fCA_size = 0;
         while (((len = fread(fCA_content + fCA_size, sizeof(char), 512,
                                    fCA)) > 0) && (fCA_size < fstat.st_size))
         {
            fCA_size += len;
         }
         SharkSslCertStore_constructor(&certStore);
         SharkSslCertStore_add(
            &certStore, (const char*)fCA_content, (U32)fCA_size);
         SharkSslCertStore_assemble(&certStore, &caList);
         baFree(fCA_content);
      }
      fclose(fCA);

Note: Another option to using the Certificate Management API at runtime is to pre-process a SharkSslCAList at compile time. Such a list can then be stored in flash memory, thus saving memory in memory constrained devices. See the command line tool SharkSSLParseCAList for more information.

Data Structures
struct	SharkSslCertStore
	SharkSslCertStore is a container object used when assembling a SharkSslCAList. More...

Macros
#define	SharkSslECCKey_create(privKey, curveID) SharkSslECCKey_createEx((privKey), (curveID), 0, 0)
	A macro for creating an ECC key using the SharkSSL library. More...

#define	SharkSslCertStore_release(o) SharkSslCertStore_destructor(o)
	Alias for SharkSslCertStore_destructor.

Typedefs
typedef struct SharkSslCertStore	SharkSslCertStore
	SharkSslCertStore is a container object used when assembling a SharkSslCAList. More...

Functions
SHARKSSL_API U16	SharkSslCert_len (SharkSslCert cert)
	Get certificate length. More...

SHARKSSL_API int	SharkSslASN1Create_CSR (struct SharkSslASN1Create o, SharkSslKey privKey, U8 hashID, struct SharkSslCertDN certDN, const char SAN, struct SharkSslBitExtReq keyUsage, struct SharkSslBitExtReq *nsCertType)
	CSR creation (all parameters are input parameters) More...

SHARKSSL_API int	SharkSslCert_signCSR (SharkSslCert signedCSR, const U8 csrData, int csrDataLen, const SharkSslCert caCert, const SharkSslKey privKey, const char validFrom, const char validTo, SharkCertSerialNumber serialNumber, U8 hashID)
	CSR signing (if not specified, parameters are input parameters) More...

SHARKSSL_API int	SharkSslRSAKey_create (SharkSslRSAKey *privKey, U16 keyLength)
	RSA key creation. More...

SHARKSSL_API U8 *	SharkSslRSAKey_getPublic (SharkSslRSAKey privKey)
	RSA public key extraction from a private key. More...

SHARKSSL_API U16	SharkSslRSAKey_size (SharkSslRSAKey key)
	Returns the private or public key's modulus size in bytes.

SHARKSSL_API U16	SharkSslKey_vectSize (const SharkSslKey key)
	Returns the private or public key's "vector size" in bytes. More...

SHARKSSL_API int	SharkSslECCKey_createEx (SharkSslECCKey privKey, U16 curveID, void rngHandle, sharkssl_rngfunc rngFunc)
	Creates an ECC key using the SharkSSL library. More...

SHARKSSL_API void	SharkSslECCKey_free (SharkSslECCKey key)
	Release a SharkSslECCKey allocated by functions sharkssl_PEM_to_ECCKey or SharkSslECCKey_create.

SHARKSSL_API void	SharkSslCertStore_constructor (SharkSslCertStore *o)
	Initialize a SharkSslCertStore object. More...

SHARKSSL_API void	SharkSslCertStore_destructor (SharkSslCertStore *o)
	Cleanup all memory used by the SharkSslCAList object.

SHARKSSL_API U16	SharkSslCertStore_add (SharkSslCertStore o, const char cert, U32 certlen)
	add a certificate in PEM or p7b format to the CA store. More...

SHARKSSL_API U8	SharkSslCertStore_assemble (SharkSslCertStore o, SharkSslCAList outList)
	Assemble all certificates added by calling SharkSslCertStore_add. More...

Macro Definition Documentation

◆ SharkSslECCKey_create

#define SharkSslECCKey_create	(	privKey,
		curveID
	)	SharkSslECCKey_createEx((privKey), (curveID), 0, 0)

A macro for creating an ECC key using the SharkSSL library.

This macro simplifies the creation of an ECC key by calling the SharkSslECCKey_createEx function with default values for the random number generator (RNG) handle and function.

Parameters

privKey	Pointer to a `SharkSslECCKey` structure that will hold the generated private key.
curveID	The curve identifier (`curveID`) specifying which elliptic curve to use.

Note: This macro automatically sets rngHandle and rngFunc to 0, which means the default RNG mechanism will be used.

See also: SharkSslECCKey_createEx

Typedef Documentation

◆ SharkSslCertStore

typedef struct SharkSslCertStore SharkSslCertStore

SharkSslCertStore is a container object used when assembling a SharkSslCAList.

Without a certificate store, function SharkSslCon_trustedCA() will only return FALSE (not trusted).

A certificate store is required when a TLS client must validate the server's certificate and the complete chain. See the tutorial Certificate Management for an introduction to Public Key Infrastructure or PKI for short.

Example:

SharkSslCertStore certStore;
SharkSslCertStore_constructor(&certStore);
SharkSslCertStore_add(&certStore, cert, certLen);
SharkSslCertStore_assemble(&certStore, &caList);

Function Documentation

◆ SharkSslASN1Create_CSR()

SHARKSSL_API int SharkSslASN1Create_CSR	(	struct SharkSslASN1Create *	o,
		SharkSslKey	privKey,
		U8	hashID,
		struct SharkSslCertDN *	certDN,
		const char *	SAN,
		struct SharkSslBitExtReq *	keyUsage,
		struct SharkSslBitExtReq *	nsCertType
	)

CSR creation (all parameters are input parameters)

Note: after successful execution, the function SharkSslASN1Create_getDataLen must be called.

Example:

U8 *asnData;
int asnDataLen;
SharkSslASN1Create asn;
 
SharkSslASN1Create_CSR(&asn, <additional parameters>)
asnDataLen = SharkSslASN1Create_getDataLen(&asn, &asnData);

The blob 'asnData' is the CSR in binary format.

Parameters

o	pointer to an initialized SharkSslASN1Create instance.
privKey	a private key (ECC or RSA) in SharkSSL format. The key can be created with SharkSslECCKey_create and SharkSslRSAKey_create.
hashID	an identifier for the digest function used in the CSR signature Allowed values are: SHARKSSL_HASHID_SHA512 SHARKSSL_HASHID_SHA384 SHARKSSL_HASHID_SHA256
certDN	pointer to an initialized SharkSslCertDN instance.
SAN	pointer to a string where Subject Alternative Names are listed. Multiple names and/or IP addresses can be specified separating them by semicolons. Note: SAN must include the common name set in SharkSslCertDN. The subject alternative name may include an IP address in the form "IP:IPv4"; example: "localhost;IP:127.0.0.1"
keyUsage	flags used to specify the key usage. You may use the following flags and combine them by a bitwise OR: SHARKSSL_X509_KU_DIGITAL_SIGNATURE SHARKSSL_X509_KU_NON_REPUDIATION SHARKSSL_X509_KU_KEY_ENCIPHERMENT SHARKSSL_X509_KU_DATA_ENCIPHERMENT SHARKSSL_X509_KU_KEY_AGREEMENT SHARKSSL_X509_KU_KEY_CERT_SIGN SHARKSSL_X509_KU_CRL_SIGN
nsCertType	flags used to specify the "Netscape" certificate type. You may use the following flags and combine them by a bitwise OR: SHARKSSL_X509_NS_CERT_TYPE_SSL_CLIENT SHARKSSL_X509_NS_CERT_TYPE_SSL_SERVER SHARKSSL_X509_NS_CERT_TYPE_OBJECT_SIGNING SHARKSSL_X509_NS_CERT_TYPE_SSL_CA SHARKSSL_X509_NS_CERT_TYPE_OBJECT_SIGNING_CA

Returns: 0 on success, otherwise a negative value is returned on error, where the typical reason would be that the buffer is full.

◆ SharkSslCert_len()

SHARKSSL_API U16 SharkSslCert_len ( SharkSslCert cert )

Get certificate length.

Parameters

cert	a valid SharkSSL certificate

◆ SharkSslCert_signCSR()

SHARKSSL_API int SharkSslCert_signCSR	(	SharkSslCert *	signedCSR,
		const U8 *	csrData,
		int	csrDataLen,
		const SharkSslCert	caCert,
		const SharkSslKey	privKey,
		const char *	validFrom,
		const char *	validTo,
		SharkCertSerialNumber	serialNumber,
		U8	hashID
	)

CSR signing (if not specified, parameters are input parameters)

Parameters

signedCSR	[output variable] is a certificate in SharkSSL format. Variable signedCSR will on successfull execution point to allocated memory that can be freed by calling baFree(signedCSR); Please notice that the SharkSSL certificate format includes both the certificate and the private key. See the privKey parameter for more information.
csrData	pointer to a CSR, see SharkSslASN1Create_CSR and SharkSslASN1Create_getDataLen. CSR is in binary DER format.
csrDataLen	CSR length, see SharkSslASN1Create_getDataLen
caCert	a CA certificate in SharkSSL format or NULL if the CSR is to be self-signed – that is, when issuer is the same as subject. This certificate may be obtained by using the SharkSslParseCert tool. Note that the SharkSSL certificate format includes both the CA certificate and the CA private key, where the latter will be used to sign the certificate obtained from the CSR.
privKey	the private key (ECC or RSA) matching the CSR's public key, in SharkSSL format. The key may for example be obtained by using the SharkSslParseKey tool. if the parameter caCert is NULL (self-signing), this key will be used to sign the certificate. This function is primarily designed for creating SharkSSL certificates, which include both the key and the certificate. The key should therefore normally be provided for both self signed certificates and certificates that is to be signed by the caCert (arg 4). However, the key may be set to NULL when the caCert is provided. The produced SharkSSL certificate will then include a combined key/certificate, where the key is set to a dummy variable. This mode is designed when one must save the certificate as a X.509 certificate. The produced certificate , with the dummy key, cannot be used as argument to SharkSsl_addCertificate.
validFrom	string in format YYYYMMDDHHMMSS. The certificate is valid starting from this date.
validTo	string in format YYYYMMDDHHMMSS. The certificate is valid until this date.
serialNumber	serial number for the generated certificate.
hashID	an identifier for the digest function used in the certificate signature. Allowed values are: SHARKSSL_HASHID_SHA256 SHARKSSL_HASHID_SHA384 SHARKSSL_HASHID_SHA512

Returns: the number of allocated bytes for the signed certificate or a negative value on error, where the typical reason would be that allocation fails. This is a binary format that can be saved to RAM or Flash by saving the returned allocated number of bytes starting at the address pointed to by 'signedCSR'

◆ SharkSslCertStore_add()

SHARKSSL_API U16 SharkSslCertStore_add	(	SharkSslCertStore *	o,
		const char *	cert,
		U32	certlen
	)

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.

Parameters

o	the SharkSslCertStore object.
cert	is a one PEM cert or multiple certs in p7b format.
certlen	is the length of parameter 'cert'

See also: SharkSslCertStore_assemble.

Returns: the number of certificates successfully parsed and added to the certificate store or a negative value if memory could not be allocated.

◆ SharkSslCertStore_assemble()

SHARKSSL_API U8 SharkSslCertStore_assemble	(	SharkSslCertStore *	o,
		SharkSslCAList *	outList
	)

Assemble all certificates added by calling SharkSslCertStore_add.

The assembled SharkSslCAList object contains pointers to the SharkSslCertStore object, thus the SharkSslCertStore object cannot be released/terminated as long as the SharkSslCAList object is in use.

Parameters

o	the SharkSslCertStore object
outList	is the SharkSslCAList out value

Returns: TRUE on success or FALSE if memory could not be allocated

See also: SharkSslCertStore_destructor and SharkSsl_setCAList

◆ SharkSslCertStore_constructor()

SHARKSSL_API void SharkSslCertStore_constructor ( SharkSslCertStore * o )

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.

Parameters

o	Uninitialized data of size sizeof(SharkSsl).

See also: SharkSslCertStore_assemble.

◆ SharkSslECCKey_createEx()

SHARKSSL_API int SharkSslECCKey_createEx	(	SharkSslECCKey *	privKey,
		U16	curveID,
		void *	rngHandle,
		sharkssl_rngfunc	rngFunc
	)

Creates an ECC key using the SharkSSL library.

Parameters

privKey	[output parameter] points to a buffer allocated by SharkSslECCKey_create and which contains the generated private ECC key; the key is represented in a the SharkSSL format.
curveID	is one of: SHARKSSL_EC_CURVE_ID_SECP256R1 SHARKSSL_EC_CURVE_ID_SECP384R1 SHARKSSL_EC_CURVE_ID_SECP521R1 SHARKSSL_EC_CURVE_ID_BRAINPOOLP256R1 SHARKSSL_EC_CURVE_ID_BRAINPOOLP384R1 SHARKSSL_EC_CURVE_ID_BRAINPOOLP512R1 SHARKSSL_EC_CURVE_ID_CURVE25519 SHARKSSL_EC_CURVE_ID_CURVE448
rngHandle	optional object handle/instance for rngFunc
rngFunc	You can use your own random generator function for creating the key

Returns: the number of allocated bytes if the key creation was successful. A negative value is returned on error – e.g. allocation error. They key is in a binary format that can be saved to RAM or Flash by saving the returned allocated number of bytes starting at the address pointed to by 'privKey'

Note: the key must be saved after creating it if the key must be persistent. The following example shows how to create and save a key.

SharkSslECCKey createAndSaveKey(const char* filename)
{
   SharkSslECCKey privKey;
   int len = SharkSslECCKey_create(&privKey, SHARKSSL_EC_CURVE_ID_SECP256R1,0,0);
   if(len > 0)
   {
      FILE* fp = fopen(filename, "w");
      if(fp)
      {
         fwrite(privKey, sizeof(U8), len, fp);
         fclose(fp);
         return privKey;
      }
   }
   return 0;
}

◆ SharkSslKey_vectSize()

SHARKSSL_API U16 SharkSslKey_vectSize ( const SharkSslKey key )

Returns the private or public key's "vector size" in bytes.

The "vector size" is the size of the key as represented as an array of bytes in the SharkSSL internal proprietary format. This function is useful for key comparison or saving.

◆ SharkSslRSAKey_create()

SHARKSSL_API int SharkSslRSAKey_create	(	SharkSslRSAKey *	privKey,
		U16	keyLength
	)

RSA key creation.

Parameters

privKey	[output parameter] points to a buffer allocated by SharkSslRSAKey_create and which contains the generated private RSA key; the key is represented in the SharkSSL format.
keyLength	key length in bits, valid values: 1024, 2048, 4096; other key length are not currently supported for certificate creation.

Returns: the number of allocated bytes if the key creation was successful. A negative value is returned on error – e.g. allocation error. They key is in a binary format that can be saved to RAM or Flash by saving the returned allocated number of bytes starting at the address pointed to by 'privKey'

Note: the key must be saved after creating it if the key must be persistent. See the SharkSslECCKey_create example for more information.

◆ SharkSslRSAKey_getPublic()

SHARKSSL_API U8 * SharkSslRSAKey_getPublic ( SharkSslRSAKey privKey )

RSA public key extraction from a private key.

Parameters

privKey [input parameter] RSA key represented in the internal SharkSSL format. See the privKey parameter in SharkSslRSAKey_create function.

Returns: a pointer to the RSA public key as sequence of bytes. The RSA public key is a modulo and its length can be determined by calling the function SharkSslRSAKey_size and passing to it the RSA key privKey.

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ SharkSslECCKey_create

Typedef Documentation

◆ SharkSslCertStore

Example:

Function Documentation

◆ SharkSslASN1Create_CSR()

◆ SharkSslCert_len()

◆ SharkSslCert_signCSR()

◆ SharkSslCertStore_add()

◆ SharkSslCertStore_assemble()

◆ SharkSslCertStore_constructor()

◆ SharkSslECCKey_createEx()

◆ SharkSslKey_vectSize()

◆ SharkSslRSAKey_create()

◆ SharkSslRSAKey_getPublic()