SharkSSL™ Embedded SSL/TLS Stack
Certificate Management API

Optional high level certificate management API. More...

Data Structures

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

Macros

#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)
 
SHARKSSL_API int SharkSslASN1Create_CSR (struct SharkSslASN1Create *o, SharkSslKey privKey, U8 hashID, struct SharkSslCertDN *certDN, const char *SAN, struct SharkSslBitExtReq *keyUsage, struct SharkSslBitExtReq *nsCertType)
 
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)
 
SHARKSSL_API int SharkSslRSAKey_create (SharkSslRSAKey *privKey, U16 keyLength)
 
SHARKSSL_API U8 * SharkSslRSAKey_getPublic (SharkSslRSAKey privKey)
 
SHARKSSL_API U16 SharkSslRSAKey_size (SharkSslRSAKey key)
 
SHARKSSL_API U16 SharkSslKey_vectSize (const SharkSslKey key)
 
SHARKSSL_API int SharkSslECCKey_create (SharkSslECCKey *privKey, U16 curveID)
 
SHARKSSL_API void SharkSslECCKey_free (SharkSslECCKey key)
 
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...
 

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;
}
&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.

Typedef Documentation

◆ SharkSslCertStore

SharkSslCertStore is a container object used when assembling a SharkSslCAList.

See SharkSslCertStore_assemble for details.

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_CSR(&asn, <additional parameters>)
asnDataLen = SharkSslASN1Create_getDataLen(&asn, &asnData);

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

Parameters
opointer to an initialized SharkSslASN1Create instance.
privKeya private key (ECC or RSA) in SharkSSL format. The key can be created with SharkSslECCKey_create and SharkSslRSAKey_create.
hashIDan identifier for the digest function used in the CSR signature Allowed values are: SHARKSSL_HASHID_SHA512 SHARKSSL_HASHID_SHA384 SHARKSSL_HASHID_SHA256
certDNpointer to an initialized SharkSslCertDN instance.
SANpointer 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"
keyUsageflags 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
nsCertTypeflags 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
certa 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.
csrDatapointer to a CSR, see SharkSslASN1Create_CSR and SharkSslASN1Create_getDataLen. CSR is in binary DER format.
csrDataLenCSR length, see SharkSslASN1Create_getDataLen
caCerta 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.
privKeythe 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.
validFromstring in format YYYYMMDDHHMMSS. The certificate is valid starting from this date.
validTostring in format YYYYMMDDHHMMSS. The certificate is valid until this date.
serialNumberserial number for the generated certificate.
hashIDan 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
othe SharkSslCertStore object.
certis a one PEM cert or multiple certs in p7b format.
certlenis 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
othe SharkSslCertStore object
outListis 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
oUninitialized data of size sizeof(SharkSsl).
See also
SharkSslCertStore_assemble.

◆ SharkSslECCKey_create()

SHARKSSL_API int SharkSslECCKey_create ( SharkSslECCKey privKey,
U16  curveID 
)

ECC key creation.

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.
curveIDis one of:
  • SHARKSSL_EC_CURVE_ID_SECP192R1
  • SHARKSSL_EC_CURVE_ID_SECP224R1
  • 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
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);
if(len > 0)
{
FILE* fp = fopen(filename, "w");
if(fp)
{
fwrite(privKey, sizeof(U8), len, fp);
fclose(fp);
return privKey;
}
}
return 0;
}

◆ SharkSslECCKey_free()

SHARKSSL_API void SharkSslECCKey_free ( SharkSslECCKey  key)

Release a SharkSslECCKey allocated by functions sharkssl_PEM_to_ECCKey or SharkSslECCKey_create

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

◆ SharkSslRSAKey_size()

SHARKSSL_API U16 SharkSslRSAKey_size ( SharkSslRSAKey  key)

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

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)
SharkSslCertStore_assemble
SHARKSSL_API U8 SharkSslCertStore_assemble(SharkSslCertStore *o, SharkSslCAList *outList)
Assemble all certificates added by calling SharkSslCertStore_add.
SharkSslASN1Create_getDataLen
#define SharkSslASN1Create_getDataLen(o, startOfDataPtr)
Returns the length of the ASN.1 encoded data.
Definition: SharkSslASN1.h:250
SharkSslECCKey_create
SHARKSSL_API int SharkSslECCKey_create(SharkSslECCKey *privKey, U16 curveID)
SharkSslCertStore_constructor
SHARKSSL_API void SharkSslCertStore_constructor(SharkSslCertStore *o)
Initialize a SharkSslCertStore object.
SharkSslECCKey
U8 * SharkSslECCKey
Definition: SharkSSL.h:2189
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.
SharkSslASN1Create
Opaque object used when creating ASN.1 encoded data.
Definition: SharkSslASN1.h:226