]> Arcan Consulting

rfc@arcan-consulting.de https://myclerk.eu

Applications Independent Submission protocol family distributed encryption smart home This document specifies the MyClerk Protocol, a tiered-security communication protocol designed for distributed family orchestration systems. The protocol provides six security tiers ranging from 1-byte minimal overhead for tunneled messages to 144-byte full security for critical operations. It supports multiple transport mechanisms including NATS, Matrix, WebSocket, and direct TCP, while maintaining end-to-end encryption using ChaCha20-Poly1305 and X25519 key exchange. The protocol is transport-agnostic, federation-capable, and optimized for environments ranging from resource-constrained IoT devices to full-featured desktop clients.

Introduction Modern families operate across multiple locations and devices: a primary home with network-attached storage, a vacation house with a mini-PC, grandparents with a Raspberry Pi, and mobile devices requiring access while traveling. The MyClerk Protocol addresses the communication requirements of such distributed family systems. Traditional protocols impose significant overhead that becomes problematic for constrained channels. The MyClerk Protocol introduces tiered security levels, allowing applications to select appropriate overhead based on the security requirements of each operation.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

Node

A device participating in a MyClerk deployment, such as a server, desktop client, mobile device, or IoT device.

Core Node

A node classified as stable and reliable, expected to maintain high availability (>95% uptime over 30 days).

Bonus Node

A node with variable availability, used opportunistically for additional redundancy.

Family

A group of users and nodes sharing a common trust domain and cryptographic key hierarchy.

Federation

The interconnection of multiple families for resource sharing or communication.

Tier

A security level (0-5) determining the header structure and cryptographic protections applied to a message.

Session

A stateful connection between two endpoints with established cryptographic keys.

Protocol Overview The MyClerk Protocol is a binary protocol using MessagePack for payload encoding. It defines six security tiers with increasing header sizes and cryptographic protections.

Design Goals

1. Tiered Security: 1-144 bytes overhead depending on security requirements.
2. Transport Agnostic: Operates over NATS, Matrix, WebSocket, TCP, or other transports.
3. Federation Ready: Supports multi-server, multi-family deployments.
4. Future Proof: Extensible operations and feature negotiation.

Security Tiers Overview Security Tier Summary

Tier	Header Size	Encryption	Authentication	Use Case
0	1 byte	None (tunneled)	None	Inside secure session
1	4 bytes	None	None	Fire-and-forget commands
2	6 bytes	Optional	CRC-16	Home automation
3	12 bytes	ChaCha20-Poly1305	HMAC-32	Conversational
4	42 bytes	ChaCha20-Poly1305	HMAC-64	Key exchange
5	58+ bytes	ChaCha20-Poly1305	HMAC-256 + Poly1305	Maximum security

Message Format All messages consist of a header, optional payload, and optional trailer. The header format varies by security tier.

Common Header Fields The first byte (Flags) is present in all tiers and has the following structure:

Tier 0 Header (1 byte) Tier 0 is used for messages tunneled inside an already-secure session. It provides minimal overhead. Tier 0 messages MUST only be sent within an established Tier 3+ session. Implementations receiving a Tier 0 message outside of a secure session MUST discard it.

Tier 1 Header (4 bytes)

Operation Code (16 bits)

Identifies the operation. See .

Sequence (8 bits)

Message sequence number, wrapping at 255.

Tier 2 Header (6 bytes)

Session ID (16 bits)

Identifies the session context for this message.

Tier 2 messages SHOULD include a CRC-16 trailer for error detection.

Tier 3 Header (12 bytes)

Timestamp (32 bits)

Unix timestamp in seconds. Used for replay protection.

Nonce (16 bits)

Random nonce component. Combined with timestamp and counter to form the full 96-bit nonce for ChaCha20-Poly1305.

Tier 3 messages with the E flag set MUST be encrypted using ChaCha20-Poly1305 as specified in .

Tier 4 Header (42 bytes)

Key ID (32 bits)

Identifier for the key being used or negotiated.

ECDH Public Key (256 bits)

X25519 public key as specified in .

Tier 5 Header (58 bytes) Tier 5 extends Tier 4 with a full Poly1305 authentication tag in the header: Tier 5 messages MUST include a full HMAC-SHA256 (32 bytes) in the trailer, providing dual authentication: Poly1305 for AEAD integrity and HMAC-SHA256 for post-quantum resistance.

Nonce Construction ChaCha20-Poly1305 requires a 96-bit (12-byte) nonce that MUST NOT be reused with the same key. The MyClerk Protocol constructs nonces as follows:

Timestamp (32 bits)

Unix epoch seconds. Provides cross-session replay protection.

Random (32 bits)

Cryptographically random value generated per session using a CSPRNG. Provides 2^32 possible values per second.

Counter (32 bits)

Per-message counter starting at 0, incremented for each message. Allows 2^32 messages per session.

All fields are encoded in big-endian byte order. This construction provides a collision probability of less than 2^-80 per year at 1 million operations per second, assuming proper CSPRNG implementation.

Key Derivation Session keys are derived using HKDF as specified in with SHA-256 as the hash function.

ECDH Key Exchange For Tier 4+ sessions:

Key Rotation Keys MUST be rotated after any of the following conditions:

• 2^32 messages sent (nonce exhaustion)
• 24 hours elapsed (time-based)
• Explicit KEY_ROTATE operation received

Rotated keys are derived as:

Protocol Operations Operations are identified by a 16-bit operation code. The operation space is divided into ranges: Operation Code Ranges

Range	Category
0x0000-0x00FF	Core Operations (Session, Key Management)
0x0100-0x01FF	Standard Operations (Device, Identity, Messaging)
0x0200-0x02FF	Resource Sharing
0x0300-0x03FF	Federation
0x0400-0x04FF	Billing and Economics
0x0500-0x05FF	Virtual File System (VFS)
0xF000-0xFFFE	Vendor Extensions
0xFFFF	Reserved

Core Operations (0x0000-0x00FF)

Session Management (0x0000-0x000F) Session Management Operations

Code	Name	Description
0x0000	NOP	No operation
0x0001	KEEPALIVE	Session keepalive
0x0002	KEEPALIVE_ACK	Keepalive acknowledgment
0x0003	SESSION_INIT	Initialize session
0x0004	SESSION_ACK	Session acknowledgment
0x0005	SESSION_CLOSE	Close session
0x0006	SESSION_CLOSE_ACK	Close acknowledgment
0x0007	SESSION_RESUME	Resume session with ticket
0x0008	SESSION_RESUMED	Session resumed

Key Management (0x0010-0x001F) Key Management Operations

Code	Name	Description
0x0010	KEY_EXCHANGE_INIT	Initiate key exchange
0x0011	KEY_EXCHANGE_RESPONSE	Key exchange response
0x0012	KEY_EXCHANGE_COMPLETE	Key exchange complete
0x0016	SESSION_ROTATE	Rotate session key
0x0017	SESSION_REVOKE	Revoke session key

Payload Formats Payloads are encoded using MessagePack (a subset of CBOR). This section defines payload structures using CDDL .

SESSION_INIT Payload

SESSION_ACK Payload

SESSION_RESUME Payload

Tier Compatibility When endpoints support different maximum tiers, they MUST negotiate to the highest common tier. The server MUST respond with the minimum of its supported tier and the client's requested tier. Servers MAY enforce minimum tier requirements for specific operations. If a client requests an operation at an insufficient tier, the server MUST respond with error code 0x12 (FORBIDDEN) and include the required tier in the error payload.

Minimum Tier Requirements The following operations have minimum tier requirements: Minimum Tier Requirements

Operation Category	Minimum Tier
Lock/Unlock (physical access)	3
Key Exchange	4
Federation Operations	4
Emergency Operations	3

Error Handling Error codes are 8-bit values organized into ranges: Error Codes

Range	Category
0x00-0x0F	Success
0x10-0x1F	Client Errors
0x20-0x2F	Server Errors
0x30-0x3F	Federation Errors
0xF0-0xFF	Reserved

Specific Error Codes

0x00 OK

Operation completed successfully.

0x10 BAD_REQUEST

Malformed message or invalid parameters.

0x11 UNAUTHORIZED

Authentication required or failed.

0x12 FORBIDDEN

Insufficient permissions or tier.

0x13 NOT_FOUND

Requested resource does not exist.

0x17 INVALID_SESSION

Session expired or invalid.

0x20 INTERNAL_ERROR

Server encountered an unexpected error.

0x21 SERVICE_UNAVAILABLE

Service temporarily unavailable.

0x22 TIMEOUT

Operation timed out.

Security Considerations

Nonce Reuse Reusing a nonce with the same key in ChaCha20-Poly1305 completely compromises the confidentiality and authenticity of all messages encrypted with that key-nonce pair. Implementations MUST ensure nonces are never reused by:

• Using cryptographically random values for the Random field
• Maintaining a monotonic counter per session
• Rotating keys before counter exhaustion

Replay Protection Tier 3+ messages include timestamps for replay protection. Implementations SHOULD reject messages with timestamps more than 5 minutes in the past or future. Session resumption tickets include a nonce that MUST be tracked to prevent replay attacks.

Tier Downgrade Attacks An attacker might attempt to force communication at a lower tier. Servers MUST enforce minimum tier requirements for sensitive operations. Clients SHOULD warn users when connecting at a lower tier than expected.

Key Compromise If a session key is compromised, an attacker can decrypt all messages in that session. The 24-hour automatic key rotation limits the window of exposure. For forward secrecy, implementations SHOULD use ephemeral ECDH keys for each session.

Post-Quantum Considerations The X25519 key exchange is not quantum-resistant. Tier 5 includes an additional HMAC-SHA256 trailer that provides some protection against future quantum attacks on Poly1305. Implementations concerned about long-term confidentiality SHOULD use Tier 5 for sensitive data.

IANA Considerations This document has no IANA actions. If this protocol were to be standardized, IANA would be requested to create a registry for MyClerk Protocol operation codes with the ranges defined in .

References Normative References &RFC2119; &RFC8174; &RFC8439; &RFC5869; &RFC7748; &RFC8610; &RFC8949;

Acknowledgements This specification is part of the MyClerk project, a privacy-first family orchestration platform currently in development. For more information, visit https://myclerk.eu.