|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
Cryptographic functions, including RSA, ECC, AES, hashing, etc..
The native crypto API includes RSA and elliptic-curve operations, AES, ChaCha20, Poly1305, hashes, HMAC, and random-number helpers. Optional APIs depend on the selected configuration. See Choose a SharkSSL API for the separate native and PSA consumer interfaces. Current public headers do not provide DES/3DES or ARC4 APIs.
Modules | |
| MD5 | |
| MD5 cryptographic hash. | |
| SHA1 | |
| SHA1 cryptographic hash. | |
| SHA256 | |
| SHA256 cryptographic hash. | |
| SHA384 | |
| SHA384 cryptographic hash. | |
| SHA512 | |
| SHA512 cryptographic hash. | |
| HMAC | |
| HMAC keyed-hash message authentication code (in conjunction with: MD5,SHA1,SHA256,SHA384,SHA512) | |
| AES | |
| AES. | |
| AES-GCM | |
| AES-GCM. | |
| AES-CCM | |
| AES-CCM. | |
| POLY1305 | |
| POLY1305. | |
| CHACHA20 | |
| CHACHA20. | |
| ECDSA sign/verify functions | |
| See Signing and Verifying Binaries for an example of how to use the ECDSA ECDSA sign/verify functions. | |
| RSA encrypt/decrypt functions | |
| Crypto context and buffer helpers | |
| Hash cloning, cleanup, one-shot adapters and representation helpers. | |
Functions | |
| SHARKSSL_API int | sharkssl_entropyEx (const U8 *entropy, U16 len) |
| Seed or reseed the native random-number generator. More... | |
| SHARKSSL_API sharkssl_PEM_RetVal | sharkssl_PEM (const char *certPEM, const char *keyPEM, const char *passphrase, SharkSslCert *sharkSslCert) |
| Create a SharkSslCert from PEM data. More... | |
| SHARKSSL_API sharkssl_PEM_RetVal | sharkssl_PEMEx (const char *certPEM, const char *keyPEM, const char *passphrase, SharkSslCert *sharkSslCert, U16 passphraseLen) |
| Convert PEM data using an explicit passphrase length. More... | |
| SHARKSSL_API int | sharkssl_PEM_PBKDF2Ex (U8 *dk, const char *passphrase, const char *salt, U32 saltLen, U32 iterations, U16 passphraseLen, U16 dkLen, U8 hashID) |
| Derive a key with PBKDF2-HMAC using an explicit password length. More... | |
| SHARKSSL_API int | sharkssl_PEM_PBKDF2 (U8 *dk, const char *passphrase, const char *salt, U32 saltLen, U32 iterations, U16 dkLen, U8 hashID) |
| sharkssl_PEM_PBKDF2 (output, passphrase, salt, salt_len, iterations, dkLen, hashID) Derives a key from a passphrase using the PBKDF2 algorithm as specified in RFC 8018 section 5.2. More... | |
| SHARKSSL_API int | sharkssl_X25519_createKeyPair (U8 privateKey[SHARKSSL_X25519_KEY_LEN], U8 publicKey[SHARKSSL_X25519_KEY_LEN]) |
| Create an X25519 private/public key pair. More... | |
| SHARKSSL_API int | sharkssl_X25519_sharedSecret (const U8 privateKey[SHARKSSL_X25519_KEY_LEN], const U8 peerPublicKey[SHARKSSL_X25519_KEY_LEN], U8 sharedSecret[SHARKSSL_X25519_KEY_LEN]) |
| Calculate an X25519 shared secret. More... | |
| enum sharkssl_PEM_RetVal |
Return values from function sharkssl_PEM.
| SHARKSSL_API int sharkssl_entropyEx | ( | const U8 * | entropy, |
| U16 | len | ||
| ) |
Seed or reseed the native random-number generator.
Available when SHARKSSL_PSA_CONSUMER is 0. A PSA consumer instead uses sharkssl_entropy() to initialize its provider, which manages entropy.
Supply the complete seed in one call before requesting random output or starting threads that use SharkSSL. The native deterministic random bit generator (DRBG) needs at least 48 entropy bytes for its first seed and at least 32 fresh entropy bytes for each later reseed. Buffer length alone does not establish entropy quality; obtain the bytes from a suitable platform entropy source. The function does not collect entropy itself.
With SHARKSSL_RNG_MULTITHREADED=1, later reseeds and random output are serialized by the global RNG mutex. With this option disabled, the application must serialize all access to the global RNG.
| entropy | const U8 *; required readable buffer containing len entropy bytes. Borrowed for this call only; it is neither retained nor erased. Clear a temporary seed buffer with sharkssl_clear() after the call. |
| len | U16; buffer length in bytes, 48 through 65535 for initial seeding or 32 through 65535 for reseeding. No default. |
| sharkssl_PEM_RetVal sharkssl_PEM | ( | const char * | certPEM, |
| const char * | keyPEM, | ||
| const char * | passphrase, | ||
| SharkSslCert * | sharkSslCert | ||
| ) |
Create a SharkSslCert from PEM data.
In a PSA consumer build, if keyPEM is NULL and certPEM is present, the result contains the public certificate chain and its public key, and SHARKSSL_PEM_OK_PUBLIC is returned. The caller owns the allocated result and must release it after SharkSSL no longer references it. A private key remains required for native TLS signing; a public-only result can be paired with a PSA signing key by using SharkSsl_addCertificatePSA.
example:
| certPEM | const char *; NUL-terminated PEM certificate/chain, or NULL for key-only conversion. Borrowed for the call. |
| keyPEM | const char *; NUL-terminated PEM key; may be NULL for the supported PSA public-certificate conversion. |
| passphrase | const char *; optional NUL-terminated password for an encrypted PEM key, or NULL. Borrowed. |
| sharkSslCert | SharkSslCert *; required result pointer. On success the caller owns the allocated blob; free it with baFree after all borrowers release it. |
| SHARKSSL_API int sharkssl_PEM_PBKDF2 | ( | U8 * | dk, |
| const char * | passphrase, | ||
| const char * | salt, | ||
| U32 | saltLen, | ||
| U32 | iterations, | ||
| U16 | dkLen, | ||
| U8 | hashID | ||
| ) |
sharkssl_PEM_PBKDF2 (output, passphrase, salt, salt_len, iterations, dkLen, hashID) Derives a key from a passphrase using the PBKDF2 algorithm as specified in RFC 8018 section 5.2.
This function performs the Password-Based Key Derivation Function 2 (PBKDF2) to derive a key from a given passphrase. The derived key is computed by iterating the specified hash function over the passphrase and salt.
| dk | pointer to the buffer where the derived key will be stored |
| passphrase | pointer to the passphrase (null-terminated string) used to derive the key |
| salt | pointer to the salt string used in the key derivation process |
| saltLen | length of the salt in bytes |
| iterations | number of iterations to perform in the key derivation process |
| dkLen | desired length of the derived key in bytes. |
| hashID | identifier for the digest function to use; allowed values are: SHARKSSL_HASHID_SHA512, SHARKSSL_HASHID_SHA384, SHARKSSL_HASHID_SHA256 |
| SHARKSSL_API int sharkssl_PEM_PBKDF2Ex | ( | U8 * | dk, |
| const char * | passphrase, | ||
| const char * | salt, | ||
| U32 | saltLen, | ||
| U32 | iterations, | ||
| U16 | passphraseLen, | ||
| U16 | dkLen, | ||
| U8 | hashID | ||
| ) |
Derive a key with PBKDF2-HMAC using an explicit password length.
The password may contain NUL bytes and does not need a terminator. Work depends on the public password, salt and output lengths, hash, and iteration count, not password bytes. sharkssl_PEM_PBKDF2() instead obtains the password length with strlen(). PSA builds use the selected provider. Requires SHARKSSL_ENABLE_PEM_API=1 and SHARKSSL_ENABLE_ENCRYPTED_PKCS8_SUPPORT=1.
| dk | U8 *; required caller-owned writable buffer of at least dkLen bytes. Receives the derived key on success. Do not overlap it with the password or salt. Discard its contents on failure. |
| passphrase | const char *; required readable password buffer, borrowed for this call. Supply a non-NULL pointer even for a zero-length password. |
| salt | const char *; saltLen readable salt bytes, borrowed for this call. May be NULL when saltLen is 0. No terminator is needed. |
| saltLen | U32; salt length in bytes, including zero. No default. |
| iterations | U32; iteration count, 1 through 4294967295. No default. |
| passphraseLen | U16; password length in bytes, 0 through 65535, including embedded NUL bytes. No default. |
| dkLen | U16; derived-key length in bytes, 1 through 65535. No default. |
| hashID | U8; enabled HMAC hash identifier. Native builds accept SHARKSSL_HASHID_MD5, SHARKSSL_HASHID_SHA1, SHARKSSL_HASHID_SHA256, SHARKSSL_HASHID_SHA384, or SHARKSSL_HASHID_SHA512 when the corresponding hash is enabled. PSA consumers accept SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512 identifiers when enabled and supported by the provider; MD5 is not accepted. No default. |
| SHARKSSL_API sharkssl_PEM_RetVal sharkssl_PEMEx | ( | const char * | certPEM, |
| const char * | keyPEM, | ||
| const char * | passphrase, | ||
| SharkSslCert * | sharkSslCert, | ||
| U16 | passphraseLen | ||
| ) |
Convert PEM data using an explicit passphrase length.
Like sharkssl_PEM(), but the passphrase may contain NUL bytes and does not need a terminator. passphraseLen is public; sharkssl_PEM() obtains this length by scanning its NUL-terminated passphrase. PEM labels, whitespace, encoded length and ASN.1 structure are public format information. Native encrypted AES keys are decrypted with the constant-time software AES.
| certPEM | const char *; NUL-terminated PEM certificate or certificate chain, or NULL for key-only conversion. Borrowed for this call. |
| keyPEM | const char *; NUL-terminated PEM public or private key, borrowed for this call. Required except when a PSA consumer converts a certificate chain without a private key; that case requires certPEM. Native conversion with certPEM requires a private key. |
| passphrase | const char *; passphraseLen readable password bytes for an encrypted key. May be NULL only when passphraseLen is 0. Borrowed for this call; embedded NUL bytes are included in the password. |
| sharkSslCert | SharkSslCert *; required pointer to the result variable. The caller owns any allocated result. Keep a successful result alive while SharkSSL references it, then release it with baFree(). On failure, discard and free any non-NULL result; an error does not always clear this pointer. |
| passphraseLen | U16; password length in bytes, 0 through 65535. Use 0 with a NULL passphrase. No default. |
| SHARKSSL_API int sharkssl_X25519_createKeyPair | ( | U8 | privateKey[SHARKSSL_X25519_KEY_LEN], |
| U8 | publicKey[SHARKSSL_X25519_KEY_LEN] | ||
| ) |
Create an X25519 private/public key pair.
| privateKey | receives the 32-byte private key. The key must be treated as opaque and passed unchanged to sharkssl_X25519_sharedSecret. |
| publicKey | receives the 32-byte RFC 7748 little-endian public u-coordinate. |
privateKey and publicKey must point to separate, non-overlapping 32-byte buffers. | SHARKSSL_API int sharkssl_X25519_sharedSecret | ( | const U8 | privateKey[SHARKSSL_X25519_KEY_LEN], |
| const U8 | peerPublicKey[SHARKSSL_X25519_KEY_LEN], | ||
| U8 | sharedSecret[SHARKSSL_X25519_KEY_LEN] | ||
| ) |
Calculate an X25519 shared secret.
| privateKey | a 32-byte private key generated by sharkssl_X25519_createKeyPair. The key must be passed unchanged to this function. |
| peerPublicKey | the peer's 32-byte RFC 7748 public key. |
| sharedSecret | receives the 32-byte shared secret. |