The MyClerk Protocol: Tiered Security Communication for Distributed Family Systems

1.1. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. 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.¶

2.1. 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.¶

2.2. Default Port

When using TCP or UDP as the transport protocol, implementations SHOULD use port 5657 as the default listening port. This port is registered with IANA for the "myclerk" service (see Section 11.1).¶

Implementations MAY use alternative ports when:¶

• Operating behind a reverse proxy or load balancer¶
• Running multiple instances on the same host¶
• Required by local network policies¶

Service discovery mechanisms (such as mDNS or DNS-SD) SHOULD advertise the actual port in use, regardless of whether it matches the default.¶

2.3. Security Tiers Overview

3.1. Common Header Fields

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

 0
 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|V V|T T T|C|F|E|
+-+-+-+-+-+-+-+-+

V: Protocol Version (2 bits) - Currently 0
T: Security Tier (3 bits) - Values 0-5
C: Compressed (1 bit) - Payload is compressed
F: Fragmented (1 bit) - Message is fragmented
E: Encrypted (1 bit) - Payload is encrypted

3.2. Tier 0 Header (1 byte)

Tier 0 is used for messages tunneled inside an already-secure session. It provides minimal overhead.¶

 0
 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|0 0|0 0 0|C|F|E|
+-+-+-+-+-+-+-+-+

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.¶

3.3. Tier 1 Header (4 bytes)

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V V|0 0 1|C|F|E|        Operation Code         |   Sequence    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Operation Code (16 bits)

Identifies the operation. See Section 6.¶

Sequence (8 bits)

Message sequence number, wrapping at 255.¶

3.4. Tier 2 Header (6 bytes)

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V V|0 1 0|C|F|E|        Operation Code         |   Sequence    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          Session ID           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Session ID (16 bits)

Identifies the session context for this message.¶

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

3.5. Tier 3 Header (12 bytes)

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V V|0 1 1|C|F|E|        Operation Code         |   Sequence    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          Session ID           |           Timestamp           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Timestamp (cont.)        |             Nonce             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

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 [RFC8439].¶

3.6. Tier 4 Header (42 bytes)

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V V|1 0 0|C|F|E|        Operation Code         |   Sequence    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          Session ID           |           Timestamp           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Timestamp (cont.)        |             Nonce             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            Key ID                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
|                    ECDH Public Key (X25519)                   |
|                         (32 bytes)                            |
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Key ID (32 bits)

Identifier for the key being used or negotiated.¶

ECDH Public Key (256 bits)

X25519 public key as specified in [RFC7748].¶

3.7. Tier 5 Header (58 bytes)

Tier 5 extends Tier 4 with a full Poly1305 authentication tag in the header:¶

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    [Tier 4 Header - 42 bytes]                 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
|                   Poly1305 Tag (16 bytes)                     |
|                                                               |
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

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.¶

5.1. ECDH Key Exchange

For Tier 4+ sessions:¶

shared_secret = X25519(local_private_key, remote_public_key)

session_key = HKDF-SHA256(
    IKM  = shared_secret,
    salt = nonce_initiator || nonce_responder,
    info = "myclerk-session-v0",
    L    = 32
)

5.2. 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:¶

new_key = HKDF-SHA256(
    IKM  = current_key,
    salt = "rotate",
    info = rotation_counter (4 bytes, big-endian),
    L    = 32
)

6.1. Core Operations (0x0000-0x00FF)

6.2. Resource Sharing Operations (0x0200-0x02FF)

Resource Sharing operations enable devices to expose and consume resources across the network. These operations support video, audio, HID, and GPU services.¶

6.3. Hardware Passthrough Operations (0x0600-0x06FF)

Hardware Passthrough operations enable low-level access to hardware interfaces. Unlike service-based resource sharing, these operations provide direct protocol-level access to hardware buses.¶

6.4. Vendor Extension: SMS Gateway (0xF350-0xF37F)

The SMS Gateway vendor extension provides application-level SMS handling for the MyClerk platform. Unlike the low-level GSM Modem operations which deal with AT commands and hardware, these operations provide intelligent message routing, TAN/OTP detection, and emergency fallback services.¶

7.1. SESSION_INIT Payload

session-init = {
    nonce: bstr .size 8,
    timestamp: uint,
    ? capabilities: [* capability],
    ? device-id: bstr .size 16,
}

capability = &(
    compression-lz4: 0,
    compression-zstd: 1,
    encryption-chacha20: 2,
    encryption-aes256gcm: 3,
    fragmentation: 4,
    streaming: 5,
    federation: 6,
    vfs: 8,
)

7.2. SESSION_ACK Payload

session-ack = {
    session-id: uint .size 2,
    nonce: bstr .size 8,
    selected-tier: uint .le 5,
    ? selected-capabilities: [* capability],
}

7.3. SESSION_RESUME Payload

session-resume = {
    old-session-id: uint .size 2,
    ticket: bstr .size 64,
}

; Ticket structure (encrypted with server key, AES-256-GCM):
; - session-key: 32 bytes
; - device-id: 16 bytes
; - issued-at: 4 bytes (Unix timestamp)
; - expires-at: 4 bytes (Unix timestamp)
; - ticket-nonce: 8 bytes

8.1. Minimum Tier Requirements

The following operations have minimum tier requirements:¶

9.1. 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.¶

10.1. 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¶

10.2. 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.¶

10.3. 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.¶

10.4. 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.¶

10.5. 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.¶

11.1. Service Name and Port Number Registration

IANA is requested to register the following service name and port number in the "Service Name and Transport Protocol Port Number Registry" [RFC6335]:¶

Service Name:

myclerk¶

Port Number:

5657¶

Transport Protocol(s):

TCP, UDP¶

Description:

MyClerk Protocol¶

Assignee:

IESG <iesg@ietf.org>¶

Contact:

IETF Chair <chair@ietf.org>¶

Reference:

This document¶

TCP is the primary transport for control messages, synchronization, authentication, and VFS operations. UDP is used for real-time streaming (video, audio) and low-latency sensor telemetry where latency is prioritized over reliability.¶

11.2. Operation Code Registry

IANA is requested to create a new registry titled "MyClerk Protocol Operation Codes" with the following structure:¶

Registration Procedure:

Expert Review per [RFC8126]¶

Reference:

This document¶

The initial entries are the operation codes defined in Section 6 of this document, organized into the following ranges:¶