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 AuthenticationFirebase Cloud Functions 函数

如需设置 Firebase 帐号,请执行以下操作:

  1. 如需创建 Firebase 项目,请参阅将 Firebase 添加至您的 Android 项目
  2. 如需启用某些 Firebase 身份验证器,请参阅如何开始使用 Firebase Authentication?
  3. 如需添加空的 Firebase Cloud Functions 函数,请参阅使用入门
  4. 请安装 Node.js、NPM 和 Firebase Tools 以编译和部署 Token Issuer(如果您尚未这样做)。

集成 DRC 应用

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

捆绑 build

如需构建捆绑应用,请执行以下操作:

  1. applicationIdprojectIdapiKeygoogle-services.json 复制到 packages/apps/Car/DebuggingRestrictionController/soong/FirebaseApplication.java。 这样做可让 DRC 应用正确连接到 Firebase。
  2. 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_EMAILDRC_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,请执行以下操作:

  1. 确认您已安装 Android SDK。
  2. 在应用的根目录中创建名为 local.properties 的文本文件。
  3. 设置 Android SDK 的位置:
     sdk.dir=path/to/android/sdk
    
  4. 如需设置 Firebase,请将 google-services.json 复制到 packages/apps/Car/DebuggingRestrictionController/app。Gradle 会解析此文件,并自动完成其余设置。
  5. 定义环境变量。与捆绑 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)。
  6. 如需使用 Gradle 构建应用,请运行如下命令:
    $ ./gradlew build
    

集成 Token Issuer

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

  1. 使用以下内容填充 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 应用接收并使用,则可以将过期时间设置得长一些。不支持令牌撤消。

  2. 将配置上传到 Firebase:
  3. $ firebase functions:config:set api_config="$(cat YOUR_CONFIG.json)"
    
  4. 部署 Firebase Cloud Functions 函数:
  5. $ firebase deploy --only functions
    
  6. 如需管理和监控 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>