How is TR-369 secured? TLS, end-to-end encryption, certificates and roles

An Agent on a customer’s ONT will reboot, change Wi-Fi settings or download firmware when a Controller asks. So TR-369 spends a whole section on who that Controller is and what it may touch. This guide walks through how USP protects the channel, the Message and the data model, with the requirement behind each step.

Where does USP put its security?

Because USP links components that may also speak protocols outside its scope, “security must be considered from end-to-end”, so USP “contains its own security mechanisms” (§1.6.2). The architecture lists them as separate building blocks: MTP security, “a system for end-to-end confidentiality, integrity and identity authentication”, and access control on a per element basis (§2). Communication between Endpoints is secured by the MTP, by a USP Session Context, or both (§2.1). The TR-369 overview shows where these sit in the protocol.

1. MTPTLS handshakeThe Agent requires an X.509 certificate from its peer.
2. AuthenticationCertificate checkedThe Endpoint ID in the certificate must match the Record’s from_id.
3. AuthorizationRole determinedAssigned, inherited from a trusted CA, or untrusted on first use.
4. Every MessagePermission checkThe Role must allow the action before the Agent performs it.

What does TLS protect on the MTP?

R-MTP.0 requires secure transport “when USP Messages cross inter-network boundaries”, and MTPs that run over TCP are expected to implement at least TLS 1.2 (§4.1.2). Three rules shape how an Agent uses it:

• The peer shows a certificate. When TLS secures an MTP, the Agent must require an X.509 certificate (R-MTP.1).
• The certificate names the Endpoint. It carries the Endpoint ID in its subjectAltName extension, and Records whose from_id does not match must not be processed (R-SEC.0a). Endpoint IDs are explained in USP Agent vs Controller.
• Clocks matter. An Agent that can obtain absolute time should wait for it before setting up TLS. If it connects without it, it must ignore the certificate’s validity dates, and once it has accurate time it must check them (R-MTP.2, R-MTP.3).

The specification also recommends that Agents encrypt all MTPs, “enable it by default, and not implement the ability to disable it” (§8.1). Each binding’s TLS rules are in USP transports compared.

When is MTP encryption not enough?

When something sits in the middle. If the MTP connection runs directly between Agent and Controller, MTP encryption “is sufficient to provide end-to-end encryption and security” (§8). If a proxy or broker sits between them, USP-layer End to End Message Exchange is required, “or the intermediate device must be a trusted part of the end-to-end ecosystem” (§8).

That trusted intermediary is a Trusted Broker: it makes sure the from_id of each brokered Record matches the Endpoint’s certificate or credentials, or it belongs to a closed ecosystem whose Endpoints can be trusted not to spoof their IDs (§1.4). It must authenticate every client with a unique client certificate and make sure their communication cannot be forwarded to another party (R-SEC.4b). And it “MUST NOT inspect USP payloads contained in USP Records” (R-SEC.4c).

When the MTP does not protect a Record, the sender must still protect the integrity of its non-payload fields (R-E2E.29), with an ECDSA P-256 signature or, once a TLS session exists, an HMAC based on SHA-256 (§6.3).

How does end-to-end Secure Message Exchange work?

Broker-based transports and proxies are why it exists: bindings only secure each hop (§6.4). The originating Endpoint secures the payload before segmentation and transmission, and the receiving Endpoint decrypts it after reassembly (§6.4). The Record’s payload_security field says how: PLAINTEXT or TLS12, meaning TLS 1.2 or later (§4.1.3.1).

The TLS handshake itself travels inside USP Records, so Endpoints using TLS12 must exchange Records within an E2E Session Context (R-E2E.41). The Endpoint that started the Session Context acts as TLS client, and a new TLS session takes two round trips (§6.4.1.1).

How does an Agent decide to trust a Controller?

Controllers are authenticated with X.509 certificates, or with shared secrets on a UNIX domain socket MTP (§8.1). Before processing a Controller’s Message, the Agent must hold that Controller’s certificate information, or a Trusted Broker’s, and have a cryptographically protected connection to it (R-SEC.0). Then it works out the Role:

• Trusted Certificate Authorities. The Agent can trust a CA only to vouch for a Controller’s identity, or also to grant a Role that the Controller inherits (§8.3, §8.9.2.4). Stored CA information includes at least a fingerprint and its algorithm (R-SEC.2).
• Self-signed certificates and TOFU. Accepting them is Agent policy. If allowed, the Controller gets an “untrusted” Role on first use (R-SEC.6): the Agent trusts the certificate for encryption but will “heavily restrict what the Controller is authorized to do” (§8.5). The Agent must remember which certificate goes with which Endpoint ID, or every use becomes a first use (R-SEC.8, §8.5).
• Challenges. A passphrase or PIN, printed on the packaging for example, can raise a Controller’s Role. A factory-default value must be unique to the Agent, not derivable from what it reveals, and tries must be limited (§8.7, R-SEC.14 to R-SEC.16).

An Agent must clear all cached encryption sessions and Role authorizations when it reboots (R-SEC.21).

How do Controllers authenticate Agents?

Controllers must authenticate Agents with X.509 certificates, a shared secret, or a Trusted Broker that vouches for them (R-SEC.9). Shared secrets that are not unique per device “are not recommended”, and neither is one certificate shared by several Agents through a wildcarded Endpoint ID, which Controllers need not support (§8.6, R-SEC.11).

For self-signed Agent certificates, the choice is the Controller’s: refuse them, let a person approve each Agent, or accept them automatically (§8.5).

What can a Controller do once it is trusted?

A Role is the set of permissions, an access control list, that an Agent grants a Controller over its Instantiated Data Model (§1.4). The Agent must confirm those permissions before performing any action in a Message (R-SEC.1), and the error for a refusal is 7006 “Permission denied” (§7.8).

Roles live in Device.LocalAgent.ControllerTrust.Role. entries. Each Permission entry names its Targets (the Path Names it covers), an Order, and four permission strings: Param, Obj, InstantiatedObj and CommandEvent (§8.9.2.1). Each string has four characters, always in the order rwxn, for Read, Write, Execute and Notify, with a dash for each missing one. The specification’s example grants full access, then takes back the trust settings (Param lines shown):

Device.LocalAgent.ControllerTrust.Role.1.Permission.1.Order = 1
Device.LocalAgent.ControllerTrust.Role.1.Permission.1.Targets = Device
Device.LocalAgent.ControllerTrust.Role.1.Permission.1.Param = rwxn
Device.LocalAgent.ControllerTrust.Role.1.Permission.2.Order = 2
Device.LocalAgent.ControllerTrust.Role.1.Permission.2.Targets = Device.LocalAgent.ControllerTrust
Device.LocalAgent.ControllerTrust.Role.1.Permission.2.Param = ----

Within one Role, the entry with the larger Order wins where Targets overlap. Across Roles, permissions add up, so r--- and ---n give r--n (§8.9.2.3). Three special Roles have fixed jobs (§8.9.2.2): UntrustedRole for any Controller not yet authorized for another Role, BannedRole for revoked certificates, and SecuredRoles for Controllers allowed to read secured Parameters. Any other Controller reads those as a null value, such as an empty string. Agents should also expose each Controller’s AssignedRole and InheritedRole, so users can spot rogue Controllers (R-SEC.1a).