Debugging Restriction Controller 集成指南

请按以下说明集成 AAOS Debugging Restriction Controller (DRC)。

图 1. DRC 应用示例

架构

DRC 架构如下图所示。红线框住的组件（Token Issuer 和 Debutting Restriction Controller）随附了您可以自定义的参考实现。

图 2. DRC 架构

什么是 DRC？

车机包含 DRC 应用（请参阅 packages/apps/Car/DebuggingRestrictionController 中的参考实现）。参考应用包含以下逻辑：接收来自 Token Issuer 的访问令牌，验证此令牌，然后按照此令牌中的规定应用调试限制更改。此逻辑包含汽车端的基本用户体验元素。

什么是 Token Issuer？

这是一项颁发经过加密签名的访问令牌的网络服务（请参阅 packages/apps/Car/DebuggingRestrictionController/server 中的参考实现）。参考网络服务是一项可部署的 Firebase Cloud Functions 函数（如需了解详情，请参阅 Cloud Functions for Firebase）。

前提条件

在部署参考实现之前，请务必完成以下任务。

准备用于对访问令牌进行签名的证书

Token Issuer 会生成 JSON Web Signature (JWS) 作为访问令牌。为了实现最佳的兼容性，参考 Issuer 仅支持 RS256 算法（采用 SHA256 的 RSA 签名）。为了方便实现密钥轮替，请使用证书链（而不是单个证书）对访问令牌进行签名。典型的证书链应包含一个根 CA 证书、一个中间 CA 证书和一个终端实体证书。

对 JWS 令牌进行签名的终端实体证书与标准 TLS 证书没有区别。您可以从公共 CA（例如 DigiCert）购买证书，也可以使用自签名的根 CA 证书或硬件安全模块来维护您自己的证书链。终端实体证书应该是具有主题备用名称 (SAN) 扩展项的 X509v3 证书。SAN 扩展项包含 Token Issuer 的标识符（例如，主机名）。最后，RSA 证书应该优先于 EC 证书，因为 Token Issuer 仅支持 RS256。

Google 提供了一个 Shell 脚本，用于在 packages/apps/Car/DebuggingRestrictionController/server/genkey.sh 中生成自签名证书。

设置 Firebase

参考 Token Issuer 使用 Firebase Authentication 和 Firebase Cloud Functions 函数。

如需设置 Firebase 帐号，请执行以下操作：

如需创建 Firebase 项目，请参阅将 Firebase 添加至您的 Android 项目。
如需启用某些 Firebase 身份验证器，请参阅如何开始使用 Firebase Authentication？。
如需添加空的 Firebase Cloud Functions 函数，请参阅使用入门。
请安装 Node.js、NPM 和 Firebase Tools 以编译和部署 Token Issuer（如果您尚未这样做）。
注意：创建 Firebase 项目后，系统会提示您下载名为 google-services.json 的配置文件。此文件不包含敏感信息，并且稍后将供参考 DRC 应用和 Token Issuer 使用。

集成 DRC 应用

参考 DRC 应用位于 packages/apps/Car/DebuggingRestrictionController 中。此应用可在 AOSP 中使用 Soong 以捆绑的方式进行构建，也可以使用 Gradle 以非捆绑的方式进行构建。

捆绑 build

如需构建捆绑应用，请执行以下操作：

将 applicationId、projectId 和 apiKey 从 google-services.json 复制到 packages/apps/Car/DebuggingRestrictionController/soong/FirebaseApplication.java。这样做可让 DRC 应用正确连接到 Firebase。
在 packages/apps/Car/DebuggingRestrictionController/soong/BuildConfig.java 中更新以下常量：
- TOKEN_USES_SELF_SIGNED_CA 表示是否使用了自签名根 CA 证书。启用该常量后，DCR 应用仅信任 ROOT_CA_CERT 中指定的 PEM 编码的根 CA 证书。
- TOKEN_ISSUER_API_NAME 是 Firebase Cloud Functions 函数的名称，应与您之前在 Firebase 控制台中创建的 Cloud Functions 函数相匹配。
- TOKEN_ISSUER_HOSTNAME 应与对访问令牌进行签名的终端实体证书中的主题备用名称相匹配。
- DRC_TEST_EMAIL 和 DRC_TEST_PASSWORD 是可选测试帐号的凭据，如果您已启用电子邮件地址/密码登录功能，则可以在 Firebase 中预先配置这些凭据。这些凭据仅用于插桩测试。

应用现已配置为使用您的 Firebase 帐号和相关证书。在 Android 9 及更高版本中，您必须设置特许权限许可名单。此许可名单必须至少包含 android.permission.MANAGE_USERS。例如：

<permissions>
  <privapp-permissions package="com.android.car.debuggingrestrictioncontroller">
    <permission name="android.permission.INTERNET"/>
    <permission name="android.permission.MANAGE_USERS"/>
  </privapp-permissions>
</permissions>

未捆绑 build

未捆绑的 DRC build 会使用 Gradle 编译应用。

如需创建未捆绑 build，请执行以下操作：

确认您已安装 Android SDK。
在应用的根目录中创建名为 local.properties 的文本文件。
设置 Android SDK 的位置：
```
 sdk.dir=path/to/android/sdk
```
如需设置 Firebase，请将 google-services.json 复制到 packages/apps/Car/DebuggingRestrictionController/app。Gradle 会解析此文件，并自动完成其余设置。
定义环境变量。与捆绑 build 一样，您必须指定以下各项：
- $TOKEN_USES_SELF_SIGNED_CA：true 还是 false；
- $ROOT_CA_CERT：指向 PEM 编码的根 CA 证书的路径；
- $TOKEN_ISSUER_API_NAME：Firebase Cloud Functions 函数的名称；
- $TOKEN_ISSUER_HOST_NAME：证书中的 SAN；
- $DRC_TEST_EMAIL 和 $DRC_TEST_EMAIL：测试帐号的凭据（仅调试 build）。
如需使用 Gradle 构建应用，请运行如下命令：
```
$ ./gradlew build
```
注意：未捆绑的 DRC 应用必须使用平台证书进行签名，因为它需要特许权限 MANAGE_USERS。出于同样的原因，您仍需要使用特许权限许可名单。

集成 Token Issuer

参考 Token Issuer 是使用 Node.js 实现的 Firebase Cloud Functions 函数。此函数只能由通过身份验证的用户来调用。在部署应用之前，您必须设置用于对 JWS 令牌进行签名的私钥和证书。

使用以下内容填充 JSON 文件：

{
    "key": "---BEGIN PRIVATE KEY---\nRSA_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
    "certificates.0": "-----BEGIN CERTIFICATE-----\nTOKEN_SIGNING_CERT\n-----END CERTIFICATE-----\n",
    "certificates.1": "-----BEGIN CERTIFICATE-----\nINTERMEDIATE_CA_CERT\n-----END CERTIFICATE-----\n",
    "certificates.2": "-----BEGIN CERTIFICATE-----\nROOT_CA_CERT\n-----END CERTIFICATE-----\n",
    "expiration": "30m",
    "issuer": "Debugging Access Token Issuer",
    "audience": "IHU"
}

证书的顺序是终端实体证书在最前面，根 CA 证书在最后面。过期时间可自定义，如果颁发的令牌需要一段时间才会被 DRC 应用接收并使用，则可以将过期时间设置得长一些。不支持令牌撤消。

将配置上传到 Firebase：

$ firebase functions:config:set api_config="$(cat YOUR_CONFIG.json)"

部署 Firebase Cloud Functions 函数：

$ firebase deploy --only functions

如需管理和监控 Token Issuer，请参阅管理函数部署和运行时选项。

设置默认限制

默认限制可在首次启动之前应用。为此，请使用静态资源叠加层，以便替换 Android 框架中的默认值。可为不同类型的用户分别应用各项限制。如需了解不同类型的用户，请参阅多用户支持。

无头系统用户的默认限制可以使用 frameworks/base/core/res/res/values/config.xml 中的 config_defaultFirstUserRestrictions 字符串数组进行配置。设置此限制会自动停用 Android 调试桥 (ADB)，直到此限制移除为止，例如：

<string-array translatable="false" name="config_defaultFirstUserRestrictions">
  <item>no_debugging_features</item>
</string-array>

常规用户（例如司机和乘客）和访客的默认设置可以在 frameworks/base/core/res/res/xml/config_user_types.xml 中进行配置。您可以叠加这些字符串，以便针对每种类型的用户分别设置默认限制，例如：

<user-types>
  <full-type name="android.os.usertype.full.SECONDARY" >
    <default-restrictions no_debugging_features="true"/>
  </full-type>
  <full-type name="android.os.usertype.full.GUEST" >
    <default-restrictions no_debugging_features="true"/>
  </full-type>
</user-types>