|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
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... | |
| #define SharkSslCertStore_release | ( | o | ) | SharkSslCertStore_destructor(o) |
Alias for SharkSslCertStore_destructor.
| #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.
| privKey | Pointer to a SharkSslECCKey structure that will hold the generated private key. |
| curveID | The curve identifier (curveID) specifying which elliptic curve to use. |
rngHandle and rngFunc to 0, which means the default RNG mechanism will be used.| 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.
| 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:
The blob 'asnData' is the CSR in binary format.
| 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, 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. |
| 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 |
| 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.
| o | the ASN.1 instance |
| key | a valid SharkSslKey |
| U16 SharkSslCert_len | ( | SharkSslCert | cert | ) |
Get certificate length.
| cert | a valid SharkSSL certificate |
| 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.
| o | SharkSslCertInfo *; required caller-owned result storage; unchanged on failure. |
| der | const U8 *; required complete DER certificate, including its ASN.1 sequence header. Result pointers borrow these bytes. |
| len | U32; actual available DER byte length. |
| 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.
| o | the SharkSslCertStore object. |
| cert | the certificate data. |
| certlen | the length of parameter cert in bytes. |
| 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.
| o | the SharkSslCertStore object |
| outList | is the SharkSslCAList out value |
| 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.
| o | Uninitialized data of size sizeof(SharkSsl). |
| void SharkSslCertStore_destructor | ( | SharkSslCertStore * | o | ) |
Cleanup all memory used by the SharkSslCAList object.
| o | SharkSslCertStore *; required initialized caller-owned store. Releases its assembled list and owned certificate allocations; no SharkSsl object may still reference them. |
| SHARKSSL_API int SharkSslECCKey_createEx | ( | SharkSslECCKey * | privKey, |
| U16 | curveID, | ||
| void * | rngHandle, | ||
| sharkssl_rngfunc | rngFunc | ||
| ) |
Creates an ECC key using the SharkSSL library.
| 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:
|
| rngHandle | optional object handle/instance for rngFunc |
| rngFunc | You can use your own random generator function for creating the key |
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.
| void SharkSslECCKey_free | ( | SharkSslECCKey | key | ) |
Release a SharkSslECCKey allocated by functions sharkssl_PEM_to_ECCKey or SharkSslECCKey_create.
| key | SharkSslECCKey; dynamically allocated key returned by a conversion/creation API, or NULL. Do not pass static generated key arrays; release every borrower first. |
| 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.
| key | SharkSslKey; readable complete SharkSSL certificate/key blob, or NULL. |
| 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.
| key | SharkSslKey; readable complete SharkSSL certificate/key blob, or NULL. |
| keyType | U8 *; optional output SHARKSSL_KEYTYPE_RSA or SHARKSSL_KEYTYPE_EC. |
| isKeyPrivate | U8 *; optional output: 1 for private-key material, 0 for a public key. |
| d1 | U8 **; optional borrowed output pointer to RSA modulus or EC X coordinate. Do not free or modify it. |
| d1Len | U16 *; optional byte length of d1. |
| d2 | U8 **; optional borrowed output pointer to RSA exponent or EC Y coordinate. Do not free or modify it. |
| d2Len | U16 *; optional byte length of d2. |
| SHARKSSL_API int SharkSslRSAKey_create | ( | SharkSslRSAKey * | privKey, |
| U16 | keyLength | ||
| ) |
RSA key creation.
| 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 | U16; 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. |
Note: the key must be saved after creating it if the key must be persistent. See the SharkSslECCKey_create example for more information.
| SHARKSSL_API U8 * SharkSslRSAKey_getPublic | ( | SharkSslRSAKey | privKey | ) |
RSA public key extraction from a private key.
| privKey | [input parameter] RSA key represented in the internal SharkSSL format. See the privKey parameter in SharkSslRSAKey_create function. |
| U16 SharkSslRSAKey_size | ( | SharkSslRSAKey | key | ) |
Returns the private or public key's modulus size in bytes.
| key | SharkSslRSAKey; readable SharkSSL-encoded RSA key, or NULL. |