Leancrypto API Documentation

Doxygen Documentation

The Doxygen Documentation is automatically generated during the compilation of the source code if the doxygen binary is found on the host system.

API Documentation in Header Files

The leancrypto API is documented in the exported header files. The only header file that needs to be included in the target code is #include <leancrypto.h>. This header file includes all algorithm-specific header files for the compiled and supported algorithms.

To fully understand the API, please consider the following base concept of leancrypto: Different algorithm implementations are accessible via common APIs. For example, different random number generator algorithms are accessible via the RNG API. To ensure the common APIs act on the proper algorithm, the caller must use algorithm-specific initialization functions. The initialization logic returns a “cipher handle” that can be used with the common API for all subequent operations.

The following list enumerates all algorithm-specific header files which contains the respective API documentation:

• AEAD Algorithms:

  • Main API: lc_aead.h

  • Ascon AEAD: lc_ascon_lightweight.h

  • Ascon-Keccak AEAD: lc_ascon_keccak.h

  • cSHAKE AEAD: lc_cshake_crypt.h

  • Hash-based AEAD: lc_hash_crypt.h

  • KMAC-based AEAD lc_kmac_crypt.h

  • Symmetric algorithm + HMAC AEAD: lc_symhmac.h

  • Symmetric algorithm + KMAC AEAD: lc_symkmac.h

• Deterministic RNGs:

  • Main API: lc_rng.h

  • ChaCha20-based DRNG: lc_chacha20_drng.h

  • KMAC-based DRNG: lc_kmac256_drng.h

  • cSHAKE-based DRNG: lc_cshake256_drng.h

  • XDRBG-based DRNG: lc_xdrbg.h

  • SP800-90A Hash-based DRBG: lc_hash_drbg.h

  • SP800-90A HMAC-based DRBG: lc_hmac_drbg_sha512.h

• Message Digests:

  • Main API: lc_hash.h

  • SHA2-256: lc_sha256.h

  • SHA2-512: lc_sha512.h

  • cSHAKE support: lc_cshake.h

  • SHA-3, SHAKE, cSHAKE: lc_sha3.h

• Key-Derivation Function:

  • RFC5869 HKDF: lc_hkdf.h

  • SP800-108 counter KDF: lc_kdf_ctr.h

  • SP800-108 feedback KDF: lc_kdf_fb.h

  • SP800-108 double-pipeline KDF: lc_kdf_dpi.h

  • SP880-132 PBKDF2: lc_pbkdf2.h

• Key Encapsulation Mechanisms:

  • FIPS 203 Kyber: lc_kyber.h

• One-time Pads:

  • HOTP: lc_hotp.h

  • TOTP: lc_totp.h

• Signature Algorithms:

  • FIPS 204 Dilithium: lc_dilithium.h

• Symmetric Algorithms:

  • Main API: lc_sym.h

  • ChaCha20: lc_chacha20.h

  • AES: lc_aes.h

• Keyed Message Digests:

  • FIPS 198 HMAC: lc_hmac.h

  • SP800-185 KMAC: lc_kmac.h

• Helper Functions:

  • Constant-time memcmp: lc_memcmp_secure.h

  • Secure memset: lc_memset_secure.h

  • Status API: lc_status.h

Example Code

Almost all test cases found in the various tests directories use the aforementioned public APIs and thus serve as example code for the given algorithms.