config: Rename enc.conf to sec.conf

The per-name config file holds more than encryption settings (KEX,
cipher, KDF, peer authentication), so renamed it from enc.conf to
sec.conf and the code internals to match.

Signed-off-by: Dimitri Staessens <dimitri@ouroboros.rocks>
Signed-off-by: Sander Vrijders <sander@ouroboros.rocks>

1 files changed, 177 insertions, 0 deletions

diff --git a/sec.conf.in b/sec.conf.in
new file mode 100644
index 00000000..4796b72d
--- /dev/null
+++ b/sec.conf.in
@@ -0,0 +1,177 @@
+### Example Ouroboros security configuration file
+#
+# This file specifies the security parameters for a service: the key
+# exchange (KEX) algorithm, cipher, key derivation, and peer authentication.
+#
+# File Locations:
+# ---------------
+#
+# This file should be placed at one of:
+#   @OUROBOROS_CONFIG_DIR@/security/server/<name>/sec.conf  (server-side config)
+#   @OUROBOROS_CONFIG_DIR@/security/client/<name>/sec.conf  (client-side config)
+#
+# Where <name> is the service name registered with 'irm name create'.
+#
+# You can override the default paths using:
+#   irm name create <name> ssecpath <server-sec-path> csecpath <client-sec-path>
+#
+# Configuration Options:
+# ----------------------
+#
+# kex=<algorithm>      Key exchange/encapsulation algorithm
+# cipher=<cipher>      Symmetric cipher algorithm
+# kdf=<hash>           Key derivation function hash algorithm
+# kem_mode=<mode>      KEM encapsulation mode (server or client)
+# auth=<policy>        Peer authentication policy (required or optional)
+# encryption=none      Explicitly disable encryption
+#
+# Supported KEX algorithms (kex=):
+# --------------------------------
+#
+# ECDH Curves:
+#   prime256v1     NIST P-256 (default)
+#   secp384r1      NIST P-384
+#   secp521r1      NIST P-521
+#   X25519         Curve25519
+#   X448           Curve448
+#
+# Finite Field Diffie-Hellman (RFC 7919):
+#   ffdhe2048      2048-bit MODP Group
+#   ffdhe3072      3072-bit MODP Group
+#   ffdhe4096      4096-bit MODP Group
+#
+# ML-KEM (FIPS 203):
+#   ML-KEM-512     CRYSTALS-Kyber-512
+#   ML-KEM-768     CRYSTALS-Kyber-768
+#   ML-KEM-1024    CRYSTALS-Kyber-1024
+#
+# Hybrid KEMs:
+#   X25519MLKEM768  X25519 + ML-KEM-768
+#   X448MLKEM1024   X448 + ML-KEM-1024
+#
+# Supported cipher algorithms (cipher=):
+# --------------------------------------
+#
+# Authenticated encryption:
+#   aes-128-gcm         AES-128 in GCM mode
+#   aes-192-gcm         AES-192 in GCM mode
+#   aes-256-gcm         AES-256 in GCM mode (default)
+#   chacha20-poly1305   ChaCha20-Poly1305
+#
+# Key Derivation Functions (kdf=):
+# ---------------------------------
+#
+# Hash algorithms for key derivation in KEX operations:
+#
+#   sha256              SHA-256 (default)
+#   sha384              SHA-384
+#   sha512              SHA-512
+#   sha3-256            SHA3-256
+#   sha3-384            SHA3-384
+#   sha3-512            SHA3-512
+#   blake2b512          BLAKE2b-512
+#   blake2s256          BLAKE2s-256
+#
+# Peer Authentication (auth=):
+# ----------------------------
+#
+#   optional   Accept unauthenticated peers
+#   required   Reject peers that do not present a valid certificate
+#
+# This setting applies to the *peer*: in a client config it requires
+# the server to authenticate; in a server config it requires the
+# client. The defaults mirror the web: a client config defaults to
+# required (the server must authenticate), a server config defaults
+# to optional (client authentication is opt-in). Set auth=required on
+# the server too for mutual authentication. Combine encryption=none
+# with auth=required for authenticated but unencrypted flows.
+#
+# Issuer Pinning (cacert=):
+# -------------------------
+#
+#   cacert=<path>   Path to a CA certificate that must be part of the
+#                   peer certificate's verified chain
+#
+# The peer certificate is always validated against the trusted CA
+# store; cacert= further restricts which CA must have issued it: a
+# certificate, if presented, must chain through the pinned CA. Whether
+# a certificate is mandatory is controlled by auth= alone: under
+# auth=optional a peer may still connect without one. The pinned CA
+# must load when the config is read, otherwise flow allocation fails.
+#
+# KEM Mode (kem_mode=):
+# ---------------------
+#
+# For KEM algorithms (ML-KEM-* and hybrid KEMs), specify which side
+# performs the encapsulation operation:
+#
+#   server    Server encapsulates to client's ephemeral public key (default, matches TLS 1.3)
+#             - Client generates ephemeral keypair, sends public key in request
+#             - Server encapsulates and sends ciphertext in response
+#             - Client decapsulates with ephemeral private key
+#             - Standard approach, no pre-shared keys needed
+#
+#   client    Client encapsulates to server's static public key (alternative)
+#             - Requires cached server public key at:
+#               @OUROBOROS_CONFIG_DIR@/security/client/<service>/kex.srv.pub.[pem|raw]
+#             - Client encapsulates and sends ciphertext in initial request
+#             - Server decapsulates with its static private key from:
+#               @OUROBOROS_CONFIG_DIR@/security/server/kex.key.pem
+#             - More efficient (0 round-trip) but requires key distribution
+#               and forfeits forward secrecy
+#
+# Note: Both sides must use the same kem_mode setting.
+# This option is ignored for ECDH/DH key exchange algorithms.
+#
+# Key Management for Client Mode:
+# --------------------------------
+#
+# For client encapsulation mode, you must:
+# 1. Generate server KEM keypair:
+#      openssl genpkey -algorithm ML-KEM-768 \
+#        -out @OUROBOROS_CONFIG_DIR@/security/server/kex.key.pem
+# 2. Extract and distribute server public key:
+#      openssl pkey -in kex.key.pem -pubout -out kex.srv.pub.pem
+# 3. Cache on clients at:
+#      @OUROBOROS_CONFIG_DIR@/security/client/<service-name>/kex.srv.pub.pem
+#
+# File formats:
+# - Pure ML-KEM: PEM format (.pem extension)
+# - Hybrid KEMs: Raw bytes (.raw extension)
+#
+# Examples:
+# ---------
+#
+# Default configuration (NIST P-256 ECDH + AES-256-GCM):
+kex=prime256v1
+cipher=aes-256-gcm
+kdf=sha256
+#
+# Post-quantum KEX with server encapsulation (default, like TLS 1.3):
+# kex=ML-KEM-768
+# cipher=chacha20-poly1305
+# kdf=sha256
+# kem_mode=server
+#
+# Post-quantum KEX with client encapsulation (requires key distribution):
+# kex=ML-KEM-768
+# cipher=chacha20-poly1305
+# kdf=sha256
+# kem_mode=client
+#
+# Hybrid KEX (quantum-resistant):
+# kex=X25519MLKEM768
+# cipher=aes-256-gcm
+# kdf=sha256
+#
+# High security configuration:
+# kex=secp521r1
+# cipher=aes-256-gcm
+# kdf=sha512
+#
+# Disable encryption:
+# encryption=none
+#
+# Authentication required, no encryption:
+# encryption=none
+# auth=required