Module crypto_algorithms

Expand description

Cryptographic algorithm identifiers for VSF hash, signature, and key types

Each type (h, g, k) uses a single lowercase ASCII letter (a-z) to identify the algorithm. This gives 26 slots per type, with most reserved for future use.

§Important: Algorithm vs Output Size

Each letter represents a distinct algorithm, NOT just a different output size:

SHA-256 (s) and SHA-512 (t) are different algorithms (32-bit vs 64-bit internal words, different round counts)
They are not “the same algorithm with different output lengths”

§Variable-Length Output

Some algorithms support variable output lengths while maintaining the same algorithm ID:

BLAKE3: Can output any length (default 32 bytes, but can produce 1 byte to 2^64 bytes)
BLAKE2b: Can output 1-64 bytes
SHA-3: Supports “XOF” (extendable output) variants

When storing a hash, the actual output length is encoded in the VSF h type’s length field. The algorithm ID just tells you which hash function was used.

Constants§

HASH_BLAKE3: BLAKE3 hash - RECOMMENDED DEFAULT
HASH_SHA256: SHA-256 hash
HASH_SHA512: SHA-512 hash
KEY_AES256_GCM: AES-256-GCM symmetric key
KEY_CHACHA20_POLY1305: ChaCha20-Poly1305 symmetric key
KEY_ED25519: Ed25519 public key - RECOMMENDED DEFAULT
KEY_FRODO: FrodoKEM public key
KEY_MCELIECE: Classic McEliece public key
KEY_ML_KEM: ML-KEM public key (FIPS 203 - formerly Kyber)
KEY_P_CURVE: P-curve ECDSA/ECDH public key (P-256, P-384)
KEY_SECP256K1: secp256k1 public key (Bitcoin curve)
KEY_SHARED_SECRET: Shared secret / derived key material
KEY_X25519: X25519 public key
MAC_BLAKE3: BLAKE3 keyed mode
MAC_CMAC: CMAC (AES-based)
MAC_HMAC_SHA256: HMAC-SHA256 - RECOMMENDED DEFAULT
MAC_HMAC_SHA512: HMAC-SHA512
MAC_POLY1305: Poly1305
SIG_ECDSA_P256: ECDSA P-256 signature
SIG_ED25519: Ed25519 signature - RECOMMENDED DEFAULT
SIG_RSA_2048: RSA-2048 signature
WRAP_AES256_GCM: AES-256-GCM encryption
WRAP_CHACHA20POLY1305: ChaCha20-Poly1305 AEAD encryption - RECOMMENDED DEFAULT

Functions§

hash_algorithm_name: Get hash algorithm name from ID
hash_length: Get expected hash length in bytes
is_valid_hash_algorithm: Validate hash algorithm ID is known
is_valid_key_algorithm: Validate key algorithm ID is known
is_valid_mac_algorithm: Validate MAC algorithm ID is known
is_valid_signature_algorithm: Validate signature algorithm ID is known
key_algorithm_name: Get key algorithm name from ID
key_length: Get expected public key length in bytes (None = variable length)
mac_algorithm_name: Get MAC algorithm name from ID
mac_length: Get expected MAC tag length in bytes (None = variable length)
signature_algorithm_name: Get signature algorithm name from ID
signature_length: Get expected signature length in bytes
wrap_algorithm_name: Get wrapping algorithm name from ID
wrap_key_length: Get expected key length for wrapping algorithm in bytes