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

Detailed Description

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.
 

Enumerations

enum  sharkssl_PEM_RetVal {
  SHARKSSL_PEM_OK = 0 , SHARKSSL_PEM_OK_PUBLIC = 1 , SHARKSSL_PEM_ALLOCATION_ERROR = - 3000 , SHARKSSL_PEM_KEY_PARSE_ERROR ,
  SHARKSSL_PEM_KEY_WRONG_IV , SHARKSSL_PEM_KEY_WRONG_LENGTH , SHARKSSL_PEM_KEY_PASSPHRASE_REQUIRED , SHARKSSL_PEM_KEY_UNRECOGNIZED_FORMAT ,
  SHARKSSL_PEM_KEY_UNSUPPORTED_FORMAT , SHARKSSL_PEM_KEY_UNSUPPORTED_MODULUS_LENGTH , SHARKSSL_PEM_KEY_UNSUPPORTED_EXPONENT_LENGTH , SHARKSSL_PEM_KEY_UNSUPPORTED_ENCRYPTION_TYPE ,
  SHARKSSL_PEM_KEY_CERT_MISMATCH , SHARKSSL_PEM_CERT_UNRECOGNIZED_FORMAT , SHARKSSL_PEM_CERT_UNSUPPORTED_TYPE , SHARKSSL_PEM_KEY_UNSUPPORTED_VERSION ,
  SHARKSSL_PEM_KEY_REQUIRED , SHARKSSL_PEM_KEY_PRIVATE_KEY_REQUIRED , SHARKSSL_PEM_INTERNAL_ERROR
}
 Return values from function sharkssl_PEM. More...
 

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

Enumeration Type Documentation

◆ sharkssl_PEM_RetVal

Return values from function sharkssl_PEM.

Enumerator
SHARKSSL_PEM_OK 

OK.

SHARKSSL_PEM_OK_PUBLIC 

OK_PUBLIC.

SHARKSSL_PEM_ALLOCATION_ERROR 

ALLOCATION_ERROR.

SHARKSSL_PEM_KEY_PARSE_ERROR 

KEY_PARSE_ERROR.

SHARKSSL_PEM_KEY_WRONG_IV 

KEY_WRONG_IV.

SHARKSSL_PEM_KEY_WRONG_LENGTH 

KEY_WRONG_LENGTH.

SHARKSSL_PEM_KEY_PASSPHRASE_REQUIRED 

KEY_PASSPHRASE_REQUIRED.

SHARKSSL_PEM_KEY_UNRECOGNIZED_FORMAT 

KEY_UNRECOGNIZED_FORMAT.

SHARKSSL_PEM_KEY_UNSUPPORTED_FORMAT 

KEY_UNSUPPORTED_FORMAT.

SHARKSSL_PEM_KEY_UNSUPPORTED_MODULUS_LENGTH 

KEY_UNSUPPORTED_MODULUS_LENGTH.

SHARKSSL_PEM_KEY_UNSUPPORTED_EXPONENT_LENGTH 

KEY_UNSUPPORTED_EXPONENT_LENGTH.

SHARKSSL_PEM_KEY_UNSUPPORTED_ENCRYPTION_TYPE 

KEY_UNSUPPORTED_ENCRYPTION_TYPE.

SHARKSSL_PEM_KEY_CERT_MISMATCH 

KEY_CERT_MISMATCH.

SHARKSSL_PEM_CERT_UNRECOGNIZED_FORMAT 

CERT_UNRECOGNIZED_FORMAT.

SHARKSSL_PEM_CERT_UNSUPPORTED_TYPE 

CERT_UNSUPPORTED_TYPE.

SHARKSSL_PEM_KEY_UNSUPPORTED_VERSION 

KEY_UNSUPPORTED_VERSION.

SHARKSSL_PEM_KEY_REQUIRED 

KEY_REQUIRED.

SHARKSSL_PEM_KEY_PRIVATE_KEY_REQUIRED 

A PRIVATE KEY IS REQUIRED.

SHARKSSL_PEM_INTERNAL_ERROR 

INTERNAL ERROR.

Function Documentation

◆ sharkssl_entropyEx()

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.

Parameters
entropyconst 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.
lenU16; buffer length in bytes, 48 through 65535 for initial seeding or 32 through 65535 for reseeding. No default.
Returns
int: 0 after successful seeding or reseeding; -1 for a NULL buffer or insufficient input length. Invalid input leaves the DRBG state unchanged.

◆ sharkssl_PEM()

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:

int addMyCert(SharkSsl *shark)
{
SharkSslCert *sharkCert;
// The two following functions illustrate how a certificate and
// key can be read from a file system and inserted into an
// allocated buffer.
char *cert=readMyCertFromFileSystem();
char *key=readMyKeyFromFileSystem();
if(sharkssl_PEM(cert,key,NULL,&sharkCert))
return -1;
free(cert);
free(key);
// You may redesign the code and keep a reference to the
// SharkSslCert object if you design a system using dynamic objects
// i.e. if you later plan on releasing the SharkSSL object and
// the SharkSslCert object. You cannot release the SharkSslCert
// object before releasing the SharkSSL object.
SharkSsl_addCertificate(shark,sharkCert);
return 0;
}
SHARKSSL_API sharkssl_PEM_RetVal sharkssl_PEM(const char *certPEM, const char *keyPEM, const char *passphrase, SharkSslCert *sharkSslCert)
Create a SharkSslCert from PEM data.
SHARKSSL_API U8 SharkSsl_addCertificate(SharkSsl *o, SharkSslCert cert)
Add a certificate to the SharkSsl object.
const U8 * SharkSslCert
The SharkSSL Certificate is in a binary format optimized for speed and size.
Definition: SharkSSL.h:326
A SharkSsl object is the coordinator for managing SharkSslCon objects (See SharkSsl_constructor for d...
Definition: SharkSSL.h:511
Parameters
certPEMconst char *; NUL-terminated PEM certificate/chain, or NULL for key-only conversion. Borrowed for the call.
keyPEMconst char *; NUL-terminated PEM key; may be NULL for the supported PSA public-certificate conversion.
passphraseconst char *; optional NUL-terminated password for an encrypted PEM key, or NULL. Borrowed.
sharkSslCertSharkSslCert *; required result pointer. On success the caller owns the allocated blob; free it with baFree after all borrowers release it.
Returns
sharkssl_PEM_RetVal: SHARKSSL_PEM_OK or SHARKSSL_PEM_OK_PUBLIC on success; a negative SHARKSSL_PEM_* error on failure. Treat both success codes explicitly.

◆ sharkssl_PEM_PBKDF2()

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.

Parameters
dkpointer to the buffer where the derived key will be stored
passphrasepointer to the passphrase (null-terminated string) used to derive the key
saltpointer to the salt string used in the key derivation process
saltLenlength of the salt in bytes
iterationsnumber of iterations to perform in the key derivation process
dkLendesired length of the derived key in bytes.
hashIDidentifier for the digest function to use; allowed values are: SHARKSSL_HASHID_SHA512, SHARKSSL_HASHID_SHA384, SHARKSSL_HASHID_SHA256
Returns
0 on success, or a non-zero error code on failure

◆ sharkssl_PEM_PBKDF2Ex()

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.

Parameters
dkU8 *; 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.
passphraseconst char *; required readable password buffer, borrowed for this call. Supply a non-NULL pointer even for a zero-length password.
saltconst char *; saltLen readable salt bytes, borrowed for this call. May be NULL when saltLen is 0. No terminator is needed.
saltLenU32; salt length in bytes, including zero. No default.
iterationsU32; iteration count, 1 through 4294967295. No default.
passphraseLenU16; password length in bytes, 0 through 65535, including embedded NUL bytes. No default.
dkLenU16; derived-key length in bytes, 1 through 65535. No default.
hashIDU8; 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.
Returns
int: 0 on success; -1 for invalid input, an unavailable hash, or a hash/provider operation failure. Early input rejection can leave dk unchanged; do not assume that every failure erases it.

◆ sharkssl_PEMEx()

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.

Parameters
certPEMconst char *; NUL-terminated PEM certificate or certificate chain, or NULL for key-only conversion. Borrowed for this call.
keyPEMconst 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.
passphraseconst 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.
sharkSslCertSharkSslCert *; 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.
passphraseLenU16; password length in bytes, 0 through 65535. Use 0 with a NULL passphrase. No default.
Returns
sharkssl_PEM_RetVal: SHARKSSL_PEM_OK (0) for a private-key result, SHARKSSL_PEM_OK_PUBLIC (1) for a public-only result, or a negative SHARKSSL_PEM_* error. Check both success codes explicitly.

◆ sharkssl_X25519_createKeyPair()

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.

Parameters
privateKeyreceives the 32-byte private key. The key must be treated as opaque and passed unchanged to sharkssl_X25519_sharedSecret.
publicKeyreceives the 32-byte RFC 7748 little-endian public u-coordinate.
Returns
zero on success and nonzero on error.
Note
The SharkSSL random number generator must be initialized and seeded before calling this function.
privateKey and publicKey must point to separate, non-overlapping 32-byte buffers.

◆ sharkssl_X25519_sharedSecret()

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.

Parameters
privateKeya 32-byte private key generated by sharkssl_X25519_createKeyPair. The key must be passed unchanged to this function.
peerPublicKeythe peer's 32-byte RFC 7748 public key.
sharedSecretreceives the 32-byte shared secret.
Returns
zero on success and nonzero on error. An all-zero shared secret is rejected.