Skip to content

Instantly share code, notes, and snippets.

@ajsb85

ajsb85/usp_permissions.md

Created June 5, 2025 08:45
Show Gist options
  • Save ajsb85/cd1dc81268525c73d0e9b03a61fe734c to your computer and use it in GitHub Desktop.
Save ajsb85/cd1dc81268525c73d0e9b03a61fe734c to your computer and use it in GitHub Desktop.
Download ZIP
Raw
usp_permissions.md

The USP (User Services Platform) permission system is a critical component of the TR-369 specification, designed to provide robust and granular access control for managing connected devices. It's a complex interplay between the Controller and the Agent, leveraging various mechanisms to ensure security and compliance.

1. Overview of the USP Permission System

The USP permission system operates on the principle of least privilege, meaning that any entity (Controller) interacting with a USP Agent (the managed device) should only be granted the minimum necessary access rights to perform its intended function. This is vital in heterogeneous environments with multiple stakeholders (e.g., ISPs, IoT platforms, end-users) and diverse devices.

The system is characterized by a layered approach:

  • Controller-Side (Proactive Evaluation): The Controller is responsible for determining if its internal user (human or automated process) is authorized to initiate a specific USP operation. This acts as a first line of defense, preventing unauthorized requests from even being sent to the Agent. Our Go program's RBAC/ABAC logic resides here.
  • Agent-Side (Primary Enforcement): The Agent is the ultimate authority for access control. Every USP message received by the Agent is rigorously validated against its configured security policies before any action is performed on the device's resources. This is where the core enforcement logic resides, ensuring the device's integrity regardless of the Controller's intent or potential compromise.

2. Core Concepts and Definitions in USP Permissions

To understand the USP permission system fully, the following key concepts are essential, drawing from TR-369, TR-181 (Device Data Model), and TR-106 (Data Model Template):

  • Controller Identity & Trust: Each USP Controller has a unique ControllerID. The Agent must be configured to trust specific Controllers. This trust is established through:
    • Mutual Authentication: Typically using X.509 certificates (mTLS) over secure Message Transfer Protocols (MTPs) like WebSockets, MQTT, or UNIX Domain Sockets. The subjectAltName extension in the certificate is used to convey the ControllerID (R-SEC.0a).
    • Pre-shared Keys/Enrollment: Agents can be pre-provisioned with trusted ControllerIDs or keys.
    • Dynamic Onboarding: A highly privileged Controller can dynamically onboard and grant permissions to new Controllers by modifying the Agent's internal Device.LocalAgent.Controller object (R-DIS.0).
  • Agent Identity: Each USP Agent has a unique EndpointID, which Controllers use to target specific devices.
  • Data Model & Attributes (TR-181, TR-106): USP Agents expose their capabilities and configurable parameters through a hierarchical data model (e.g., Device.WiFi.SSID, Device.Reboot()). Critical attributes for permissioning include:
    • Writable: Indicates if a parameter's value can be changed by a Set message.
    • Addable: Indicates if new instances of an object can be created under a parent path via an Add message.
    • Deletable: Indicates if an instance of an object can be removed via a Delete message.
    • Executable: Indicates if a command can be invoked via an Operate message.
    • Secured: (From TR-106 and TR-181). This is paramount. A Secured parameter or object requires special authorization. Access to Secured elements is restricted to Controllers with higher trust levels or specific roles (like the SecuredRole mentioned in TR-369 Amendment 3, or the secured_user role in our Go program). This attribute protects sensitive configurations (e.g., Wi-Fi passwords, admin credentials, factory reset commands).
  • Access Control Lists (ACLs) / Roles: On the Agent side, ACLs (or "Roles" as USP refers to them, implying a set of permissions) are the primary mechanism for runtime permission enforcement (R-SEC.1). An ACL maps a ControllerID to allowed operations on specific data model paths. ACLs can use path patterns (wildcards like Device.**), specify allowed operations (Get, Set, Add, Delete, Operate), and are evaluated in a defined order (most specific rule takes precedence). The fundamental rule is Default Deny: if no explicit rule grants access, access is denied.
    • TR-369 Amendment 3 introduces the concept of SecuredRole and clarifies that role permissions apply to both Supported and Instantiated Data Models, and specifically to secured parameters.
  • Interface Security: USP allows Agents to apply different security policies based on the originating MTP interface. For instance, a local UNIX Domain Socket MTP (UDSConnectRecord) might have different trust implications than a remote WebSocket MTP (WebSocketConnectRecord) or MQTT MTP (MQTTConnectRecord).

3. Permission Enforcement and Evaluation Flow

3.1. Agent-Side Enforcement: The Primary Gatekeeper

The Agent is the ultimate authority. Every USP message undergoes a multi-stage authorization process:

  1. MTP-Level Security & Authentication: The Agent first authenticates the Controller's connection using MTP-specific mechanisms (e.g., mTLS certificates, shared secrets). This verifies the identity of the Controller.
    • Example from usp.txt: The specification/security directory contains diagrams like check-cert.png and determine-role.png that illustrate how the Agent checks the Controller's certificate and derives its Role or trust level based on factors like trusted Certificate Authorities (TrustedCertificateAuthorities in TR-369). R-E2E.43 explicitly states that USP Endpoints MUST be mutually authenticated using X.509 certificates.
  2. USP Message Parsing & Controller Identification: The Agent parses the incoming USP message (Protocol Buffers) and extracts the ControllerID from the header (from_id).
  3. ACL Evaluation (Policy Decision Point - PDP):
    • For the extracted ControllerID and the Requested Path (the data model element being targeted by the USP message), the Agent consults its internal ACLs (its defined "Roles").
    • It finds the most specific ACL rule that applies.
    • It checks if the requested USP operation (Get, Set, Add, Delete, Operate) is permitted by that rule.
    • Default Deny: If no explicit rule grants access, it's denied.
    • R-SEC.1 (from usp.txt): "An Agent MUST confirm a Controller has the necessary permissions to perform the requested actions in a Message prior to performing that action." This is the core requirement for Agent-side authorization.
  4. Data Model Attribute Checks (Fine-grained Authorization):
    • Even if the ACL grants general permission, the Agent performs a secondary check against the inherent attributes of the target data model element.
    • Writable Check: For Set operations, the Agent confirms the parameter is Writable.
    • Addable/Deletable Check: For Add and Delete operations, the Agent checks the parent object/target instance for Addable or Deletable attributes.
    • Executable Check: For Operate messages, it confirms the command is Executable.
    • Secured Parameter Handling: If a parameter is Secured, the Agent's policy explicitly requires higher privileges (e.g., SecuredRole). The ROLE_POLICIES in our Go program demonstrate this by routing requests for Secured resources through the canAccessSecuredResource policy function. The usp.txt CHANGELOG.md for v1.4.0 explicitly states: "Updated Role Definition Section with clarifications to Role permissions applying to Supported and Instantiated Data model and the Secured Role as applying to 'secured' parameter in the path(s), with examples of both."
  5. Interface Security (Binding-Specific):
    • Different MTPs might have varying levels of inherent security or be exposed on different network segments. The Agent can apply additional restrictions based on the MTP used (e.g., blocking Set messages over insecure MTPs for certain sensitive parameters). usp.txt describes MTP bindings like WebSocket (RFC6455), MQTT (MQTT-5-0), STOMP (STOMP-1-2), and UNIX Domain Sockets. Each MTP section in TR-369 includes specific security considerations and requirements (e.g., R-MTP.5 in specification/mtp/index.md for error handling).

3.2. Controller-Side Evaluation: Proactive Gatekeeping

The Controller acts as the Policy Enforcement Point (PEP) for its own users before even generating USP messages.

  • Internal IAM (RBAC/ABAC): The Controller manages its own user identities, roles, and attributes. Our Go program's User struct, RoleName enums, AppPermission enums, ROLE_DEFINITIONS, and ROLE_POLICIES maps directly implement this.
  • PolicyContext (PIP): For each requested action, the Controller gathers relevant attributes (user's roles/department, target Agent's owner/department, Secured status of the parameter being accessed, current time, IP address). This PolicyContext is then passed to the PDP.
  • CheckPermission (PDP): This function determines if the user is authorized based on a hybrid evaluation of their roles (RBAC) and specific attribute-based policies (ABAC). This prevents unauthorized requests from leaving the Controller's domain.
  • Synchronization: While not explicitly a "USP" requirement for the Agent, Controllers need to handle USP_ERROR messages from the Agent, especially 7006 (Permission Denied), to update their internal state or inform the user that their request was rejected at the Agent. This feedback loop is crucial for a robust system.

4. Real-World Use Cases and Agent Enforcement

Use Case 1: A Controller Attempting to Modify a Sensitive Parameter (e.g., Wi-Fi password)

  • Scenario: An "ISP Customer Service" Controller user attempts to change Device.WiFi.SSID (non-secured, writable) and Device.WiFi.Password (secured, writable) on agent-001. The "ISP Customer Service" user is only assigned the RoleOperator role, which in our policies, can ServiceElementUpdate if the agent's Department matches, but it doesn't have canAccessSecuredResource granted generally.
  • Controller-Side:
    • The Controller's internal logic (e.g., triggered by a web UI for the customer service agent) prepares a SET USP message.
    • Before sending, the Controller's CheckPermission is invoked for ServiceElementUpdate on Device.WiFi.SSID and Device.WiFi.Password.
    • For Device.WiFi.SSID: Policy canUpdateAgentIfDepartmentMatches is checked. If agent-001's department matches operator1's department ("Operations"), this part passes.
    • For Device.WiFi.Password: The ServiceElementUpdate permission is checked. Even if canUpdateAgentIfDepartmentMatches passes, the canAccessSecuredResource policy (triggered because Device.WiFi.Password is Secured) will likely fail for RoleOperator because IsSecured is false for operator1, and RoleOperator does not implicitly gain secured access.
    • Outcome (Controller): The Controller might prevent sending the entire SET message or redact the Device.WiFi.Password part if its internal logic is sophisticated enough. If it sends the message anyway, the Agent will catch it.
  • Agent-Side Enforcement:
    1. Agent receives the SET message from the Controller.
    2. MTP/Authentication: Validates the Controller's connection (e.g., mTLS).
    3. Overall Message Permission: Checks USPMessageSet for the Controller's identity. (Assume it passes for operators generally).
    4. Per-Path/Attribute Checks:
      • For Device.WiFi.SSID:
        • Checks ServiceElementUpdate for this path. (Passes as per ACL/Role).
        • Checks Writable attribute of Device.WiFi.SSID (true in our Agent.DataModel). (Passes).
        • Checks Secured attribute (false). (Passes canAccessSecuredResource trivially).
        • Result: SSID is updated.
      • For Device.WiFi.Password:
        • Checks ServiceElementUpdate for this path. (Passes as per ACL/Role).
        • Checks Writable attribute of Device.WiFi.Password (true). (Passes).
        • Crucial Secured check: The Agent sees Device.WiFi.Password is Secured. It invokes the canAccessSecuredResource policy (Policies["canAccessSecuredResource"](policyCtx)). Since operator1 is not IsSecured and not admin, this policy returns false.
        • Outcome: Password update is denied.
    5. Error Reporting: The Agent sends a SET_RESP USP message. The ModifiedPaths list will include Device.WiFi.SSID, but not Device.WiFi.Password. Instead, the response (in a real USP message, or conceptually in our simulated one) would include a SetFailure element for Device.WiFi.Password with err_code: 7006 (USPErrorPermissionDenied) and an appropriate err_msg.

Use Case 2: Multi-tenant Environments with Multiple Controllers having Different Roles

  • Scenario:
    • ISP Controller (admin1, RoleAdmin, Department: Operations): Manages agent-001. Needs full control.
    • Third-Party Diagnostic App Controller (diag_user, RoleViewer, Department: Support): Wants to monitor agent-002's performance stats (Device.LAN.1.Stats.BytesSent).
  • Agent-Side Enforcement (ACL Configuration):
    • agent-001 (owned by admin1 in Operations): Has ACLs configured (or implicit policies) granting admin1 full access.
    • agent-002 (owned by operator1 in Sales): Has ACLs allowing diag_user (RoleViewer) read access to Device.LAN.1.Stats.** but no Set/Add/Delete/Operate permissions on any path, and no access to Secured parameters.
  • Controller-Side Evaluation:
    • ISP Controller: admin1 attempts Set on agent-001's Device.Time.NTPServer1. The Controller's internal logic confirms admin1 has USPMessageSet and ServiceElementUpdate permissions. Policy canUpdateAgentIfDepartmentMatches is evaluated for agent1. Since admin role bypasses most checks, it succeeds. The USP SET message is sent.
    • Diagnostic Controller: diag_user attempts Get on agent-002's Device.LAN.1.Stats.BytesSent. The Controller's internal logic confirms diag_user has USPMessageGet and ServiceElementView permissions. The canViewAgentIfUnblocked policy is also checked. The USP GET message is sent.
    • Diagnostic Controller attempts Set on agent-002's Device.LAN.1.IPAddress: The Controller's internal CheckPermission for USPMessageSet and ServiceElementUpdate for diag_user will fail based on ROLE_POLICIES[RoleViewer] which explicitly sets USPMessageSet to false. The UI for diag_user on the Controller might not even allow this action to be selected.
  • Agent-Side Enforcement:
    • ISP Controller (for agent-001): All operations are permitted by Agent's ACLs and data model attributes. Set on Device.Time.NTPServer1 succeeds.
    • Diagnostic Controller (for agent-002 - Get on Stats):
      1. Agent receives GET from diag_user.
      2. ACL grants USPMessageGet to RoleViewer.
      3. ACL grants ServiceElementView to RoleViewer on Device.LAN.1.Stats.**.
      4. Device.LAN.1.Stats.BytesSent is not Secured.
      5. Outcome: Success. Agent returns GET_RESP with data.
    • Diagnostic Controller (for agent-002 - Set on IPAddress):
      1. Agent receives SET from diag_user.
      2. ACL denies USPMessageSet to RoleViewer (or no explicit grant).
      3. Outcome: Agent immediately returns USP_ERROR (7006) to the Diagnostic Controller.

Use Case 3: Dynamic Controller Onboarding and ACL Negotiation

  • Scenario: A new "Home Automation App" (e.g., controller-iot-app) needs to control a smart bulb (Device.IoT.Bulb.1.) connected to agent-001. Initially, agent-001 has no ACL entries for controller-iot-app.
  • Agent-Side Enforcement:
    1. Initial State (agent-001): Default ACL behavior is "deny all" for unknown controllers. The Device.IoT.Bulb.1. object is Writable and Addable but its LightLevel parameter is Secured and Writable.
    2. Onboarding: A trusted ISP Admin (admin1) sends a SET USP message to agent-001 to add a new Device.LocalAgent.Controller entry and associated ACL rules for controller-iot-app. The ACL entry grants Set and Get permissions only to Device.IoT.Bulb.1.Color and Device.IoT.Bulb.1.Brightness for controller-iot-app. It also sets canAccessSecuredResource policy to true for this specific controller on Device.IoT.Bulb.1.**.
    3. Agent admin1's SET on ACL objects is authorized (since admin1 has full control). The ACL is updated.
    4. IoT App attempts Set on Device.IoT.Bulb.1.Color (value: "Red"):
      • IoT App Controller sends SET USP message from controller-iot-app.
      • Agent receives SET. Checks USPMessageSet for controller-iot-app. (Passes if the onboarding process also included granting generic USPMessageSet to new app controllers, or the specific canAccessSecuredResource policy covers it).
      • Checks ServiceElementUpdate on Device.IoT.Bulb.1.Color. Agent finds the specific ACL rule created by admin1. (Passes).
      • Checks Writable attribute of Device.IoT.Bulb.1.Color (true). (Passes).
      • Checks Secured attribute of Device.IoT.Bulb.1.Color (false). (Passes canAccessSecuredResource trivially).
      • Outcome: Success. Bulb color is set.
  • Controller-Side Evaluation: The IoT App Controller, upon successful onboarding, now knows it can send Set messages to these specific parameters and presents appropriate controls to the end-user.

Use Case 4: An Unauthorized Controller Attempting Access Over a Trusted Interface

  • Scenario: A malicious actor spoofs ControllerID: "diag_user" (a valid but low-privilege Controller) and attempts to send a DELETE USP message for Device.DeviceInfo.** over a seemingly "trusted" (e.g., TLS-secured) WebSocket interface to agent-002. Device.DeviceInfo is not deletable.
  • Agent-Side Enforcement:
    1. MTP-Level: The Agent validates the TLS connection, establishing trust for the connection itself.
    2. Controller Identification: Agent extracts ControllerID: "diag_user".
    3. Overall Message Permission: Agent checks USPMessageDelete for diag_user. The ACL for diag_user (RoleViewer) does not permit USPMessageDelete (as explicitly set to false in ROLE_POLICIES).
    4. Outcome (First Check): Agent immediately denies the request based on the lack of high-level message type permission. It constructs and sends a USP_ERROR with err_code: 7006 ("Permission Denied").
    5. Fallback (If general permission allowed): Even if USPMessageDelete was allowed for diag_user (e.g., by misconfiguration):
      • Agent would check ServiceElementDelete for Device.DeviceInfo.**. ACL for diag_user would likely deny this specific path for deletion.
      • The Agent would then check the intrinsic attributes of Device.DeviceInfo. It would discover that Device.DeviceInfo is an object, but its Deletable attribute is false.
      • Outcome (Second/Third Check): The Agent would still deny the request, returning USP_ERROR with err_code: 7006 or 7004 (Operation Failed due to non-deletable object).
  • Security Isolation: This showcases that even if a network interface is compromised or a low-privilege ControllerID is spoofed, the Agent's application-layer ACLs and data model attribute checks provide critical security isolation, preventing unauthorized operations.

6. Principle of Least Privilege (PoLP) in USP Implementation

USP strongly supports PoLP through its multi-layered design and granular controls:

  • Default Deny: The fundamental security posture. Agents, by default, deny any operation unless explicitly permitted by an ACL. This forces administrators to consciously grant access.
  • Granular ACLs/Roles: Controllers can be assigned roles (or ACLs) that grant highly specific permissions (ServiceElementView, ServiceElementUpdate, ServiceElementAdd, ServiceElementDelete, AgentCommandExecute) on precisely defined data model paths. This avoids broad "all-or-nothing" access.
    • Example from usp.txt (CHANGELOG.md for v1.4.0): "Updated Role Definition Section with clarifications to Role permissions applying to Supported and Instantiated Data model and the Secured Role as applying to 'secured' parameter in the path(s), with examples of both." This highlights continuous refinement towards more granular PoLP.
  • Data Model Attributes: The Writable, Addable, Deletable, Executable, and Secured attributes of data model elements directly enforce PoLP at the resource level. A parameter marked Read-only (i.e., Writable: false) cannot be changed, even if an ACL would theoretically permit a Set operation. This is a crucial device-side self-protection mechanism.
  • Controller Onboarding and Challenge Mechanisms: For devices in the field, Controllers might initially have an "UntrustedRole" (Device.LocalAgent.ControllerTrust.UntrustedRole). Highly sensitive operations (like gaining SecuredRole access) can be protected by "Challenges" (Device.LocalAgent.ControllerTrust.Challenge.{i}.), requiring physical interaction or verification (e.g., "Enter passphrase printed on bottom of device"). This ensures that broad privileges are not easily gained by remote, unverified entities (R-SEC.15, R-SEC.16, R-SEC.17 related to challenges).
  • Interface-Specific Policies: The ability to configure different access rules per MTP interface enables stronger PoLP. A local management interface might allow broader administrative access, while a wide-area network interface would be locked down to only essential, limited operations.
  • Ephemeral Permissions (Conceptual): In advanced scenarios, ACLs could be dynamically modified to grant temporary, just-in-time permissions for specific tasks, then automatically revoked, further enforcing PoLP.
  • Clear Error Reporting: When a permission is denied, the Agent sends a specific USP_ERROR (code 7006) which allows the Controller to understand why the operation failed and guide its users/applications to adhere to PoLP. This transparency aids debugging and policy refinement.

In summary, USP's permission system is built to provide a secure and flexible management framework, enabling fine-grained control over connected devices by combining explicit Controller-side policies with robust, attribute-aware enforcement on the Agent side, all while adhering to the principle of least privilege.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment