The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)
Copyright (c) 2023 General Motors GTO LLC Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION SPDX-FileCopyrightText: 2023 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0
The following specification shall elaborate on the policies governing access to specific topics,methods, and services used by uProtocol, they are: * Code-based Permissions (CAPs): Based on identity of the code requesting such access
-
Token-based Access Permissions (TAP): Based on identity of the person or device (typically represented by a system account and based on the information in said account) requesting such access
Throughout this document we will use the Permissions Terms below:
| Term | Description |
|---|---|
Permission Artifact (uPA) |
A resource or service that is accessible via uProtocol identified by a URI. |
Permission Level (uPL) |
An integer value of 0 to N, the latter being the most permissive, reflecting the expected level of trust associated with the code claiming permissions. Used by Code-Based Access Permissions (CAPs). |
Access to each uService, as well as their methods or topics, all collectively referred to as uPerm artifacts (uPA), is governed by permissions granted to client entities (applications and services) using the service.
Permissions for sensitive topics are explicitly requested by client entities in their platform specific deployment manifests (ex. Android package manifests), the requests represented by customary uProtocol URIs. A CAP is applicable to every uPA to which the corresponding URI (including generic ones) can be resolved.
|
Note
|
Definition of sensitive topic vs non-sensitive topic along with uPLs are not covered in this specification and are platform/ecosystem specific. |
uPLs are also considered during the client entity’s installation, which will fail if for any of the uPAs declared by the entity its level is less that that of the entity itself. Permission claims not resolved to any specific uPA are logged, but otherwise ignored by the uPlatforms.
For pre-installed client entities only runtime enforcement is applied.
|
Important
|
The runtime enforcement of CAPs is uPlatform specific and not covered by this specifications. |
CAP assumes that the uTransport implementation provides a means to determine client’s uPL.
|
Note
|
The importance of permissions will vary between uPlatforms. The key initially will be a robust solution for CAPs covering clients residing in-vehicle devices (i.e. Android & Linux uPlatforms). We do not expect CAPs to be applicable to less dynamic and more controlled environments such as mechatronic, Mobile or Cloud uPlatforms. |
While inspired by Android’s permission, CAPs under the current proposal are different in several aspects. The differences include:
-
Android permissions are always explicitly defined. uPerms are associated with uPA Uris, thus derived implicitly from service definitions
-
In Android permissions use declarations are specific to a particular resource. uProtocol clients declare their claimed CAPs whose URIs can be generic, thus describing multiple uPAs at once
-
Android does not support explicit permission levels. Its concept of meta-attributed (normal, dangerous, signature etc) is also somewhat hierarchical, so can be considered as being similar to that of levels to some extent. But it is also much more elaborate, reflecting the challenges and complexities of a completely open, un-curated programmatic ecosystem
-
In Android application of permissions can be affected by specifics of client’s and server’s signatures. No such consideration is proposed for uPerms at this point in time
Services declare their uPLs as google.protobuf CustomOptions within their protos. The options are declared in uprotocol_options.proto and their purpose is defined in uProtocol options for CAPs below.
-
uPL value MUST be an integer, 0 to N, where N is the most permissive level. The default value is 0.
| google.protobuf Extension | Description |
|---|---|
|
uPL for the service |
|
Service’s method uPL |
|
Service’s topic uPL |
|
Note
|
MUST assumes the most permissive level, N, if the the declarations above are missing for the service, method, or topic in the service protos. |
Claimed level of a uE is also handled by uTransport. uPlatforms will determine the claimed level of the caller in a secure manner, and this will also be done differently depending on the uTransport implementation.
When the calling uE permission level needs to be carried across different uTransport implementations, or across hops (i.e. across dispatchers such as the uBus), the callers permission level is placed in uAttributes permission_level.
uEs that do not have proto defintions (i.e. applications), claimed uPLs using a uPlatform specific manor like Android’s manifest file. See Example using Android for an example.
For Android we will use the AOSP-standard manifest extension mechanism of <meta-data> to describe the permission level. We’ll use the name of uprotocol.permissionLevel and the value of the actual level, 0 to 5. The default value of 5 will be assigned implicitly when uprotocol.entity.permissionLevel` is not declared.
Another metadata element with the name of uprotocol.entity.permissions will explicitly list (claim) all used uPAs with levels equal or less than 2 (explicit claim threshold), to improve visibility of sensitive claims. The resource attribute of this element points to an array of strings listing the URIs of the uPAs.
The entities enforcing the permissions (uBus, uSub and uTwin) will allow access to a uPA if:
The client’s claimed level is equal or less than that of the uPA;
For uPAs of levels equal or less than explicit claim threshold, URI of that uPA is present in the array referred by uprotocol.entity.permissions element.
An example of a manifest fragment for an app accessing the BodyAccess service could look as follows:
<application android:label="@string/app_name" ...>
<meta-data
android:name="uprotocol.entity.permissionLevel"
android:value="1" />
<meta-data
android:name="uprotocol.entity.permissions"
android:resource="@array/uPerms"
</application>In the string resources directory of the APK we may then have a file with the following content:
<resources>
<string-array name="uPerm">
<item>/body.access/1/rpc.ExecuteSunroofCommand</item>
<item>/body.access/1/rpc.ExecuteWindowCommand</item>
</string-array>
</resources>Such entries in the manifest will allow the client access to any topics of the BodyAccess service and two methods explicitly specified, as they are both level 1, thus requiring an explicit claim.
Token-based access permissions (TAPs) are policies governing access to specific methods, topics, and services, based on identity of the person or vehicle (domain), typically represented by a system account and based on the information in said account. TAP is generally more restrictive than CAPs as the scope of TAP is larger (user/domain vs single uE level).
Implementations of TAP are generally platform/vendor specific, as such the following is not specified:
-
Token Format: How the token is structured
-
Issuer & Token Procurement: Who issues tokens and how they are shared with the user/domain/device
-
Verification: How the platform (and/or services) verifies the validity of said token (i.e. signature verification, etc…)
Scope is the list of artifacts that the caller (who has the token) are allowed to access. The scope is a list of uPA URIs.
Tokens are passed by the called to the transport (and then carried throughout the network) by populating the token uAttributes header field.