Ouroboros Flow Allocation Protocol

 This page is under construction  

Header

OAP Header Structure
====================

/*
 *  0                   1                   2                   3
 *  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+
 * |                                                               |    |
 * +                                                               +    |
 * |                                                               |    |
 * +                      id (128 bits)                            +    |
 * |                  Unique flow allocation ID                    |    |
 * +                                                               +    |
 * |                                                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    |
 * |                                                               |    |
 * +                     timestamp (64 bits)                       +    |
 * |                UTC nanoseconds since epoch                    |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    |
 * |         crt_len (16 bits)     |                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +    |
 * |                                                               |    |
 * +                  certificate (variable)                       +    |
 * |               X.509 certificate, DER encoded                  |    |
 * +                                                               +    |
 * |                                                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    |
 * |         eph_len (16 bits)     |                               |    | Signed
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +    | Region
 * |                                                               |    |
 * +                 ephemeral_key (variable)                      +    |
 * |                  public key, DER encoded                      |    |
 * +                                                               +    |
 * |                                                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    |
 * |       cipher_len (16 bits)    |                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +    |
 * |                                                               |    |
 * +                    cipher (variable)                          +    |
 * |               symmetric cipher name (UTF-8)                   |    |
 * +                                                               +    |
 * |                                                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    |
 * |        data_len (16 bits)     |                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +    |
 * |                                                               |    |
 * +                    data (variable)                            +    |
 * |              Piggybacked application data                     |    |
 * +                                                               +    |
 * |                                                               |    |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+
 * |        sig_len (16 bits)      |                               |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +
 * |                                                               |
 * +                     signature (variable)                      +
 * |                  DSA signature over signed region             |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 */

Field Summary:
+---------------+----------+----------------------------------------+
| Field         | Size     | Description                            |
+---------------+----------+----------------------------------------+
| id            | 16 bytes | Random 128-bit flow allocation ID      |
| timestamp     |  8 bytes | UTC time in nanoseconds (replay prot.) |
| crt_len       |  2 bytes | Certificate length (0 = no auth)       |
| certificate   | variable | X.509 cert signed by CA (DER encoded)  |
| eph_len       |  2 bytes | Ephemeral key length (0 = no encrypt)  |
| ephemeral_key | variable | DHE public key                         |
| cipher_len    |  2 bytes | Cipher name length (0 = no cipher)     |
| cipher        | variable | Name of the cipher to use              |
| data_len      |  2 bytes | Application data length                |
| data          | variable | Piggybacked app data (future use)      |
| sig_len       |  2 bytes | Signature length (0 = unsigned)        |
| signature     | variable | Signature                              |
+---------------+----------+----------------------------------------+

Minimum header size: 16 + 8 + 2 + 2 + 2 + 2 + 2 = 34 bytes (no optional fields)

Operation

When an application calls flow_alloc() to connect to a service or flow_accept() to receive incoming connections, the Ouroboros IRMd (IPC Resource Manager daemon) transparently handles all security operations on behalf of the application. The application simply provides a destination name (e.g., "sec.oping.tut.o7s") and receives back a flow descriptor for reading and writing data—it remains completely unaware of any underlying cryptography. During flow allocation, the IRMd on the client side constructs an OAP (Ouroboros Allocation Protocol) header containing a unique flow ID, timestamp, and optionally the client's X.509 certificate, an ephemeral DHE public key, and a digital signature. This OAP header travels inside the FLOW_REQ message to the server's IRMd, which can verify the client's certificate against its configured CA trust store and validate the signature. The server's IRMd then responds with its own OAP header in the FLOW_REPLY, containing its certificate, ephemeral public key, and signature. Both sides independently derive the same symmetric encryption key using DHE key agreement. Once the flow is established, the library layer (between the application and IRMd) automatically encrypts outgoing data and decrypts incoming data using this shared key—the application's flow_read() and flow_write() calls work identically whether encryption is enabled or not. This architecture applies uniformly to all flows regardless of their QoS characteristics: whether the underlying flow provides reliable ordered delivery (connection-oriented semantics) or best-effort delivery (connectionless semantics), the security handshake occurs during flow allocation, and the resulting symmetric key protects all subsequent data exchange. The security policy is entirely configuration-driven through certificate and key files in security, allowing system administrators to enforce authentication and encryption requirements without any application code changes.

Client (IRMd)                              Server (IRMd)
     |                                           |
     | 1. Load client cert/key                   |
     | 2. Generate ephemeral keypair             |
     | 3. Build OAP_HDR (id, ts, crt, eph)       |
     | 4. Sign header with client key            |
     |                                           |
     |-------- FLOW_REQ (OAP_HDR) -------------> |
     |                                           |
     |                                           | 5. Load server cert/key
     |                                           | 6. Verify client cert against CA
     |                                           | 7. Verify client signature
     |                                           | 8. Generate ephemeral keypair
     |                                           | 9. Derive symmetric key (ECDHE)
     |                                           | 10. Build response OAP_HDR
     |                                           | 11. Sign with server key
     |                                           |
     |<------- FLOW_REPLY (OAP_HDR) ------------ |
     |                                           |
     | 12. Verify server cert against CA         |
     | 13. Verify server signature               |
     | 14. Derive symmetric key (ECDHE)          |
     |                                           |
     |===========================================|
     |         Encrypted data channel            |
     |===========================================|