slcrypto.h
crypto/include/slcrypto.h · 186 line(s) · c
/*
* crypto/include/slcrypto.h
* SLeeLa National-Grade Cryptography โ public C API.
*
* This header declares standards-faithful reference implementations of the
* cryptographic primitives that make up the modern "national grade" / U.S.
* government algorithm suites (NSA CNSA 1.0 / 2.0, built from open NIST FIPS
* and SP standards):
*
* Hashing SHA-256, SHA-384, SHA-512 FIPS 180-4
* SHA3-256, SHA3-512 (Keccak) FIPS 202
* Symmetric AES-128/192/256 FIPS 197
* AES-GCM (AEAD) NIST SP 800-38D
* MAC HMAC FIPS 198-1 / RFC 2104
* KDF HKDF (extract/expand) RFC 5869
* Post-quantum ML-KEM (Kyber) FIPS 203 (interface)
* ML-DSA (Dilithium) FIPS 204 (interface)
*
* SECURITY NOTE (read before use):
* These are CORRECT, SPECIFICATION-FAITHFUL REFERENCE implementations meant
* for study, interoperability testing, and use inside the SLeeLa toolchain.
* They are NOT hardened for production: they are not guaranteed constant-time
* and are not side-channel resistant. For data that must actually be
* protected, use an audited library (BoringSSL, OpenSSL, libsodium, liboqs).
* This boundary is intentional and is stated again at each primitive.
*
* All algorithms are public, published standards. Nothing here weakens,
* backdoors, or circumvents cryptography.
*/
#ifndef SLCRYPTO_H
#define SLCRYPTO_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ---- Return codes -------------------------------------------------------- */
typedef enum {
SLCRYPTO_OK = 0,
SLCRYPTO_ERR_PARAM = -1, /* bad argument */
SLCRYPTO_ERR_AUTH = -2, /* authentication / tag verification failed */
SLCRYPTO_ERR_UNIMPL = -3 /* interface declared, implementation pending */
} slcrypto_status;
/* ========================================================================= *
* SHA-2 (FIPS 180-4) *
* ========================================================================= */
#define SLC_SHA256_DIGEST_LEN 32
#define SLC_SHA384_DIGEST_LEN 48
#define SLC_SHA512_DIGEST_LEN 64
#define SLC_SHA256_BLOCK 64
#define SLC_SHA512_BLOCK 128
typedef struct { uint32_t h[8]; uint64_t len; uint8_t buf[SLC_SHA256_BLOCK]; size_t n; } slc_sha256_ctx;
typedef struct { uint64_t h[8]; uint64_t len_hi, len_lo; uint8_t buf[SLC_SHA512_BLOCK]; size_t n; } slc_sha512_ctx;
void slc_sha256_init(slc_sha256_ctx *c);
void slc_sha256_update(slc_sha256_ctx *c, const void *data, size_t len);
void slc_sha256_final(slc_sha256_ctx *c, uint8_t out[SLC_SHA256_DIGEST_LEN]);
void slc_sha256(const void *data, size_t len, uint8_t out[SLC_SHA256_DIGEST_LEN]);
/* SHA-384 and SHA-512 share the 64-bit core; init selects the variant. */
void slc_sha512_init(slc_sha512_ctx *c);
void slc_sha384_init(slc_sha512_ctx *c);
void slc_sha512_update(slc_sha512_ctx *c, const void *data, size_t len);
void slc_sha512_final(slc_sha512_ctx *c, uint8_t *out /* 64 or 48 bytes */);
void slc_sha512(const void *data, size_t len, uint8_t out[SLC_SHA512_DIGEST_LEN]);
void slc_sha384(const void *data, size_t len, uint8_t out[SLC_SHA384_DIGEST_LEN]);
/* ========================================================================= *
* SHA-3 / Keccak (FIPS 202) *
* ========================================================================= */
#define SLC_SHA3_256_DIGEST_LEN 32
#define SLC_SHA3_512_DIGEST_LEN 64
typedef struct {
uint64_t state[25];
size_t rate; /* bytes absorbed per permutation */
size_t absorbed; /* bytes currently in the rate buffer */
uint8_t buf[200];
} slc_sha3_ctx;
void slc_sha3_256_init(slc_sha3_ctx *c);
void slc_sha3_512_init(slc_sha3_ctx *c);
void slc_sha3_update(slc_sha3_ctx *c, const void *data, size_t len);
void slc_sha3_final(slc_sha3_ctx *c, uint8_t *out /* 32 or 64 bytes */);
void slc_sha3_256(const void *data, size_t len, uint8_t out[SLC_SHA3_256_DIGEST_LEN]);
void slc_sha3_512(const void *data, size_t len, uint8_t out[SLC_SHA3_512_DIGEST_LEN]);
/* ========================================================================= *
* AES (FIPS 197) + GCM AEAD (SP 800-38D) *
* ========================================================================= */
#define SLC_AES_BLOCK 16
typedef struct {
uint32_t rk[60]; /* round keys (enough for AES-256) */
int rounds; /* 10 / 12 / 14 */
} slc_aes_key;
/* key_bits must be 128, 192, or 256. */
slcrypto_status slc_aes_set_encrypt_key(slc_aes_key *k, const uint8_t *key, int key_bits);
slcrypto_status slc_aes_set_decrypt_key(slc_aes_key *k, const uint8_t *key, int key_bits);
void slc_aes_encrypt_block(const slc_aes_key *k, const uint8_t in[16], uint8_t out[16]);
void slc_aes_decrypt_block(const slc_aes_key *k, const uint8_t in[16], uint8_t out[16]);
/*
* AES-GCM authenticated encryption (SP 800-38D).
* key_bits : 128 | 192 | 256
* iv : nonce (96-bit / 12-byte recommended)
* aad : additional authenticated data (not encrypted)
* tag_len : 1..16 (16 recommended)
* Encryption writes ciphertext (same length as plaintext) and the tag.
* Decryption verifies the tag before returning plaintext; a bad tag yields
* SLCRYPTO_ERR_AUTH and no plaintext is released.
*/
slcrypto_status slc_aes_gcm_encrypt(
const uint8_t *key, int key_bits,
const uint8_t *iv, size_t iv_len,
const uint8_t *aad, size_t aad_len,
const uint8_t *pt, size_t pt_len,
uint8_t *ct_out,
uint8_t *tag_out, size_t tag_len);
slcrypto_status slc_aes_gcm_decrypt(
const uint8_t *key, int key_bits,
const uint8_t *iv, size_t iv_len,
const uint8_t *aad, size_t aad_len,
const uint8_t *ct, size_t ct_len,
const uint8_t *tag, size_t tag_len,
uint8_t *pt_out);
/* ========================================================================= *
* HMAC (FIPS 198-1 / RFC 2104) โ parameterized by hash *
* ========================================================================= */
void slc_hmac_sha256(const uint8_t *key, size_t key_len,
const uint8_t *msg, size_t msg_len,
uint8_t out[SLC_SHA256_DIGEST_LEN]);
void slc_hmac_sha512(const uint8_t *key, size_t key_len,
const uint8_t *msg, size_t msg_len,
uint8_t out[SLC_SHA512_DIGEST_LEN]);
/* ========================================================================= *
* HKDF (RFC 5869) over HMAC-SHA-256 *
* ========================================================================= */
void slc_hkdf_sha256(const uint8_t *salt, size_t salt_len,
const uint8_t *ikm, size_t ikm_len,
const uint8_t *info, size_t info_len,
uint8_t *okm, size_t okm_len);
/* ========================================================================= *
* Post-quantum (CNSA 2.0) โ interface declared, implementation pending *
* ---------------------------------------------------------------------------
* ML-KEM (FIPS 203, Kyber) and ML-DSA (FIPS 204, Dilithium) are the NIST
* post-quantum standards named by CNSA 2.0. Their reference implementations
* are large (lattice arithmetic, NTT, sampling) and are best vendored from
* liboqs/pq-crystals rather than hand-rolled. These entry points declare the
* stable surface; they currently return SLCRYPTO_ERR_UNIMPL. See
* crypto/PQ-INTEGRATION.md for the integration plan.
* ========================================================================= */
typedef enum { SLC_MLKEM_512, SLC_MLKEM_768, SLC_MLKEM_1024 } slc_mlkem_param;
typedef enum { SLC_MLDSA_44, SLC_MLDSA_65, SLC_MLDSA_87 } slc_mldsa_param;
slcrypto_status slc_mlkem_keygen(slc_mlkem_param p, uint8_t *pk, uint8_t *sk);
slcrypto_status slc_mlkem_encaps(slc_mlkem_param p, const uint8_t *pk, uint8_t *ct, uint8_t *shared);
slcrypto_status slc_mlkem_decaps(slc_mlkem_param p, const uint8_t *sk, const uint8_t *ct, uint8_t *shared);
slcrypto_status slc_mldsa_keygen(slc_mldsa_param p, uint8_t *pk, uint8_t *sk);
slcrypto_status slc_mldsa_sign(slc_mldsa_param p, const uint8_t *sk,
const uint8_t *msg, size_t msg_len,
uint8_t *sig, size_t *sig_len);
slcrypto_status slc_mldsa_verify(slc_mldsa_param p, const uint8_t *pk,
const uint8_t *msg, size_t msg_len,
const uint8_t *sig, size_t sig_len);
/* ---- Utility ------------------------------------------------------------- */
/* Constant-time comparison; returns 1 if equal, 0 otherwise. */
int slc_ct_equal(const void *a, const void *b, size_t len);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* SLCRYPTO_H */