ouroboros/doc, branch master

lib: Add post-quantum cryptography support

2026-01-19T07:29:29+00:00

This adds initial support for runtime-configurable encryption and post-quantum Key Encapsulation Mechanisms (KEMs) and authentication (ML-DSA). Supported key exchange algorithms: ECDH: prime256v1, secp384r1, secp521r1, X25519, X448 Finite Field DH: ffdhe2048, ffdhe3072, ffdhe4096 ML-KEM (FIPS 203): ML-KEM-512, ML-KEM-768, ML-KEM-1024 Hybrid KEMs: X25519MLKEM768, X448MLKEM1024 Supported ciphers: AEAD: aes-128-gcm, aes-192-gcm, aes-256-gcm, chacha20-poly1305 CTR: aes-128-ctr, aes-192-ctr, aes-256-ctr Supported HKDFs: sha256, sha384, sha512, sha3-256, sha3-384, sha3-512, blake2b512, blake2s256 Supported Digests for DSA: sha256, sha384, sha512, sha3-256, sha3-384, sha3-512, blake2b512, blake2s256 PQC support requires OpenSSL 3.4.0+ and is detected automatically via CMake. A DISABLE_PQC option allows building without PQC even when available. KEMs differ from traditional DH in that they require asymmetric roles: one party encapsulates to the other's public key. This creates a coordination problem during simultaneous reconnection attempts. The kem_mode configuration parameter resolves this by pre-assigning roles: kem_mode=server # Server encapsulates (1-RTT, full forward secrecy) kem_mode=client # Client encapsulates (0-RTT, cached server key) The enc.conf file format supports: kex= # Key exchange algorithm cipher= # Symmetric cipher kdf= # Key derivation function digest= # Digest for DSA kem_mode= # Server (default) or client none # Disable encryption The OAP protocol is extended to negotiate algorithms and exchange KEX data. All KEX messages are signed using existing authentication infrastructure for integrity and replay protection. Tests are split into base and _pqc variants to handle conditional PQC compilation (kex_test.c/kex_test_pqc.c, oap_test.c/oap_test_pqc.c). Bumped minimum required OpenSSL version for encryption to 3.0 (required for HKDF API). 1.1.1 is long time EOL. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

build: Refactor CMake modules

2026-01-07T09:00:06+00:00

This moves the CMake build logic out of the source tree and splits it up into a more modular form. The tests now have a CMakeLists.txt file in their respective source directory. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

lib: Move encryption control from QoS to name

2025-09-10T06:21:58+00:00

This removes the flow encryption option (cypher_s) from the qosspec. The configuration file is configured in the security options (default /etc/ouroboros/security/). For this poc, encryption can be disabled client or server side by putting an enc.cfg file. If that file is present in the client folder, the client will require encryption. If that file is present on the server side, the server will require encryption and reject non-encrypted flows. Encryption is now configured outside of any application control. Example: /etc/ouroboros/security/client/oping/enc.cfg exists: irmd(II): Encryption enabled for oping. irmd(DB): File /etc/ouroboros/security/client/oping/crt.pem does not exist. irmd(II): No security info for oping. irmd(DB): Generated ephemeral keys for 87474. irmd/oap(PP): OAP_HDR [caf203681d997941 @ 2025-09-02 17:08:05 (UTC) ] --> irmd/oap(PP): Certificate: irmd/oap(PP): Ephemeral Public Key: [91 bytes] irmd/oap(PP): Data: irmd/oap(PP): Signature: Example: /etc/ouroboros/security/client/oping/enc.cfg does not exist: irmd(II): Allocating flow for 87506 to oping. irmd(DB): File /etc/ouroboros/security/client/oping/enc.cfg does not exist. irmd(DB): File /etc/ouroboros/security/client/oping/crt.pem does not exist. irmd(II): No security info for oping. irmd/oap(PP): OAP_HDR [e84bb9d7c3d9c002 @ 2025-09-02 17:08:30 (UTC) ] --> irmd/oap(PP): Certificate: irmd/oap(PP): Ephemeral Public Key: irmd/oap(PP): Data: irmd/oap(PP): Signature: Example: /etc/ouroboros/security/server/oping/enc.cfg exists: irmd(II): Flow request arrived for oping. irmd(DB): IPCP 88112 accepting flow 7 for oping. irmd(II): Encryption enabled for oping. irmd(DB): File /etc/ouroboros/security/server/oping/crt.pem does not exist. irmd(II): No security info for oping. irmd/oap(PP): OAP_HDR [3c717b3f31dff8df @ 2025-09-02 17:13:06 (UTC) ] <-- irmd/oap(PP): Certificate: irmd/oap(PP): Ephemeral Public Key: irmd/oap(PP): Data: irmd/oap(PP): Signature: irmd(WW): Encryption required but no key provided. The server side will pass the ECRYPT to the client: $ oping -l Ouroboros ping server started. Failed to accept flow: -1008 $ oping -n oping -c 1 Failed to allocate flow: -1008. Encryption on flows can now be changed at runtime without needing to touch/reconfigure/restart the process. Note: The ECRYPT result is passed on via the flow allocator responses through the IPCP (discovered/fixed some endianness issues), but the reason for rejecting the flow can be considered N+1 information... We may move that information up into the OAP header at some point. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

ipcpd: Add ipcpd over UDP/IPv6

2025-09-10T06:19:52+00:00

This adds an IPCP that runs over UDP/IPv6. It's structured like the eth-dix and eth-llc in that it builds two separate binaries: ipcpd-udp4 and ipcpd-udp6. The IRM CLI is backwards compatible in that type 'udp' will resolve to type 'udp4'. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

irmd: Add flow authentication

2025-08-18T18:57:23+00:00

This adds initial implementation of peer authentication as part of flow allocation. If credentials are not provided, this will be accepted and logged as info that the flow is not authenticated. Certificates and keys are passed as .pem files. The key file should not be encrypted, else the IRMd will open a prompt for the password. The default location for these .pem files is in /etc/ouroboros/security. It is strongly recommended to make this directory only accessible to root. ├── security │ ├── cacert │ │ └── ca.root.o7s.crt.pem │ ├── client │ │ ├── │ │ | ├── crt.pem │ │ | └── key.pem │ │ └── | | ├──... | | │ ├── server │ │ ├── │ │ | ├── crt.pem │ │ | └── key.pem │ │ └── | | ├── ... | | │ └── untrusted │ └── sign.root.o7s.crt.pem Trusted root CA certificates go in the /cacert directory, untrusted certificates for signature verification go in the /untrusted directory. The IRMd will load these certificates at boot. The IRMd will look for certificates in the /client and /server directories. For each name a subdirectory can be added and the credentials in that directory are used to sign the OAP header for flows at flow_alloc() on the client side and flow_accept() on the server side. These defaults can be changed at build time using the following variables (in alphabetical order): OUROBOROS_CA_CRT_DIR /etc/ouroboros/security/cacert OUROBOROS_CLI_CRT_DIR /etc/ouroboros/security/client OUROBOROS_SECURITY_DIR /etc/ouroboros/security OUROBOROS_SRV_CRT_DIR /etc/ouroboros/security/server OUROBOROS_UNTRUSTED_DIR /etc/ouroboros/security/untrusted The directories for the names can also be configured at IRMd boot using the configuraton file and at runtime when a name is created using the "irm name create" CLI tool. The user needs to have permissions to access the keyfile and certificate when specifying the paths with the "irm name create" CLI tool. Signed-off-by: Dimitri Staessens

build: Update licenses to 2024

2024-01-13T09:20:14+00:00

Slow but steady. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

doc: Fix typo

2023-12-17T12:24:49+00:00

Fixes a typo in the fccntl manpage. Signed-off-by: Thijs Paelman Signed-off-by: Sander Vrijders

irmd: Add configuration file support

2023-03-08T14:59:37+00:00

This adds initial support for configuration files using the C99 TOML parser (to be installed separately from https://github.com/cktan/tomlc99). The default location for the IRMd configuration file is /etc/ouroboros/irmd.conf. This is configurable at build time. An example file will be installed in the configuration directory with the name irmd.conf.example. Config file support can be disabled using the DISABLE_CONFIGFILE build option. There were some refactors and changes to the configuration messages and protobuf files. This works towards consolidation of protobuf C as an option for more generic handling of serialization/deserialization of various messages. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

lib: Make flow liveness timeout configurable

2022-03-03T11:00:54+00:00

The qosspec_t now has a timeout value that sets the timeout value of the flow. Flows with a peer that has timed out will now return -EFLOWPEER on flow_read() or flow_write(). Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders

lib: Don't use pointer to set FRCT flags

2021-12-29T08:12:39+00:00

The fccntl call FRCTSFLAGS was using a pointer to a flags so set flags, which should just be a regular uint16_t. For instance, the FRCTLINGER flags can now be turned off using fccntl(fd, FRCTSFLAGS, FRCTFRESCNTL | FRCTFRTX) leaving only resource control (flow control, FRCTFRESCNTL) and retransmission enabled. Note that retransmission (FRCTFRTX) can't be enabled or disabled on a live flow, it will be set on flow allocation. Updates the man page for fccntl to add these FRCT options. Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders