macula_crypto_profile (macula v11.4.0)

View Source

The post-quantum crypto profile a node runs.

A realm runs one profile, and a station instance serves one profile. The profile is set in the macula application environment under crypto_profile. There is no default: the application refuses to start without exactly one known profile.

  • pq_pure: the CNSA 2.0 algorithms. ML-KEM-1024 key exchange, ML-DSA-87 signatures, AES-256, no classical half.
  • pq_hybrid: SecP384r1MLKEM1024 hybrid key exchange, ML-DSA-87 alone in TLS, and every other signature hybrid: ML-DSA-87 plus RSA-PSS-4096 with SHA-384, valid only if both halves verify.

See plans/PLAN_POST_QUANTUM_SECURITY.md, decisions D1 to D5 and D24.

Summary

Types

definition/0
profile/0
refusal/0
rsa_pss_params/0
signature_algorithm/0

Functions

configured()

The profile set in the application environment, validated.

definition(Other)

The algorithms of a profile. A signature is a list of algorithms: ML-DSA-87 first, then the classical half of a hybrid signature when the profile has one.

profiles()

The profiles a node can run.

validate(Profiles)

Check a configured value: it must be exactly one known profile. A list is refused, because one node runs one profile.

Types

definition/0

-type definition() ::
          #{profile := profile(),
            key_exchange_group := mlkem1024 | secp384r1_mlkem1024,
            tls_signature_scheme := mldsa87,
            tls_cipher_suite := tls_aes_256_gcm_sha384,
            identity_signature := [signature_algorithm(), ...],
            connect_proof_signature := [signature_algorithm(), ...],
            status_signature := [signature_algorithm(), ...],
            binding_digest := sha384,
            content_id_digest := sha384,
            node_id_digest := sha256}.

profile/0

-type profile() :: pq_pure | pq_hybrid.

refusal/0

-type refusal() ::
          crypto_profile_missing |
          {crypto_profile_unknown, term()} |
          {crypto_profile_not_single, list()}.

rsa_pss_params/0

-type rsa_pss_params() ::
          #{modulus_bits := 4096,
            public_exponent := 65537,
            digest := sha384,
            mgf1_digest := sha384,
            salt_bytes := 48}.

signature_algorithm/0

-type signature_algorithm() :: mldsa87 | {rsa_pss, rsa_pss_params()}.

Functions

configured()

-spec configured() -> {ok, profile()} | {error, refusal()}.

The profile set in the application environment, validated.

definition(Other)

-spec definition(term()) -> {ok, definition()} | {error, {crypto_profile_unknown, term()}}.

The algorithms of a profile. A signature is a list of algorithms: ML-DSA-87 first, then the classical half of a hybrid signature when the profile has one.

profiles()

-spec profiles() -> [profile(), ...].

The profiles a node can run.

validate(Profiles)

-spec validate(term()) -> {ok, profile()} | {error, refusal()}.

Check a configured value: it must be exactly one known profile. A list is refused, because one node runs one profile.