Esquema de firma de APK v4

Android 11 admite un esquema de firma compatible con la transmisión con el esquema de firma de APK v4. La firma v4 se basa en el árbol hash de Merkle que se calcula en todos los bytes del APK. Sigue exactamente la estructura del árbol de hash de fs-verity (por ejemplo, el padding de cero para la sal y el padding de cero para el último bloque). Android 11 almacena la firma en un archivo separado. <apk name>.apk.idsigUna firma v4 requiere una firma complementaria v2 o v3.

Formato de archivo

Todos los campos numéricos están en formato little endian. Todos los campos ocupan exactamente la cantidad de bytes como su sizeof(), sin relleno ni alineación implícitos.

A continuación, se muestra una estructura auxiliar para simplificar las definiciones.

template <class SizeT>
struct sized_bytes {
        SizeT size;
        byte bytes[size];
};

Contenido del archivo principal:

struct V4Signature {
        int32 version; // only version 2 is supported as of now
        sized_bytes<int32> hashing_info;
        sized_bytes<int32> signing_info;
        sized_bytes<int32> merkle_tree;  // optional
};

hashing_info es el parámetro que se usa para la generación de árboles de hash más el hash raíz:

struct hashing_info.bytes {
    int32 hash_algorithm;    // only 1 == SHA256 supported
    int8 log2_blocksize;     // only 12 (block size 4096) supported now
    sized_bytes<int32> salt; // used exactly as in fs-verity, 32 bytes max
    sized_bytes<int32> raw_root_hash; // salted digest of the first Merkle tree page
};

signing_info es la siguiente estructura:

struct signing_info.bytes {
    sized_bytes<int32> apk_digest;  // used to match with the corresponding APK
    sized_bytes<int32> x509_certificate; // ASN.1 DER form
    sized_bytes<int32> additional_data; // a free-form binary data blob
    sized_bytes<int32> public_key; // ASN.1 DER, must match the x509_certificate
    int32 signature_algorithm_id; // see the APK v2 doc for the list
    sized_bytes<int32> signature;
};
  • apk_digest se toma del bloque de firma v3 del APK o, si no está presente, del bloque v2 (consulta apk_digest).

Para crear y verificar un código signature, se deben serializar los siguientes datos en un blob binario y pasarlos al algoritmo de firma o verificación como los datos firmados:

struct V4DataForSigning {
        int32 size;
        int64 file_size; // the size of the file that's been hashed.
        hashing_info.hash_algorithm;
        hashing_info.log2_blocksize;
        hashing_info.salt;
        hashing_info.raw_root_hash;
        signing_info.apk_digest;
        signing_info.x509_certificate;
        signing_info.additional_data;
};
  1. merkle_tree es el árbol de Merkle completo del APK, calculado como se describe en la documentación de fs-verity.

Productores y consumidores

La herramienta del SDK de Android apksigner ahora genera el archivo de firma v4 si lo ejecutas con parámetros predeterminados. La firma v4 se puede inhabilitar de la misma manera que los otros esquemas de firma. También puede verificar si la firma v4 es válida.

adb espera que el archivo .apk.idsig esté presente junto al .apk cuando se ejecuta el comando adb install --incremental.
También usará el archivo .idsig para intentar la instalación incremental de forma predeterminada y recurrirá a una instalación normal si falta o no es válida.

Cuando se crea una sesión de instalación, la nueva API de instalación de transmisión en PackageInstaller acepta la firma v4 sin formato como un argumento independiente cuando se agrega un archivo a la sesión. En este punto, signing_info se pasa a incfs como un BLOB completo. Incfs extrae el hash raíz del blob.

Cuando se confirma la sesión de instalación, PackageManagerService realiza un ioctl para recuperar el blob signing_info de incfs, analizarlo y verificar la firma.

Se espera que el componente del cargador de datos incremental transmita la parte del árbol de Merkle de la firma a través de la API nativa del cargador de datos.El comando de shell del servicio
package install-incremental acepta el archivo de firma v4 despojado codificado como base64 como parámetro para cada archivo agregado. El árbol de Merkle correspondiente se debe enviar al stdin del comando.

apk_digest

apk_digest es el primer resumen de contenido disponible en orden:

  1. V3, bloque de 1 MB, SHA2-512 (CONTENT_DIGEST_CHUNKED_SHA512)
  2. V3, bloque de 4 KB, SHA2-256 (CONTENT_DIGEST_VERITY_CHUNKED_SHA256)
  3. V3, bloque de 1 MB, SHA2-256 (CONTENT_DIGEST_CHUNKED_SHA256)
  4. V2, SHA2-512,
  5. V2, SHA2-256.

Consulta secuencia con prefijo de longitud de firmas con prefijo de longitud en el esquema de firma de APK v3.

proceso de validación de APK v4
Figura 1: Proceso de validación de APK v4

Validación y pruebas

Valida la implementación con pruebas de unidades de funciones y CTS.

  • CtsIncrementalInstallHostTestCases
    • /android/cts/hostsidetests/incrementalinstall

Prueba el formato de la firma

Para probar el formato de firma, configura un entorno de desarrollo y ejecuta las siguientes pruebas manuales:

$ atest PackageManagerShellCommandTest

PackageManagerShellCommandIncrementalTest

Prueba el formato de firma con el SDK de Android (ADB y apksigner)

Para probar el formato de firma con el SDK de Android, configura un entorno de desarrollo y asegúrate de haber completado la implementación de IncFS. Luego, escribe la compilación en un emulador o dispositivo físico de destino. Debes generar o obtener un APK existente y, luego, crear una clave de firma de depuración. Por último, firma e instala el APK con el formato de firma v4 desde la carpeta build-tools.

Firma

$ ./apksigner sign --ks debug.keystore game.apk

Instalar

$ ./adb install game.apk

¿Dónde se pueden encontrar estas pruebas?

/android/cts/tests/tests/content/src/android/content/pm/cts/PackageManagerShellCommandIncrementalTest.java