SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
Certificate Management API

Detailed Description

Optional high level certificate management API.

The certificate APIs cover key/certificate conversion, trusted CA-list assembly, and optional certificate creation. Install a CA list with SharkSsl_setCAList and a local identity with SharkSsl_addCertificate. These are different inputs. See Create and Validate Certificates for CSR signing and issuer validation; assembly alone does not issue a certificate.

See the CertCheck.c example for file loading, conversion, and error handling. The conversion sequence is described in certificate management.

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

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 SharkSslASN1Create_key (struct SharkSslASN1Create *o, const SharkSslKey key)
 CSR signing policy and SharkSslCert_signCSR are declared in SharkSslCSR.h. More...
 
SHARKSSL_API int SharkSslCertInfo_parseCert (SharkSslCertInfo *o, const U8 *der, U32 len)
 Parse a DER certificate and return its certificate information. 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. 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. More...
 
SHARKSSL_API U16 SharkSslKey_vectSize (const SharkSslKey key)
 Returns the private or public key's "vector size" in bytes. More...
 
SHARKSSL_API U16 SharkSslKey_vectSize_keyInfo (const SharkSslKey key, U8 *keyType, U8 *isKeyPrivate, U8 **d1, U16 *d1Len, U8 **d2, U16 *d2Len)
 Returns the private or public key's "vector size" in bytes. More...
 
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. More...
 
SHARKSSL_API U16 SharkSslCertStore_add (SharkSslCertStore *o, const char *cert, U32 certlen)
 Add one or more certificates 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

◆ SharkSslCertStore_release

#define SharkSslCertStore_release (   o)    SharkSslCertStore_destructor(o)

Alias for SharkSslCertStore_destructor.

◆ 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
privKeyPointer to a SharkSslECCKey structure that will hold the generated private key.
curveIDThe 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

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_add(&certStore, cert, certLen);
SharkSslCertStore_assemble(&certStore, &caList);
SHARKSSL_API void SharkSslCertStore_constructor(SharkSslCertStore *o)
Initialize a SharkSslCertStore object.
SHARKSSL_API U16 SharkSslCertStore_add(SharkSslCertStore *o, const char *cert, U32 certlen)
Add one or more certificates to the CA store.
SHARKSSL_API U8 SharkSslCertStore_assemble(SharkSslCertStore *o, SharkSslCAList *outList)
Assemble all certificates added by calling SharkSslCertStore_add.
SharkSslCertStore is a container object used when assembling a SharkSslCAList.
Definition: SharkSSL.h:2834

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);
#define SharkSslASN1Create_getDataLen(o, startOfDataPtr)
Returns the length of the ASN.1 encoded data.
Definition: SharkSslASN1.h:281
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)
Opaque object used when creating ASN.1 encoded data.
Definition: SharkSslASN1.h:255

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, separated by semicolons (at most 255 bytes total). An unprefixed entry is a DNS name; "IP:IPv4" supplies an IPv4 address and "URI:value" supplies a URI. Prefixes are case-sensitive. Example: "localhost;IP:127.0.0.1;URI:urn:example:application". To request an OPC UA application certificate, include exactly one URI equal to the ApplicationUri and the server's DNS name or IP address. An empty string omits SANs for a CA request. Literal semicolons delimit entries; percent-encode them when they belong to a URI.
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.

◆ SharkSslASN1Create_key()

SHARKSSL_API int SharkSslASN1Create_key ( struct SharkSslASN1Create *  o,
const SharkSslKey  key 
)

CSR signing policy and SharkSslCert_signCSR are declared in SharkSslCSR.h.

Convert a SharkSslKey to ASN.1 representation. See the example file CSR.c for how to use this function.

Parameters
othe ASN.1 instance
keya valid SharkSslKey
Returns
zero on success, otherwise a negative value is returned.

◆ SharkSslCert_len()

U16 SharkSslCert_len ( SharkSslCert  cert)

Get certificate length.

Parameters
certa valid SharkSSL certificate
Returns
U16; encoded DER certificate length in bytes, including its sequence header, or 65535 ((U16)-1) if the pointer/header/length is unrecognized. This does not include an attached private key or validate an allocation boundary.

◆ SharkSslCertInfo_parseCert()

int SharkSslCertInfo_parseCert ( SharkSslCertInfo *  o,
const U8 *  der,
U32  len 
)

Parse a DER certificate and return its certificate information.

der includes the ASN.1 sequence header; len is its actual byte length. Returns 0 on success, -1 on failure. On failure, o is unchanged. Returned pointers borrow storage from der, which must remain alive. Date and SAN fields have explicit lengths and are not NULL-terminated. Parsing does not verify the issuer's signature or establish chain trust.

Parameters
oSharkSslCertInfo *; required caller-owned result storage; unchanged on failure.
derconst U8 *; required complete DER certificate, including its ASN.1 sequence header. Result pointers borrow these bytes.
lenU32; actual available DER byte length.
Returns
int: 0 on successful parsing; -1 on failure. Parsing alone verifies neither trust nor the issuer signature.

◆ SharkSslCertStore_add()

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

Add one or more certificates to the CA store.

The input may contain one binary DER or PEM certificate, multiple PEM certificates, or a PKCS#7/P7B certificate container.

Parameters
othe SharkSslCertStore object.
certthe certificate data.
certlenthe length of parameter cert in bytes.
Returns
the number of certificates added by this call, or zero if no certificate was added. Processing multi-certificate input is best-effort: malformed or unsupported entries that can be isolated are skipped. Invalid framing or an allocation failure may stop processing; certificates added before that failure remain in the store and are included in the return value. The return value is not the total number of certificates in the store.
See also
SharkSslCertStore_assemble.

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

◆ SharkSslCertStore_destructor()

void SharkSslCertStore_destructor ( SharkSslCertStore *  o)

Cleanup all memory used by the SharkSslCAList object.

Parameters
oSharkSslCertStore *; required initialized caller-owned store. Releases its assembled list and owned certificate allocations; no SharkSsl object may still reference them.

◆ 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.
curveIDis 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
rngHandleoptional object handle/instance for rngFunc
rngFuncYou 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. The 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;
if(len > 0)
{
FILE *fp = fopen(filename, "w");
if(fp)
{
fwrite(privKey, sizeof(U8), len, fp);
fclose(fp);
return privKey;
}
}
return 0;
}
#define SHARKSSL_EC_CURVE_ID_SECP256R1
To be used as hashlen parameter in sharkssl_ECDSA_ functions These are the hash lengths for the funct...
Definition: SharkSSL.h:2431
U8 * SharkSslECCKey
SharkSslECCKey is an alias for the SharkSslCert type and is a private/public key converted by sharkss...
Definition: SharkSSL.h:2495
#define SharkSslECCKey_create(privKey, curveID)
A macro for creating an ECC key using the SharkSSL library.
Definition: SharkSSL.h:2550

◆ SharkSslECCKey_free()

void SharkSslECCKey_free ( SharkSslECCKey  key)

Release a SharkSslECCKey allocated by functions sharkssl_PEM_to_ECCKey or SharkSslECCKey_create.

Parameters
keySharkSslECCKey; dynamically allocated key returned by a conversion/creation API, or NULL. Do not pass static generated key arrays; release every borrower first.

◆ SharkSslKey_vectSize()

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.

Parameters
keySharkSslKey; readable complete SharkSSL certificate/key blob, or NULL.
Returns
U16; complete serialized vector size in bytes, including its encoding/padding, or zero when unrecognized. The input has no length argument: provide a complete trusted allocation, not unbounded network data.

◆ SharkSslKey_vectSize_keyInfo()

U16 SharkSslKey_vectSize_keyInfo ( const SharkSslKey  key,
U8 *  keyType,
U8 *  isKeyPrivate,
U8 **  d1,
U16 *  d1Len,
U8 **  d2,
U16 *  d2Len 
)

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. Returns 0 if the key is not valid. keyType: return value, either SHARKSSL_KEYTYPE_RSA or SHARKSSL_KEYTYPE_EC isKeyPrivate: 0 if public key, 1 if private key if the keyType is SHARKSSL_KEYTYPE_RSA: d1: pointer to the modulus, a sequence of bytes in big endian format of length d1Len d2: pointer to the exponent, a sequence of bytes in big endian format of length d2Len if the keyType is SHARKSSL_KEYTYPE_EC: d1: pointer to the X coordinate, a sequence of bytes in big endian format of length d1Len d2: pointer to the Y coordinate, a sequence of bytes in big endian format of length d2Len This function is useful to extract info from a key.

Parameters
keySharkSslKey; readable complete SharkSSL certificate/key blob, or NULL.
keyTypeU8 *; optional output SHARKSSL_KEYTYPE_RSA or SHARKSSL_KEYTYPE_EC.
isKeyPrivateU8 *; optional output: 1 for private-key material, 0 for a public key.
d1U8 **; optional borrowed output pointer to RSA modulus or EC X coordinate. Do not free or modify it.
d1LenU16 *; optional byte length of d1.
d2U8 **; optional borrowed output pointer to RSA exponent or EC Y coordinate. Do not free or modify it.
d2LenU16 *; optional byte length of d2.
Returns
U16; serialized vector size in bytes, or zero on failure. Output fields are meaningful only on success and borrow the input lifetime. No allocation-boundary validation is possible without an input length.

◆ 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.
keyLengthU16; requested key length in bits, from 128 through 4096, divisible by twice SHARKSSL_BIGINT_WORDSIZE. This includes 2048, 3072 and 4096 bits. These are input-validation limits, not a security recommendation; select a key size meeting your application policy and certificate profile.
Returns
the number of allocated bytes if the key creation was successful. A negative value is returned on error – e.g. allocation error. The 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()

U16 SharkSslRSAKey_size ( SharkSslRSAKey  key)

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

Parameters
keySharkSslRSAKey; readable SharkSSL-encoded RSA key, or NULL.
Returns
U16; RSA modulus length in bytes, or zero for an unrecognized/non-RSA key. This is not the total serialized blob size.