Aggiornamenti di sistema dinamici

Gli aggiornamenti di sistema dinamici (DSU) ti consentono di creare un'immagine di sistema Android che gli utenti possono scaricare da internet e provare senza il rischio di danneggiare l'immagine di sistema attuale. Questo documento descrive come supportare DSU.

Requisiti del kernel

Per i requisiti del kernel, consulta Implementare le partizioni dinamiche.

Inoltre, DSU si basa sulla funzionalità del kernel device-mapper-verity (dm-verity) per verificare l'immagine di sistema Android. Pertanto, devi attivare le seguenti configurazioni del kernel:

  • CONFIG_DM_VERITY=y
  • CONFIG_DM_VERITY_FEC=y

Requisiti delle partizioni

A partire da Android 11, DSU richiede che la partizione /data utilizzi il file system F2FS o ext4. F2FS offre prestazioni migliori ed è consigliato, ma la differenza dovrebbe essere insignificante.

Ecco alcuni esempi di quanto tempo impiega un aggiornamento di sistema dinamico con un dispositivo Pixel:

  • Utilizzo di F2FS:
    • 109 secondi, 8 GB utente, 867 MB sistema, tipo di file system: F2FS: encryption=aes-256-xts:aes-256-cts
    • 104 secondi, 8 GB utente, 867 MB sistema, tipo di file system: F2FS: encryption=ice
  • Utilizzo di ext4:
    • 135 secondi, 8 GB utente, 867 MB sistema, tipo di file system: ext4: encryption=aes-256-xts:aes-256-cts

Se la procedura richiede molto più tempo sulla tua piattaforma, puoi verificare se il flag di montaggio contiene un flag che esegue la scrittura "sync" oppure puoi specificare un flag "async" in modo esplicito per ottenere prestazioni migliori.

La partizione metadata (16 MB o più) è necessaria per archiviare i dati relativi alle immagini installate. Deve essere montata durante il montaggio della prima fase.

La partizione userdata deve utilizzare il file system F2FS o ext4. Quando utilizzi F2FS, includi tutte le patch correlate a F2FS disponibili nel kernel comune di Android.

DSU è stato sviluppato e testato con kernel/common 4.9. Per questa funzionalità è consigliabile utilizzare il kernel 4.9 e versioni successive.

Comportamento di HAL del fornitore

Weaver HAL

Il Weaver HAL fornisce un numero fisso di slot per l'archiviazione delle chiavi utente. DSU utilizza due slot di chiavi aggiuntivi. Se un OEM dispone di un Weaver HAL, deve avere slot sufficienti per un'immagine di sistema generica (GSI) e un'immagine host.

Gatekeeper HAL

Il Gatekeeper HAL deve supportare valori USER_ID di grandi dimensioni, perché GSI compensa gli UID con HAL di +1000000.

Avvio verificato

Se vuoi supportare l'avvio delle immagini GSI per sviluppatori in stato BLOCCATO senza disattivare l'Avvio verificato, includi le chiavi GSI per sviluppatori aggiungendo la seguente riga al file device/<device_name>/device.mk:

$(call inherit-product, $(SRC_TARGET_DIR)/product/developer_gsi_keys.mk)

Protezione rollback

Quando utilizzi DSU, l'immagine di sistema Android scaricata deve essere più recente dell'immagine di sistema attuale sul dispositivo. Questa operazione viene eseguita confrontando i livelli patch di sicurezza nel Android Verified Boot (AVB) descrizione della proprietà AVB di entrambe le immagini di sistema: Prop: com.android.build.system.security_patch -> '2019-04-05'.

Per i dispositivi che non utilizzano AVB, inserisci il livello patch di sicurezza dell'immagine di sistema attuale nella riga di comando del kernel o nella configurazione di avvio con il bootloader: androidboot.system.security_patch=2019-04-05.

Requisiti hardware

Quando avvii un'istanza DSU, vengono allocati due file temporanei:

  • Una partizione logica per archiviare GSI.img (1~1,5 GB)
  • Una partizione /data vuota da 8 GB come sandbox per l'esecuzione di GSI

Ti consigliamo di riservare almeno 10 GB di spazio libero prima di avviare un'istanza DSU. DSU supporta anche l'allocazione da una scheda SD. Quando è presente una scheda SD, ha la massima priorità per l'allocazione. Il supporto della scheda SD è fondamentale per i dispositivi a basso consumo che potrebbero non avere memoria interna sufficiente. Quando è presente una scheda SD, assicurati che non sia adottata. DSU non supporta le schede SD adottate.

Frontend disponibili

Puoi avviare DSU utilizzando adb, un'app OEM o il programma di caricamento DSU con un solo clic (in Android 11 o versioni successive).

Avviare DSU utilizzando adb

Per avviare DSU utilizzando adb, inserisci questi comandi:

$ simg2img out/target/product/.../system.img system.raw
$ gzip -c system.raw > system.raw.gz
$ adb push system.raw.gz /storage/emulated/0/Download
$ adb shell am start-activity \
-n com.android.dynsystem/com.android.dynsystem.VerificationActivity  \
-a android.os.image.action.START_INSTALL    \
-d file:///storage/emulated/0/Download/system.raw.gz  \
--el KEY_SYSTEM_SIZE $(du -b system.raw|cut -f1)  \
--el KEY_USERDATA_SIZE 8589934592

Avviare DSU utilizzando un'app

Il punto di ingresso principale per DSU è l'API android.os.image.DynamicSystemClient.java:

public class DynamicSystemClient {


...
...

     /**
     * Start installing DynamicSystem from URL with default userdata size.
     *
     * @param systemUrl A network URL or a file URL to system image.
     * @param systemSize size of system image.
     */
    public void start(String systemUrl, long systemSize) {
        start(systemUrl, systemSize, DEFAULT_USERDATA_SIZE);
    }

Devi raggruppare/preinstallare questa app sul dispositivo. Poiché DynamicSystemClient è un'API di sistema, non puoi creare l'app con l'API SDK standard e non puoi pubblicarla su Google Play. Lo scopo di questa app è:

  1. Recuperare un elenco di immagini e l'URL corrispondente con uno schema definito dal fornitore.
  2. Confrontare le immagini nell'elenco con il dispositivo e mostrare le immagini compatibili che l'utente può selezionare.

  3. Richiamare DynamicSystemClient.start nel seguente modo:

    DynamicSystemClient aot = new DynamicSystemClient(...)
   aot.start(
        ...URL of the selected image...,
        ...uncompressed size of the selected image...);

L'URL rimanda a un file immagine di sistema compresso con gzip e non sparse, che puoi creare con i seguenti comandi:

$ simg2img ${OUT}/system.img ${OUT}/system.raw
$ gzip ${OUT}/system.raw
$ ls ${OUT}/system.raw.gz

Il nome file deve avere il seguente formato:

<android version>.<lunch name>.<user defined title>.raw.gz

Esempi:

  • o.aosp_taimen-userdebug.2018dev.raw.gz
  • p.aosp_taimen-userdebug.2018dev.raw.gz

Programma di caricamento DSU con un solo clic

Android 11 introduce il programma di caricamento DSU con un solo clic, che è un frontend nelle impostazioni sviluppatore.

Avvio del caricatore DSU

Figura 1. Avvio del programma di caricamento DSU

Quando lo sviluppatore fa clic sul pulsante Programma di caricamento DSU, recupera un descrittore JSON DSU preconfigurato dal web e visualizza tutte le immagini applicabili nel menu mobile. Seleziona un'immagine per avviare l'installazione di DSU. L'avanzamento viene visualizzato nella barra delle notifiche.

Avanzamento dell&#39;installazione dell&#39;immagine DSU

Figura 2. Avanzamento dell'installazione dell'immagine DSU

Per impostazione predefinita, il programma di caricamento DSU carica un descrittore JSON che contiene le immagini GSI. Le sezioni seguenti mostrano come creare pacchetti DSU firmati dall'OEM e caricarli dal programma di caricamento DSU.

Flag funzionalità

La funzionalità DSU è disponibile sotto il flag funzionalità settings_dynamic_android. Prima di utilizzare DSU, assicurati che il flag funzionalità corrispondente sia attivato.

Attivazione del flag funzionalità.

Figura 3. Attivazione del flag funzionalità

L'interfaccia utente del flag funzionalità potrebbe non essere disponibile su un dispositivo che esegue una build utente. In questo caso, utilizza il comando adb:

$ adb shell setprop persist.sys.fflag.override.settings_dynamic_system 1

Immagini di sistema host del fornitore su GCE (facoltativo)

Una delle possibili posizioni di archiviazione per le immagini di sistema è il bucket Google Compute Engine (GCE). L'amministratore della release utilizza la console di archiviazione di GCP per aggiungere, eliminare o modificare l'immagine di sistema rilasciata.

Le immagini devono essere ad accesso pubblico, come mostrato di seguito:

Accesso pubblico in GCE

Figura 4. Accesso pubblico in GCE

La procedura per rendere pubblico un elemento è disponibile nella documentazione di Google Cloud.

DSU con più partizioni in un file ZIP

A partire da Android 11, DSU può avere più di una partizione. Ad esempio, può contenere un file product.img oltre a system.img. Quando il dispositivo si avvia, la prima fase init rileva le partizioni DSU installate e sostituisce temporaneamente la partizione sul dispositivo quando DSU installato è attivato. Il pacchetto DSU può contenere una partizione che non ha una partizione corrispondente sul dispositivo.

Processo DSU con più partizioni

Figura 5. Processo DSU con più partizioni

DSU firmato dall'OEM

Per assicurarti che tutte le immagini in esecuzione sul dispositivo siano autorizzate dal produttore del dispositivo, tutte le immagini all'interno di un pacchetto DSU devono essere firmate. Supponiamo, ad esempio, che esista un pacchetto DSU che contiene due immagini di partizione come di seguito:

dsu.zip {
    - system.img
    - product.img
}

Sia system.img sia product.img devono essere firmati dalla chiave OEM prima di essere inseriti nel file ZIP. La pratica comune è utilizzare un algoritmo asimmetrico, ad esempio RSA, in cui la chiave segreta viene utilizzata per firmare il pacchetto e la chiave pubblica viene utilizzata per verificarlo. Il ramdisk della prima fase deve includere la chiave pubblica di accoppiamento, ad esempio /avb/*.avbpubkey. Se il dispositivo ha già adottato AVB, la procedura di firma esistente sarà sufficiente. Le sezioni seguenti illustrano la procedura di firma ed evidenziano il posizionamento della chiave pubblica AVB utilizzata per verificare le immagini nel pacchetto DSU.

Descrittore JSON DSU

Il descrittore JSON DSU descrive i pacchetti DSU. Supporta due primitive. Innanzitutto, la primitiva include include descrittori JSON aggiuntivi o reindirizza il programma di caricamento DSU a una nuova posizione. Ad esempio:

{
    "include": ["https://.../gsi-release/gsi-src.json"]
}

In secondo luogo, la primitiva image viene utilizzata per descrivere i pacchetti DSU rilasciati. All'interno della primitiva immagine sono presenti diversi attributi:

  • Gli attributi name e details sono stringhe che vengono visualizzate nella finestra di dialogo per la selezione dell'utente.

  • Gli attributi cpu_api, vndk e os_version vengono utilizzati per i controlli di compatibilità, descritti nella sezione successiva.

  • L'attributo facoltativo pubkey descrive la chiave pubblica che si accoppia con la chiave segreta utilizzata per firmare il pacchetto DSU. Se specificato, il servizio DSU può verificare se il dispositivo dispone della chiave utilizzata per verificare il pacchetto DSU. In questo modo si evita l'installazione di un pacchetto DSU non riconosciuto, ad esempio l'installazione di un DSU firmato da OEM-A su un dispositivo prodotto da OEM-B.

  • L'attributo facoltativo tos rimanda a un file di testo che descrive i Termini di servizio per il pacchetto DSU corrispondente. Quando uno sviluppatore seleziona un pacchetto DSU con l'attributo Termini di servizio specificato, si apre la finestra di dialogo mostrata nella Figura 6, che chiede allo sviluppatore di accettare i Termini di servizio prima di installare il pacchetto DSU.

    Finestra di dialogo Termini di servizio

    Figura 6. Finestra di dialogo Termini di servizio

Per riferimento, ecco un descrittore JSON DSU per GSI:

{
   "images":[
      {
         "name":"GSI+GMS x86",
         "os_version":"10",
         "cpu_abi": "x86",
         "details":"exp-QP1A.190711.020.C4-5928301",
         "vndk":[
            27,
            28,
            29
         ],
         "pubkey":"",
         "tos": "https://dl.google.com/developers/android/gsi/gsi-tos.txt",
         "uri":"https://.../gsi/gsi_gms_x86-exp-QP1A.190711.020.C4-5928301.zip"
      },
      {
         "name":"GSI+GMS ARM64",
         "os_version":"10",
         "cpu_abi": "arm64-v8a",
         "details":"exp-QP1A.190711.020.C4-5928301",
         "vndk":[
            27,
            28,
            29
         ],
         "pubkey":"",
         "tos": "https://dl.google.com/developers/android/gsi/gsi-tos.txt",
         "uri":"https://.../gsi/gsi_gms_arm64-exp-QP1A.190711.020.C4-5928301.zip"
      },
      {
         "name":"GSI ARM64",
         "os_version":"10",
         "cpu_abi": "arm64-v8a",
         "details":"exp-QP1A.190711.020.C4-5928301",
         "vndk":[
            27,
            28,
            29
         ],
         "pubkey":"",
         "uri":"https://.../gsi/aosp_arm64-exp-QP1A.190711.020.C4-5928301.zip"
      },
      {
         "name":"GSI x86_64",
         "os_version":"10",
         "cpu_abi": "x86_64",
         "details":"exp-QP1A.190711.020.C4-5928301",
         "vndk":[
            27,
            28,
            29
         ],
         "pubkey":"",
         "uri":"https://.../gsi/aosp_x86_64-exp-QP1A.190711.020.C4-5928301.zip"
      }
   ]
}

Gestione della compatibilità

Diversi attributi vengono utilizzati per specificare la compatibilità tra un pacchetto DSU e il dispositivo locale:

  • cpu_api è una stringa che descrive l'architettura del dispositivo. Questo attributo è obbligatorio e viene confrontato con la proprietà di sistema ro.product.cpu.abi. I valori devono corrispondere esattamente.

  • os_version è un numero intero facoltativo che specifica una release di Android. Ad esempio, per Android 10, os_version è 10 e per Android 11, os_version è 11. Se questo attributo è specificato, deve essere maggiore o uguale alla proprietà di sistema ro.system.build.version.release. Questo controllo viene utilizzato per impedire l'avvio di un'immagine GSI di Android 10 su un dispositivo fornitore Android 11, che al momento non è supportato. È consentito l'avvio di un'immagine GSI di Android 11 su un dispositivo Android 10.

  • vndk è un array facoltativo che specifica tutti i VNDK inclusi nel pacchetto DSU. Se specificato, il programma di caricamento DSU verifica se il numero estratto dalla proprietà di sistema ro.vndk.version è incluso.

Revocare le chiavi DSU per la sicurezza

Nel caso estremamente raro in cui la coppia di chiavi RSA utilizzata per firmare le immagini DSU venga compromessa, il ramdisk deve essere aggiornato il prima possibile per rimuovere la chiave compromessa. Oltre ad aggiornare la partizione di avvio, puoi bloccare le chiavi compromesse utilizzando un elenco di revoca delle chiavi DSU (lista nera delle chiavi) da un URL HTTPS.

L'elenco di revoca delle chiavi DSU contiene un elenco di chiavi pubbliche AVB revocate. Durante l'installazione di DSU, le chiavi pubbliche all'interno delle immagini DSU vengono convalidate con l'elenco di revoca. Se viene rilevato che le immagini contengono una chiave pubblica revocata, la procedura di installazione di DSU si interrompe.

L'URL dell'elenco di revoca delle chiavi deve essere un URL HTTPS per garantire la sicurezza ed è specificato in una stringa di risorse:

frameworks/base/packages/DynamicSystemInstallationService/res/values/strings.xml@key_revocation_list_url

Il valore della stringa è https://dl.google.com/developers/android/gsi/gsi-keyblacklist.json, che è un elenco di revoca per le chiavi GSI rilasciate da Google. Questa stringa di risorse può essere sovrapposta e personalizzata, in modo che gli OEM che adottano la funzionalità DSU possano fornire e gestire la propria lista nera di chiavi. In questo modo, l'OEM può bloccare determinate chiavi pubbliche senza aggiornare l'immagine del ramdisk del dispositivo.

Il formato dell'elenco di revoca è:

{
   "entries":[
      {
         "public_key":"bf14e439d1acf231095c4109f94f00fc473148e6",
         "status":"REVOKED",
         "reason":"Key revocation test key"
      },
      {
         "public_key":"d199b2f29f3dc224cca778a7544ea89470cbef46",
         "status":"REVOKED",
         "reason":"Key revocation test key"
      }
   ]
}
  • public_key è il digest SHA-1 della chiave revocata, nel formato descritto nella sezione Generare la chiave pubblica AVB.
  • status indica lo stato di revoca della chiave. Al momento, l'unico valore supportato è REVOKED.
  • reason è una stringa facoltativa che descrive il motivo della revoca.

Procedure DSU

Questa sezione descrive come eseguire diverse procedure di configurazione di DSU.

Generare una nuova coppia di chiavi

Utilizza il comando openssl per generare una coppia di chiavi privata/pubblica RSA in formato .pem (ad esempio, con una dimensione di 2048 bit):

$ openssl genrsa -out oem_cert_pri.pem 2048
$ openssl rsa -in oem_cert_pri.pem -pubout -out oem_cert_pub.pem

La chiave privata potrebbe non essere accessibile e viene conservata solo in un modulo di sicurezza hardware (HSM). In questo caso, dopo la generazione della chiave potrebbe essere disponibile un certificato di chiave pubblica x509. Per istruzioni su come generare la chiave pubblica AVB da un certificato x509, consulta la sezione Aggiungere la chiave pubblica di accoppiamento al ramdisk.

Per convertire un certificato x509 in formato PEM:

$ openssl x509 -pubkey -noout -in oem_cert_pub.x509.pem > oem_cert_pub.pem

Salta questo passaggio se il certificato è già un file PEM.

Aggiungere la chiave pubblica di accoppiamento al ramdisk

Il file oem_cert.avbpubkey deve essere inserito in /avb/*.avbpubkey per verificare il pacchetto DSU firmato. Innanzitutto, converti la chiave pubblica in formato PEM in formato chiave pubblica AVB:

$ avbtool extract_public_key --key oem_cert_pub.pem --output oem_cert.avbpubkey

Quindi includi la chiave pubblica nel ramdisk della prima fase seguendo questi passaggi.

  1. Aggiungi un modulo precompilato per copiare avbpubkey. Ad esempio, aggiungi device/<company>/<board>/oem_cert.avbpubkey e device/<company>/<board>/avb/Android.mk con contenuti simili a questi:

    include $(CLEAR_VARS)

LOCAL_MODULE := oem_cert.avbpubkey
LOCAL_MODULE_CLASS := ETC
LOCAL_SRC_FILES := $(LOCAL_MODULE)
ifeq ($(BOARD_USES_RECOVERY_AS_BOOT),true)
LOCAL_MODULE_PATH := $(TARGET_RECOVERY_ROOT_OUT)/first_stage_ramdisk/avb
else
LOCAL_MODULE_PATH := $(TARGET_RAMDISK_OUT)/avb
endif

include $(BUILD_PREBUILT)

  2. Fai in modo che il target droidcore dipenda da oem_cert.avbpubkey aggiunto:

    droidcore: oem_cert.avbpubkey

Generare l'attributo della chiave pubblica AVB nel descrittore JSON

Il file oem_cert.avbpubkey è in formato binario della chiave pubblica AVB. Utilizza SHA-1 per renderlo leggibile prima di inserirlo nel descrittore JSON:

$ sha1sum oem_cert.avbpubkey | cut -f1 -d ' '
3e62f2be9d9d813ef5........866ac72a51fd20

Questo sarà il contenuto dell'attributo pubkey del descrittore JSON.

   "images":[
      {
         ...
         "pubkey":"3e62f2be9d9d813ef5........866ac72a51fd20",
         ...
      },

Firmare un pacchetto DSU

Utilizza uno di questi metodi per firmare un pacchetto DSU:

  • Metodo 1: riutilizza l'artefatto creato dalla procedura di firma AVB originale per creare un pacchetto DSU. Un approccio alternativo consiste nell'estrarre le immagini già firmate dal pacchetto di release e utilizzare le immagini estratte per creare direttamente il file ZIP.

  • Metodo 2: utilizza i seguenti comandi per firmare le partizioni DSU se la chiave privata è disponibile. Ogni img all'interno di un pacchetto DSU (il file ZIP) viene firmato separatamente:

    $ key_len=$(openssl rsa -in oem_cert_pri.pem -text | grep Private-Key | sed -e 's/.*(\(.*\) bit.*/\1/')
$ for partition in system product; do
    avbtool add_hashtree_footer \
        --image ${OUT}/${partition}.img \
        --partition_name ${partition} \
        --algorithm SHA256_RSA${key_len} \
        --key oem_cert_pri.pem
done

Per ulteriori informazioni sull'aggiunta di add_hashtree_footer utilizzando avbtool, consulta Utilizzare avbtool.

Verificare localmente il pacchetto DSU

Ti consigliamo di verificare tutte le immagini locali rispetto alla chiave pubblica di accoppiamento con questi comandi:


for partition in system product; do
    avbtool verify_image --image ${OUT}/${partition}.img  --key oem_cert_pub.pem
done

L'output previsto è simile al seguente:

Verifying image dsu/system.img using key at oem_cert_pub.pem
vbmeta: Successfully verified footer and SHA256_RSA2048 vbmeta struct in dsu/system.img
: Successfully verified sha1 hashtree of dsu/system.img for image of 898494464 bytes

Verifying image dsu/product.img using key at oem_cert_pub.pem
vbmeta: Successfully verified footer and SHA256_RSA2048 vbmeta struct in dsu/product.img
: Successfully verified sha1 hashtree of dsu/product.img for image of 905830400 bytes

Creare un pacchetto DSU

L'esempio seguente crea un pacchetto DSU che contiene un file system.img e un file product.img:

dsu.zip {
    - system.img
    - product.img
}

Dopo aver firmato entrambe le immagini, utilizza il seguente comando per creare il file ZIP:

$ mkdir -p dsu
$ cp ${OUT}/system.img dsu
$ cp ${OUT}/product.img dsu
$ cd dsu && zip ../dsu.zip *.img && cd -

Personalizzare DSU con un solo clic

Per impostazione predefinita, il programma di caricamento DSU rimanda a un metadati delle immagini GSI che è https://...google.com/.../gsi-src.json.

Gli OEM possono sovrascrivere l'elenco definendo la proprietà persist.sys.fflag.override.settings_dynamic_system.list che rimanda al proprio descrittore JSON. Ad esempio, un OEM può fornire metadati JSON che includono GSI e immagini proprietarie OEM come questa:

{
    "include": ["https://dl.google.com/.../gsi-src.JSON"]
    "images":[
      {
         "name":"OEM image",
         "os_version":"10",
         "cpu_abi": "arm64-v8a",
         "details":"...",
         "vndk":[
            27,
            28,
            29
         ],
         "spl":"...",
         "pubkey":"",
         "uri":"https://.../....zip"
      },

}

È possibile che un OEM concateni i metadati DSU pubblicati come mostrato nella Figura 7.

Concatenamento dei metadati DSU pubblicati

Figura 7. Concatenamento dei metadati DSU pubblicati