Relaynet Abstract Message Format, Version 1

  • Id: RS-001.
  • Status: Working draft.
  • Type: Implementation.
  • Proof of concept: https://github.com/relaynet/poc/blob/master/core/serialization.js

Abstract

This document defines version 1 of the Relaynet Abstract Message Format (RAMF), a binary format used to serialize messages in the endpoint and gateway messaging protocols of Relaynet. It also defines some basic requirements for any recipient of the message.

Table of contents

  1. Introduction
  2. Format
  3. Post-Deserialization Validation
  4. Security Considerations
  5. Reserved Concrete Message Format Signatures
  6. Open Issues

Introduction

RAMF messages encapsulate payloads along with relevant metadata to be used for routing, authentication and authorization purposes.

Endpoint and gateway channels communicate amongst themselves using messages whose formats are based on RAMF.

Format

A message is serialized using the following byte sequence (little-endian), and its fields are framed with length prefixes instead of delimiters.

  1. File format signature (10 octets):
    1. Prefix (8 octets): “Relaynet” in ASCII (hex: “52 65 6c 61 79 6e 65 74”).
    2. Concrete message format signature (1 octet).
    3. Format version (1 octet). An 8-bit unsigned integer.
  2. Recipient address. UTF-8 encoded, and length-prefixed with a 10-bit unsigned integer (2 octets). Consequently, the address can be as long as 1024 octets.
  3. Message id. Unique to the sender. This is an opaque value, so it has no structure or semantics. This field is ASCII encoded and length-prefixed with 8-bit integer (1 octets).
  4. Date. Creation date of the message (in UTC), represented as the number of seconds since Unix epoch. This is serialized as a 32-bit unsigned integer (4 octets), so it is not susceptible to the Year 2038 Problem.
  5. Time to live (TTL). Number of seconds during which the message is valid, starting from the date in the Date field. Zero (0) means the message does not expire. The value MUST be encoded as a 24-bit, unsigned integer (3 octets), so maximum TTL is just over 6 months.
  6. Payload. Contains the service data unit encoded with the Cryptographic Message Syntax (CMS). The ciphertext MUST be length-prefixed with a 32-bit unsigned integer (4 octets), so the maximum length is 4 GiB.
  7. Signature. The sender’s detached signature to validate the integrity and authenticity of the message. This is at the bottom to make it easy to generate and process messages with a single pass.
    • The plaintext MUST be the entire RAMF message before the signature.
    • The ciphertext MUST be encapsulated as a valid CMS signed data value where:
      • digestAlgorithms, the collection of message digest algorithm identifiers, MUST contain exactly one OID and it MUST correspond to a valid algorithm per RS-018.
      • encapContentInfo, the signed content, MUST NOT include the content itself, since this is a detached signature.
      • certificates MUST contain the sender’s certificate and it SHOULD also include the rest of the certificates in the chain. All certificates MUST comply with the Relaynet PKI.
      • crls MUST be empty, since certificate revocation is part of the Relaynet PKI.
      • signerInfos MUST contain exactly one signer (SignerInfo), and whose signatureAlgorithm MUST be valid per RS-018.
    • The CMS value MUST be length-prefixed with a 14-bit unsigned integer (2 octets), so the maximum length is 16 KiB.

Post-Deserialization Validation

Recipients and brokers of a RAMF message MUST validate the message as soon as it is received, before any further processing or relay. The message MUST be refused when any of the conditions below is not met:

  • The message date MUST NOT be more than 5 minutes in the future.
  • The message TTL MUST NOT be more than 5 minutes in the future.
  • The message date MUST be within the period of time during which the sender certificate was valid.
  • The sender’s certificate MUST be embedded in the signature.
  • All certificates MUST be valid per Relaynet PKI.
  • The signature MUST be valid according to the CMS verification process and the specified signature algorithm. Additionally, the signature MUST be deemed invalid if the signature algorithm is unsupported or the hashing algorithm is unsupported.

The purpose of the grace period in the date and TTL fields is to account for a potential clock drift.

Security Considerations

To avoid replay attacks, the message id SHOULD be persisted until the TTL expires, and until then, reject any incoming message from the same sender and the same id.

Nodes can further protect from replay attacks, amongst other attack vectors, by establishing a secure session with the Relaynet Key Agreement Protocol.

Note that all cryptographic algorithms MUST comply with RS-018.

Reserved Concrete Message Format Signatures

The following concrete signatures have been reserved by other Relaynet specifications:

Open Issues