Integrationsleitfaden für den Einschränkungs-Controller zur Fehlerbehebung

Folgen Sie der Anleitung auf dieser Seite, um den AAOS Debugging Restriction Controller (DRC) zu integrieren.

Abbildung 1: Beispiel für eine DRC-App

Architektur

Die DRC-Architektur ist in Abbildung 2 dargestellt. Für die rot umrandeten Komponenten (Tokenaussteller und DRC) gibt es Referenzimplementierungen, die Sie anpassen können.

Abbildung 2: DRC-Architektur.

Was ist die DRC?

Die Auto-Headunit enthält die DRC-App (siehe Referenzimplementierung in packages/apps/Car/DebuggingRestrictionController). Die Referenz-App enthält die Logik zum Empfangen eines Zugriffstokens vom Tokenaussteller, zum Validieren des Tokens und zum Anwenden von Änderungen an den Einschränkungen für die Fehlerbehebung, wie im Token angegeben. Die Logik umfasst grundlegende UX-Elemente auf der Fahrzeugseite.

Was ist der Tokenaussteller?

Dies ist ein Webdienst, der kryptografisch signierte Zugriffstokens ausstellt (siehe Referenzimplementierung in packages/apps/Car/DebuggingRestrictionController/server). Der Referenz-Webdienst ist eine implementierbare Firebase-Cloud-Funktion. Weitere Informationen finden Sie unter Cloud Functions for Firebase.

Voraussetzungen

Bevor Sie eine Referenzimplementierung bereitstellen, müssen Sie die folgenden Aufgaben ausführen.

Zertifikate für die Signatur von Zugriffstokens vorbereiten

Der Tokenaussteller generiert JSON Web Signatures (JWS) als Zugriffstokens. Für optimale Kompatibilität unterstützt der Referenzaussteller nur den RS256-Algorithmus (RSA-Signaturen mit SHA256). Verwenden Sie zum Erleichtern der Schlüsselrotation eine Zertifikatskette anstelle eines einzelnen Zertifikats, um Zugriffstokens zu signieren. Eine typische Zertifikatskette sollte aus einem Stammzertifikat der Zertifizierungsstelle, einem Zwischenzertifikat der Zertifizierungsstelle und einem Endentitätszertifikat bestehen.

Das Zertifikat der Endentität, das die JWS-Tokens signiert, unterscheidet sich nicht von einem Standard-TLS-Zertifikat. Sie können entweder ein Zertifikat von öffentlichen Zertifizierungsstellen wie DigiCert erwerben oder Ihre eigene Zertifikatskette mit selbst signierten Stamm-CA-Zertifikaten oder Hardware Security Modules verwalten. Das Endentitätszertifikat muss ein X509v3-Zertifikat mit der Erweiterung „Subject Alternative Name“ (SAN) sein. Die SAN-Erweiterung enthält eine Kennung (z. B. Hostname) des Tokenausstellers. Außerdem sollten RSA-Zertifikate EC-Zertifikaten vorgezogen werden, da der Tokenaussteller nur RS256 unterstützt.

Google stellt ein Shell-Script zum Generieren selbst signierter Zertifikate in packages/apps/Car/DebuggingRestrictionController/server/genkey.sh bereit.

Firebase einrichten

Der Aussteller des Referenztokens verwendet Firebase Authentication und Firebase Cloud Function.

So richten Sie Ihr Firebase-Konto ein:

  1. Eine Anleitung zum Erstellen eines Firebase-Projekts finden Sie unter Ihrem Android-Projekt Firebase hinzufügen.
  2. Informationen zum Aktivieren einiger Firebase-Authentifikatoren finden Sie unter Einstieg in Firebase Authentication.
  3. Informationen zum Hinzufügen einer leeren Firebase-Cloud-Funktion finden Sie unter Einstieg.
  4. Installieren Sie Node.js, NPM und Firebase-Tools, um den Tokenaussteller zu kompilieren und bereitzustellen, falls noch nicht geschehen.

DRC-App einbinden

Die Referenz-DRC-App befindet sich unter packages/apps/Car/DebuggingRestrictionController. Die App kann mit Soong in AOSP als Paket oder mit Gradle ohne Paket erstellt werden.

Gebündelte Builds

So erstellen Sie eine App-Bündelung:

  1. Kopieren Sie applicationId, projectId und apiKey aus google-services.json in packages/apps/Car/DebuggingRestrictionController/soong/FirebaseApplication.java. Dadurch kann die DRC-App eine korrekte Verbindung zu Firebase herstellen.
  2. Aktualisieren Sie diese Konstanten in packages/apps/Car/DebuggingRestrictionController/soong/BuildConfig.java:
    • TOKEN_USES_SELF_SIGNED_CA gibt an, ob selbst signierte Stamm-CA-Zertifikate verwendet werden. Wenn diese Option aktiviert ist, vertraut die DRC-App nur dem in ROOT_CA_CERT angegebenen PEM-codierten Stamm-Zertifizierungsstellenzertifikat.
    • TOKEN_ISSUER_API_NAME ist der Name der Firebase-Cloud-Funktion und sollte mit der Cloud-Funktion übereinstimmen, die Sie zuvor in der Firebase Console erstellt haben.
    • TOKEN_ISSUER_HOSTNAME muss mit dem alternativen Antragstellernamen im Zertifikat der Endentität übereinstimmen, mit dem die Zugriffstokens signiert werden.
    • DRC_TEST_EMAIL und DRC_TEST_PASSWORD sind Anmeldedaten für ein optionales Testkonto, das in Firebase vorab bereitgestellt werden kann, wenn Sie die Anmeldung per E-Mail/Passwort aktiviert haben. Sie werden nur für instrumentierte Tests verwendet.

Die App ist jetzt für die Verwendung Ihres Firebase-Kontos und Ihrer Zertifikate konfiguriert. Unter Android 9 und höher müssen Sie eine Zulassungsliste für Berechtigungen mit erhöhten Berechtigungen einrichten. Die Zulassungsliste muss mindestens android.permission.MANAGE_USERS Elemente enthalten. Beispiel:

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

Unverpackter Build

Bei nicht gebündelten DRC-Builds wird die App mit Gradle kompiliert.

So erstellen Sie einen nicht gebündelten Build:

  1. Prüfen Sie, ob das Android SDK installiert ist.
  2. Erstellen Sie im Stammverzeichnis der App eine Textdatei mit dem Namen local.properties.
  3. Legen Sie den Speicherort des Android SDK fest: 
     sdk.dir=path/to/android/sdk
  4. Kopieren Sie google-services.json in packages/apps/Car/DebuggingRestrictionController/app, um Firebase einzurichten. Gradle analysiert die Datei und richtet den Rest automatisch ein.
  5. Definieren Sie die Umgebungsvariablen. Wie bei gebündelten Builds müssen Sie Folgendes angeben:
    • $TOKEN_USES_SELF_SIGNED_CA: „wahr“ oder „falsch“;
    • $ROOT_CA_CERT: Pfad zum PEM-codierten Stamm-CA-Zertifikat
    • $TOKEN_ISSUER_API_NAME: Name der Firebase-Cloud-Funktion
    • $TOKEN_ISSUER_HOST_NAME: SAN im Zertifikat;
    • $DRC_TEST_EMAIL und $DRC_TEST_EMAIL: Anmeldedaten für ein Testkonto, nur für Debug-Builds.
  6. Führen Sie zum Erstellen der App mit Gradle einen Befehl wie diesen aus: 
    $ ./gradlew build

Tokenaussteller einbinden

Der Aussteller des Referenztokens ist eine Firebase-Cloud-Funktion, die in Node.js implementiert ist. Die Funktion kann nur von einem authentifizierten Nutzer aufgerufen werden. Bevor Sie die App bereitstellen, müssen Sie den privaten Schlüssel und die Zertifikate einrichten, die zum Signieren der JWS-Tokens verwendet werden.

  1. Fülle eine JSON-Datei mit folgendem Inhalt: 
    {
    "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"
}

    Die Zertifikate werden in der Reihenfolge ausgegeben, in der sie erstellt wurden, also zuerst das Zertifikat der Endentität und zuletzt das Zertifikat der Stammzertifizierungsstelle. Die Gültigkeitsdauer ist anpassbar und kann auf eine längere Dauer festgelegt werden, wenn es einige Zeit dauert, bis ein ausgestelltes Token von einer DRC-App empfangen und verwendet werden kann. Der Widerruf von Tokens wird nicht unterstützt.

  2. Laden Sie die Konfiguration in Firebase hoch:
    3. $ firebase functions:config:set api_config="$(cat YOUR_CONFIG.json)"
  3. Stellen Sie die Firebase-Cloud-Funktion bereit:
    4. $ firebase deploy --only functions
  4. Informationen zum Verwalten und Überwachen des Tokenausstellers finden Sie unter Bereitstellungs- und Laufzeitoptionen für Funktionen verwalten.

Standardeinschränkungen festlegen

Standardeinschränkungen können vor dem ersten Start angewendet werden. Verwenden Sie dazu statische Ressourcen-Overlays, um die Standardeinstellungen im Android-Framework zu überschreiben. Einschränkungen können für verschiedene Nutzertypen gelten. Weitere Informationen zu den verschiedenen Nutzertypen finden Sie unter Support für mehrere Nutzer.

Die Standardeinschränkung für den Headless-Systemnutzer kann mit dem config_defaultFirstUserRestrictions-String-Array in frameworks/base/core/res/res/values/config.xml konfiguriert werden. Wenn Sie diese Einschränkung festlegen, wird die Android Debug Bridge (ADB) automatisch deaktiviert, bis die Einschränkung aufgehoben wird. Beispiele:

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

Die Standardeinschränkungen für normale Nutzer (z. B. Fahrer und Mitfahrer) und Gäste können in frameworks/base/core/res/res/xml/config_user_types.xml konfiguriert werden. Sie können diese Strings überlagern, um die Standardeinschränkungen für die einzelnen Nutzertypen festzulegen, z. B.:

<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>