Ouroboros Tutorial 06

Ouroboros Tutorial 06 - Authenticated Flows

This tutorial demonstrates setting up and using authenticated flows in Ouroboros with certificate-based authentication.

Tutorial Directory: This tutorial will execute in /tmp/o7s-tut06/. All configuration files, generated certificates, logs, and packet captures will be stored in this directory.

We create a complete PKI (Public Key Infrastructure):

• Root CA (ca.tut.o7s): Self-signed trust anchor
• Intermediate CA (sign.tut.o7s): Signed by root with pathlen:0 constraint
• Server Certificate (sec.oping.tut.o7s): Signed by intermediate CA

All cryptographic operations use ECDSA P-384 with SHA-384 hashing.

Setting Up the Tutorial

To properly understand and debug the authenticated flows, this tutorial uses a debug build of Ouroboros with OAP protocol debugging enabled.

cd /path/to/ouroboros
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DDEBUG_PROTO_OAP=ON ..
make -j$(nproc)
sudo make install

When built with these options, the IRMd will output detailed OAP protocol information.

Configuration Files

The following three files should be created in the tutorial directory (/tmp/o7s-tut06/) before starting the tutorial:

tut06.conf - IRMd configuration

# Ouroboros Tutorial 06 - Authenticated Flows Configuration
# Uses system-installed certificates at /etc/ouroboros/security/

[name."sec.oping.tut.o7s"]
prog=["/usr/bin/oping"]
args=["--listen"]

[eth-dix.eth-dix-lo]
bootstrap="eth-dix-network"
dev="lo"
reg=["sec.oping.tut.o7s"]

PCAP Trace Analysis

Protocol Overview

This section summarizes the four protocols that work together in the captured packet flow.

Ethernet DIX Frame with EID Header

Ouroboros extends the DIX frame with a flow identifier (EID - Endpoint Identifier) and length field.

Field	Octets	Size	Description
Destination MAC	0-5	6 bytes	Hardware address of destination
Source MAC	6-11	6 bytes	Hardware address of source
EtherType	12-13	2 bytes	Protocol identifier (0xA000 for Ouroboros)
EID	14-15	2 bytes	Destination Endpoint Identifier
Length	16-17	2 bytes	Payload length (needed for runt frame padding)
Payload	18+	Variable	Frame data (up to MTU size)

Ethernet Flow Allocator - Management Protocol

The Ethernet DIX management protocol handles flow allocation, setup, and teardown. All management frames use destination EID 0x0000.

Management Frame Types:

Code	Type	Direction	Service Hash	Purpose
0x00	FLOW_REQ	Client → Server	✓ Included	Request new flow allocation
0x01	FLOW_REPLY	Server → Client	– Not included	Respond to flow request (success/failure)
0x02	NAME_QUERY_REQ	Client → Server	✓ Included	Query if a remote name is reachable
0x03	NAME_QUERY_REPLY	Server → Client	✓ Included	Response to name query

Note: The 32-byte service hash (SHA3-256) is appended after the management protocol header for NAME_QUERY_* and FLOW_REQ messages to identify which service is being queried or allocated. FLOW_REPLY does not include the service hash; the endpoints are already identified by the allocated EIDs (SEID/DEID).

Ouroboros Flow Allocation Protocol (OAP)

The Ouroboros Application Protocol (OAP) is the flow allocation and authentication protocol. It carries flow negotiation requests, responses, and authentication credentials. OAP frames are encapsulated as data payload over the management protocol.

Frame Layout by Field:

Field	Offset	Size	Description
ID	0-15	16 bytes	Unique flow allocation identifier
Timestamp	16-23	8 bytes	Creation timestamp (UTC, seconds and microseconds)
Crt Length	24-25	2 bytes	Certificate length (bytes)
Certificate	26+	Variable	X.509 certificate (DER encoded)
Eph Length	Variable	2 bytes	Ephemeral public key length (bytes)
Ephemeral Key	Variable	Variable	ECDHE public key (DER/raw encoded)
Data Length	Variable	2 bytes	Application data length (bytes)
Data	Variable	Variable	Piggybacked application-layer data
Sig Length	Variable	2 bytes	Signature length (bytes)
Signature	Variable	Variable	Digital signature (ECDSA, DER encoded)

Oping Application Protocol

The Ouroboros Ping (oping) application is a simple echo/reply protocol used to measure round-trip time and validate connectivity between applications. It implements a request/reply pattern similar to ICMP ping.

Frame Layout by Field:

Field	Offset	Size	Description
Type	0-3	4 bytes	Message type (ECHO_REQUEST=0 or ECHO_REPLY=1)
ID	4-7	4 bytes	Sequence number / message identifier
Timestamp (seconds)	8-15	8 bytes	Seconds when message was sent (CLOCK_REALTIME)
Timestamp (nanoseconds)	16-23	8 bytes	Nanoseconds component of timestamp
Payload	24+	Variable	Application data (configurable size, default 64 bytes)

Packet Analysis

Packet 1: NAME_QUERY_REQ (Test 1 - Setup)

Summary: Client sends a NAME_QUERY_REQ message to discover if the service sec.oping.tut.o7s is available. This is a broadcast discovery query sent early in the flow allocation process.

Ethernet DIX Frame with EID Header

Offset	Hex	Field	Size	Value	Notes
0x00-0x01	0000	EID	2	0x0000	Destination Endpoint ID (management channel)
0x02-0x03	0047	Length	2	71 bytes	Total payload length

Ethernet Flow Allocator - Management Protocol

Offset	Hex	Field	Size	Value	Notes
0x04-0x05	0000	SEID	2	0x0000	Source Endpoint ID (UNUSED)
0x06-0x07	0000	DEID	2	0x0000	Destination Endpoint ID (UNUSED)
0x08-0x23	0000 ... 0000	QoS (Various)	28	0	UNUSED
0x24-0x27	0000 0000	Response	4	0	Response code (UNUSED)
0x28	00	QoS (In-Order)	1	0	UNUSED
0x29	03	Code	1	0x03	Message Type: NAME_QUERY_REQ
0x2a	00	QoS (Availability)	1	0x00	UNUSED
0x2b-0x4a	ec f815 ad98 3df6 bf81...9282 8a	Service Hash	32	SHA3-256	Hash of sec.oping.tut.o7s

Packet 2: NAME_QUERY_REPLY (Test 1 - Setup)

Summary: Server responds to the NAME_QUERY_REQ by sending a NAME_QUERY_REPLY for the service hash.

Ethernet DIX Frame with EID Header

Offset	Hex	Field	Size	Value	Notes
0x00-0x01	0000	EID	2	0x0000	Destination Endpoint ID (management channel)
0x02-0x03	0047	Length	2	71 bytes	Total payload length

Ethernet Flow Allocator - Management Protocol

Offset	Hex	Field	Size	Value	Notes
0x04-0x05	0000	SEID	2	0x0000	Source Endpoint ID (UNUSED)
0x06-0x07	0000	DEID	2	0x0000	Destination Endpoint ID (UNUSED)
0x08-0x23	0000 ... 0000	QoS (Various)	28	0	UNUSED
0x24-0x27	0000 0000	Response	4	0	Response code (UNUSED)
0x28	00	QoS (In-Order)	1	0	UNUSED
0x29	03	Code	1	0x03	Message Type: NAME_QUERY_REPLY
0x2a	00	QoS (Availability)	1	0x00	UNUSED
0x2b-0x4a	ec f815 ad98 3df6 bf81...9282 8a	Service Hash	32	SHA3-256	Hash of sec.oping.tut.o7s (echoed back)

Packet 3: FLOW_REQ (Test 1 - Unauthenticated + Unencrypted)

Summary: Client initiates a flow allocation request (FLOW_REQ) with minimal OAP headers since no authentication or encryption is being used.

Key observations:

• SEID is 0x0040 (first allocated flow ID for this session)
• Service hash is carried in management protocol payload (32 bytes)
• OAP header is minimal: only ID and timestamp, no optional fields
• No certificate, ephemeral key, data, or signature in this initial request

Packet 4: FLOW_REPLY (Test 1 - Unauthenticated + Unencrypted)

Summary: Server responds to FLOW_REQ by sending FLOW_REPLY with a new DEID (destination endpoint ID 0x0041) to establish the allocated flow for data transfer.

Key observations:

• SEID 0x0041 is the newly allocated server-side flow endpoint
• DEID 0x0040 reflects the client's flow ID, creating a bidirectional mapping
• No service hash included (FLOW_REPLY only needs the EIDs to identify the flow)
• OAP echoes the client's ID and timestamp, confirming the flow allocation
• Response code 0x00000000 indicates success

Packet 5: ECHO_REQUEST (Test 1 - Plaintext Data)

Summary: Client sends an oping ECHO_REQUEST packet to the server using the allocated flow. This is an application-layer ping request to measure latency and connectivity.

Key observations:

• EID 0x0041 shows traffic from server-side flow ID
• This is the first ping request (ID = 0x00000000)
• Timestamp captures when the ping was sent (seconds in network order)
• Default oping payload is 64 bytes total; 24 bytes header + 40 bytes data

Packet 6: ECHO_REPLY (Test 1 - Plaintext Data)

Summary: Server receives the ECHO_REQUEST and immediately sends back an ECHO_REPLY with the same ID and timestamps, echoing the client's message.

Key observations:

• EID 0x0040 shows traffic from client-side flow ID receiving the reply
• Type field changed from 0x00000000 (REQUEST) to 0x00000001 (REPLY)
• ID, timestamps, and payload data are identical to the request (echoed back)
• Round-trip time can be calculated by comparing current time with echoed timestamp
• Ping succeeded on first attempt with minimal latency

Packet 7: FLOW_REQ (Test 2 - Unauthenticated + Encrypted)

Summary: Client initiates flow allocation with encryption enabled. This FLOW_REQ carries an OAP header with an ephemeral ECDHE P-384 public key (91 bytes) for encryption setup.

Key observations:

• Encryption enabled: ephemeral key present (91 bytes)
• Client sends no certificate, allowing anonymous encryption setup
• No signature (unsigned OAP)
• Ephemeral key is ECDHE P-384 for key exchange

Packet 8: FLOW_REPLY (Test 2 - Unauthenticated + Encrypted)

Summary: Server accepts the encrypted flow allocation request. FLOW_REPLY contains the server's ephemeral key but no certificate (since client didn't send one).

Key observations:

• SEID 0x0042 is the new server-side flow endpoint
• Server's ephemeral key matches client's (both 91 bytes)
• Both keys are now exchanged; client and server can derive shared secret
• No authentication (no certificates) but encryption is negotiated
• Response indicates successful allocation

Packet 9: ECHO_REQUEST (Test 2 - Encrypted Data)

Summary: Client sends encrypted ping request after encryption keys are established. The payload is encrypted with the derived shared secret.

Key observations:

• All 96 bytes of oping data (type, ID, timestamps, payload) are encrypted
• No plaintext oping headers visible; entire packet is ciphertext
• Flow IDs (0x0042) identify which encryption context to use
• Ping still works with encryption transparently

Packet 10: ECHO_REPLY (Test 2 - Encrypted Data)

Summary: Server receives encrypted ping request, decrypts it, and sends encrypted ECHO_REPLY.

Key observations:

• EID 0x0040 shows reply going back to client-side flow
• Ciphertext is different from request (different plaintext: type field differs)
• Both encrypted packets are 96 bytes (same size as Packet 9)
• Client receives encrypted reply, decrypts it, verifies ID and timestamps match request
• Encryption is transparent at application layer: oping works exactly as with plaintext flows

Packet 11: FLOW_REQ (Test 3 - Authenticated + Encrypted)

Summary: Client initiates flow allocation with encryption enabled and server certificate present. This is the full authentication + encryption scenario.

Key observations:

• SEID is 0x0040 (same as Test 2 - reusing the same client flow ID)
• No Certificate field because client is not authenticating
• Ephemeral Key present for ECDHE encryption setup
• No Signature because client has no certificate to sign with

Packet 12: FLOW_REPLY (Test 3 - Authenticated + Encrypted)

Summary: Server responds with its certificate for authentication, ephemeral public key for ECDHE encryption, and a digital signature proving ownership of the certificate.

Ouroboros Allocation Protocol (OAP) - FLOW_REPLY Payload with Full Authentication

Offset	Hex	Field	Size	Value	Notes
0x2b-0x3a	66 bb82 95fa 91a2 7bd3 bd60 1b3e 35f6	ID	16	128-bit identifier	Same ID as client's FLOW_REQ (echoed back)
0x3b-0x42	b9 18 86a8 e37e d566 a0	Timestamp	8	0xb91886a8e37ed566	Server's timestamp
0x43-0x44	0202	Crt_len	2	562 (0x0232)	Server certificate length: 562 bytes
0x45-0x246	2f30 8202 2b30 8201 b2a0 0302 0102 0202 1000 300a 0608 2a86 48ce 3d04 0303 3017 ... 81c8 30 09 06 03 55 1d 13 04 02 30 00	Certificate	562	DER-encoded X.509	Server's certificate (signed by intermediate CA)
0x247-0x248	005b	Eph_len	2	91 (0x005b)	Server's ephemeral public key length: 91 bytes
0x249-0x2a3	30 5930 1306 072a 8648 ce3d 0201 0608 2a86 48ce 3d03 0107 0342 0004 5f3c 6929 cca2 024a ae9f 9aa1 dfc2 a493 3ff3 ff58 b054 74dc d2e2 47fc 7c5b eff5 e129 72b4 de1e 7c09 bf8c fe38 5e8b b22e 59ed 6eb9 dfda 369d 691e 6e2c 122c 9936	Ephemeral Key	91	ECDP-384 public key (DER encoded)	Server's ephemeral ECDHE public key
0x2a4-0x2a5	0000	Data_len	2	0x0000	No application data
0x2a6-0x2a7	0068	Sig_len	2	104 (0x0068)	Digital signature length: 104 bytes
0x2a8-0x30f	30 6602 3100 898e 0f2c 25c0 ... c517 d299 9992 07	Signature	104	ECDSA signature (DER encoded)	Server's signature over OAP header proving certificate ownership

Key Observations:

1. SEID is 0x0043 - New server-side endpoint ID allocated for this authenticated flow 2. DEID is 0x0040 - Client's flow ID from the FLOW_REQ, establishing the bidirectional flow 3. FLOW_REPLY Message Type - Code field is 0x01, no service hash (already identified in FLOW_REQ) 4. Full Certificate - carrying server's complete X.509 certificate signed by intermediate CA 5. Ephemeral Key Present - with server's ECDHE public key for encryption 6. Signature Included - containing ECDSA digital signature over the entire OAP header 7. Same OAP ID - Server echoes back the exact ID from client's FLOW_REQ to confirm association 8. Large Payload - Total of 825 bytes due to certificate + ephemeral key + signature + overhead 9. Authentication Complete - Client verifies: (1) certificate against CA store, (2) signature over entire response ensures authenticity and integrity, (3) echoed ID binds response to this specific request, (4) timestamp prevents replay attacks

Packet 13: Encrypted ECHO_REQUEST (Test 3 - Auth + Encrypted)

Summary: Client sends encrypted ping request after authentication handshake. All application data is protected by encryption using the ephemeral keys established in Packets 11-12.

Key observations:

• No visible protocol structure - all application data appears as ciphertext
• Uses the same source/destination EID pair (0x0043 → 0x0060) established in the FLOW_REQ/FLOW_REPLY handshake
• Encryption is done using the ephemeral key (91 bytes) exchanged in Packet 11's OAP header
• Unlike Packets 11-12, this packet contains no certificate, public keys, or signatures
• The 110-byte encrypted data corresponds to the original oping ECHO_REQUEST message

Packet 14: Encrypted ECHO_REPLY (Test 3 - Auth + Encrypted)

Summary: Server sends encrypted ping reply. Note that the flow identifiers swap, demonstrating bidirectional encrypted communication.

Key observations:

• The EID in offset 0x00 is now 0x0040 (server's view of client's inbound flow)
• Uses the same ephemeral key material as Packet 13, but encryption direction is reversed
• Both packets use AES-GCM with keys derived from the ECDH exchange
• Timestamp 17:39:59.836930 is only 445 microseconds after Packet 13, indicating server-side processing
• The 110-byte encrypted ECHO_REPLY payload is the same size as the request
• All application data is protected by both authentication (X.509 + ECDSA) and encryption (AES-GCM)

Packet 15: FLOW_REQ (Test 4 - Auth + No Encryption)

Summary: Client initiates flow allocation with authentication enabled but encryption disabled. This FLOW_REQ carries an OAP header but no ephemeral key since encryption is not being used.

Ouroboros Allocation Protocol (OAP) - FLOW_REQ Payload (No Encryption)

Offset	Hex	Field	Size	Value	Notes
0x4b-0x5a	8f a6ab 6ea7 ef89 68e1 ed1e 2ede 0919	ID	16	128-bit identifier	Unique flow allocation identifier
0x5b-0x62	fa18 86a8 e490 0de6	Timestamp	8	Network order	Creation timestamp
0x63-0x64	6100	Crt_len	2	0x0000	No certificate in client request
0x65-0x66	0000	Eph_len	2	0x0000	No ephemeral key (no encryption)
0x67-0x68	0000	Data_len	2	0x0000	No application data
0x69-0x6a	0000	Sig_len	2	0x0000	No signature

Key observations:

• No encryption enabled: ephemeral key absent
• Client requests authentication only
• Server will respond with certificate + signature but no ephemeral key
• Packet is minimal compared to Packet 11 (which includes 91-byte ephemeral key)

Packet 16: FLOW_REPLY (Test 4 - Auth + No Encryption)

Summary: Server accepts the authenticated (but not encrypted) flow allocation request. FLOW_REPLY contains the server's X.509 certificate and ECDSA signature for authentication, but no ephemeral key.

Ouroboros Allocation Protocol (OAP) - FLOW_REPLY Payload with Certificate and Signature (No Ephemeral Key)

Offset	Hex	Field	Size	Value	Notes
0x2b-0x3a	8f a6ab 6ea7 ef89 68e1 ed1e 2ede 0919	ID	16	128-bit identifier	Same ID as client's FLOW_REQ (echoed back)
0x3b-0x42	fa18 86a8 e490 3754	Timestamp	8	Network order	Server's timestamp
0x43-0x44	a702	Crt_len	2	0x02a7 (679 decimal)	Certificate length: 679 bytes
0x45-0x270	2f30 8202 2b30 8201 b2a0 0302 0102 0202 1000 300a 0608 2a86 48ce 3d04 0303 3017 ... (DER certificate) ...	Certificate	679	DER-encoded X.509	Server's certificate signed by intermediate CA
0x271-0x272	0000	Eph_len	2	0x0000	No ephemeral key (no encryption)
0x273-0x274	0000	Data_len	2	0x0000	No application data
0x275-0x276	0067	Sig_len	2	0x0067 (103 decimal)	ECDSA signature length: 103 bytes
0x277-0x2dd	3065 0230 75dc 5717 b6d1 75bd 400f 37d9 0c12 85c8 d2ff d7c0 dc1b ca3a 2a3a 789d 6e35 f2b6 2fa5 25dd 83c9 75ec 6c01 964e 6b96 b283 0231 0089 70a9 7e6c c813 a1eb 32a1 4598 3ad3 ef7f ddcc dc3f bdca a50a 421f bdca 21f5 1668 c6c2 77b8 e904 efdc b83d edfc 83	Signature	103	ECDSA signature (DER encoded)	Server's ECDSA signature proving certificate ownership

Key Observations:

1. SEID is 0x0041 - New server-side endpoint ID allocated for this authenticated flow 2. DEID is 0x0040 - Client's flow ID from Packet 15 FLOW_REQ, establishing the bidirectional flow 3. FLOW_REPLY Message Type - Code field is 0x01, no service hash 4. Certificate Field - carrying server's X.509 certificate signed by intermediate CA 5. Separate Signature Field - with ECDSA signature over entire OAP header 6. No Ephemeral Key - since encryption is not being used in Test 4 7. Same OAP ID - Server echoes back the exact ID from client's FLOW_REQ 8. Complete OAP Structure - Full OAP header with all standard fields, just without ephemeral key data 9. Total Payload - 751 bytes total vs Packet 12's 843 bytes (92-byte difference = missing 91-byte ephemeral key) 10. Authentication Only - Client verifies: (1) certificate against CA store, (2) signature over entire response ensures authenticity and integrity, (3) echoed ID binds response to this specific request, (4) timestamp prevents replay attacks 11. Plaintext Data Exchange - After this FLOW_REPLY, all subsequent application data will be transmitted in plaintext

Packet 17: ECHO_REQUEST (Test 4 - Plaintext Data)

Summary: Client sends plaintext ECHO_REQUEST data through the authenticated (but unencrypted) flow. The oping application's ping request is transmitted directly without encryption, relying on the earlier certificate+signature authentication for security.

Application Data - Oping Echo Request (Plaintext)

Offset	Hex	Field	Size	Value	Notes
0x04-0x05	0000	Sequence	2	0x0000	Request sequence number
0x06-0x07	0000	Padding	2	0x0000	Unused field
0x08-0x09	8177	Timestamp (high)	2	0x8177	Request timestamp high bytes
0x0a-0x0b	0000	Timestamp (mid)	2	0x0000	Request timestamp middle bytes
0x0c-0x0d	0000	Timestamp (low)	2	0x0000	Request timestamp low bytes
0x0e-0x0f	0000	Timestamp (micro)	2	0x0000	Request timestamp microseconds
0x10-0x11	aa16	Probe Data (high)	2	0xaa16	Probe payload data
0x12-0x13	1c16	Probe Data (mid-high)	2	0x1c16	Probe payload data
0x14-0x31	0000 ... 0000	Probe Data (padding)	28	0	Remaining probe payload

Key Observations:

1. EID Pair: 0x0041 → Server Flow - Data is directed to the server's endpoint ID 2. Plaintext Transmission - No encryption layer; oping payload is sent as-is 3. Authenticated Flow - Although plaintext, this data travels on the authenticated flow 4. Application Protocol - Oping ping request with sequence number 0, containing timestamp and probe payload 5. Test 4 Characteristic - Demonstrates authenticated communication without encryption 6. Contrast to Test 3 - Packet 13 was 114 bytes with ciphertext; this packet is 82 bytes of plaintext 7. Fixed-size Payload - 64 bytes of probe data

Packet 18: ECHO_REPLY (Test 4 - Plaintext Data)

Summary: Server responds with plaintext ECHO_REPLY data, echoing back the client's request. This confirms successful bidirectional communication over the authenticated (but unencrypted) flow.

Application Data - Oping Echo Reply (Plaintext)

Offset	Hex	Field	Size	Value	Notes
0x04-0x05	0000	Sequence	2	0x0000	Echo of request sequence number
0x06-0x07	0001	Response Code	2	0x0001	Echo reply success indicator
0x08-0x09	0000	Padding	2	0x0000	Unused field
0x0a-0x0b	0000	Padding	2	0x0000	Unused field
0x0c-0x0d	8177	Timestamp (high)	2	0x8177	Echoed request timestamp high bytes
0x0e-0x0f	0000	Timestamp (mid)	2	0x0000	Echoed request timestamp middle bytes
0x10-0x11	0000	Timestamp (low)	2	0x0000	Echoed request timestamp low bytes
0x12-0x13	0000	Timestamp (micro)	2	0x0000	Echoed request timestamp microseconds
0x14-0x15	aa16	Probe Data (high)	2	0xaa16	Echoed probe payload data
0x16-0x17	1c16	Probe Data (mid-high)	2	0x1c16	Echoed probe payload data
0x18-0x31	0000 ... 0000	Probe Data (padding)	26	0	Remaining probe payload

Key Observations:

1. EID Pair: 0x0040 → Client Flow - Server responds to client's endpoint ID 2. Echo Semantics - Sequence number, timestamp, and probe data are echoed from request 3. Response Code 0x0001 - Indicates successful echo response 4. Plaintext Reply - No encryption; server's response payload is readable 5. Authenticated Channel - Although plaintext, this reply is part of the authenticated flow 6. Test 4 Completion - Demonstrates full bidirectional plaintext communication over an authenticated flow 7. Contrast to Test 3 - Packet 14 was 114 bytes with ciphertext; this packet is 82 bytes of plaintext 8. Fixed-size Payload - Same 64-byte probe structure as request