APK signature scheme v3.2

Android 17 (API level 37) introduces APK Signature Scheme v3.2, a hybrid signature scheme designed to support the Android ecosystem's transition to post-quantum cryptography (PQC).

As the industry deploys PQC algorithms at scale, the v3.2 scheme provides defense in depth. It requires you to sign APKs with both a classical algorithm, like RSA or ECDSA, and a PQC algorithm. This hybrid approach uses classical cryptography to protect your APK while defending against threats from quantum computers.

Purpose and details

The v3.2 scheme operates as a standard, industry-aligned transitional mechanism. With this hybrid approach, you gain the quantum-resistant benefits of PQC while continuing to rely on the proven security of classical signature algorithms. Once the newly standardized PQC algorithms establish operational maturity at scale, you can transition from this hybrid configuration to a single PQC signing key. Platform support for the v3.2 signature scheme begins with Android 17. Lower Android versions skip the v3.2 block and use previous schemes for signature verification.

To maintain security and prevent downgrade attacks during this transition, the v3.2 scheme enforces the following behaviors:

  • New key material: Transitioning to a hybrid block requires generating new classical and PQC keys. Don't reuse key material between hybrid and non-hybrid configurations.
  • Implicit rotation: The platform treats the hybrid block as an implicit key rotation. The platform appends the new classical key to the app's existing signing lineage as the next-to-last key, and treats the new PQC key as the app's current signing identity.
  • Shared lineage: To successfully execute the implicit rotation, both the new classical key and the new PQC key within the hybrid block must share the same signing ancestry. You must duplicate the app's existing signing history—whether a single original key or a lineage of previously rotated keys—for both new hybrid signers. The platform uses this shared lineage to verify that the entity transitioning the app to the hybrid scheme is the legitimate owner of the app's current signing identity.
  • PQC single-signer restriction: During the initial rollout of PQC, Android explicitly restricts the use of PQC algorithms to the v3.2 hybrid block. The platform doesn't verify a single-signer PQC configuration using previous signature schemes, such as v2, v3.0, or v3.1.
  • Transitioning back: When transitioning from a v3.2 hybrid block back to a single-signer block—either a classical signer or a PQC signer when supported in a future release—the platform verifies that both the classical and PQC keys from the hybrid block are present in the new signing lineage and attest to the new single signer.

Best practices for transitioning

To maintain compatibility with lower Android versions and provide a safe upgrade path during the transition to PQC signing, APKs must continue to include a standard v3.0 or v3.1 signature block signed by a single classical key. Because only Android 17 (API level 37) and higher support the v3.2 hybrid scheme, this requirement lets devices running lower versions verify and install the app.

Classical fallback configuration

To provide an operational safety net during the PQC transition, implement a classical fallback configuration.

  • Existing apps: The app's current established signing key, K0, serves as the natural foundation for this fallback.
  • New apps: Generate a baseline classical signing key, K0, alongside the new hybrid keys, C_K1 and PQC_K1, to establish the initial identity.

In both scenarios, the APK must include a standard v3.0 or v3.1 signature block signed by the classical key, K0, alongside the v3.2 hybrid block signed by the new hybrid keys, C_K1 and PQC_K1.

During the initial deployment of the v3.2 scheme, the signing lineage for the hybrid block should grant the ROLLBACK capability to K0. If deployment issues arise, this capability lets the app fall back to a classical signature without disrupting user updates. Once sufficient runtime data confirms the hybrid deployment is stable, we recommend removing the ROLLBACK capability in subsequent updates to fully secure your new keys.

Long-term configuration requirements

You must maintain this hybrid signing configuration for as long as your app targets a platform release that exclusively supports the hybrid scheme. Even if a platform version supports single-signer PQC keys, you must sign any APK targeting a release that requires the v3.2 hybrid block with both keys.

APK signature scheme v3.2 block

The APK Signing Block stores the v3.2 signature block alongside any v2, v3.0, and v3.1 signature blocks.

The v3.2 block structure is similar to v3.0, but uses a new block ID, 0x70e1c89f, to signal that it's a hybrid block. A valid v3.2 block must contain exactly two signers.

Supported algorithms

The v3.2 scheme initially supports the following PQC signature algorithms:

  • ML-DSA-65
  • ML-DSA-87

These are paired with standard classical signature algorithms, such as those supported in v3.0 and v3.1, to form the hybrid block.

Format

The APK Signing Block stores the APK Signature Scheme v3.2 block under ID 0x70e1c89f.

The format of the v3.2 block is identical to v3.0, but the top-level sequence of signer elements must contain exactly two entries targeting the same SDK version:

  • length-prefixed sequence of length-prefixed signer:
    • length-prefixed signer (Classical)
    • length-prefixed signer (PQC)

Each signer uses the standard v3 format:

  • length-prefixed signed data:
    • length-prefixed sequence of length-prefixed digests:
    • signature algorithm ID (4 bytes)
    • digest (length-prefixed)
    • length-prefixed sequence of certificates:
    • length-prefixed X.509 certificate (ASN.1 DER form)
    • minSDK (uint32)
    • maxSDK (uint32)
    • length-prefixed sequence of length-prefixed additional attributes:
    • ID (uint32)
    • value (variable-length: length of the additional attribute - 4 bytes)
  • minSDK (uint32)
  • maxSDK (uint32)
  • length-prefixed sequence of length-prefixed signatures:
    • signature algorithm ID (4 bytes)
    • length-prefixed signature over signed data
  • length-prefixed public key (SubjectPublicKeyInfo, ASN.1 DER form)

Verification

On Android 17 (API level 37) and higher, to verify the v3.2 signature, the platform verifies both the classical and PQC signers, confirms their compatibility, and checks the implicit rotation lineage. On Android 16 (API level 36) and lower platform releases, the platform doesn't process this hybrid signature block and uses previous schemes instead.

The overall process is as follows:

  1. Find the APK Signature Scheme v3.2 Block (ID 0x70e1c89f).
  2. Verify that the block contains exactly two signers. If there are fewer or more than two, verification fails.
  3. Verify that one signer uses a classical signature algorithm and the other uses a PQC signature algorithm. If both are classical or both are PQC, verification fails.
  4. Verify that both signers target the exact same SDK range (minSdkVersion and maxSdkVersion).
  5. For each of the two signers, perform standard v3 verification:
    1. Choose the strongest supported signature algorithm ID from signatures.
    2. Verify the corresponding signature from signatures against signed data using the public key.
    3. Verify that the minSdkVersionand maxSdkVersion in the signed data match the unsigned minSdkVersion and maxSdkVersion.
    4. Parse certificates and verify that the first certificate matches the public key.
    5. Parse additional attributes to extract proof-of-rotation structures.
  6. Verify the signing history (proof-of-rotation):
    1. Check that both signers have identical preceding signing histories.
    2. The lineage lengths must match, and all certificates and capability flags leading up to the current signers must be identical.
    3. If the histories match, merge the lineages: treat the classical signer's certificate as the predecessor to the PQC signer's certificate, assigning the PQC signer as the current terminal node.
  7. Verify Content Digests:
    1. Iterate through the digests map for both signers.
    2. Verify that for any matching digest algorithms, the calculated digest values are identical between the classical and PQC signers.
  8. Use the matched digests from the verified signers to verify the integrity of the APK contents (similar to v2 and v3).
    1. If the app is already installed, verify the package update lineage:
    2. Updating from a single signer: If the installed app was signed with a single classical key, that key must be present in the new hybrid block's signing lineage as a predecessor to the hybrid signers.
    3. Updating from a hybrid signer to continue hybrid: If the installed app was signed with a v3.2 hybrid block, both the previous classical and PQC keys must either remain the current active signers in the update APK's v3.2 block, or both must be present in the new signing lineage attesting to the newly rotated hybrid keys.
    4. Transitioning away from a hybrid signer: If the installed app was signed with a v3.2 hybrid block and the update APK transitions back to a single signer (either PQC or classical), both of the previous hybrid signers must be present in the update APK's signing lineage and attest to the new single signing key.
    5. Invalid update paths: If a developer attempts to update a hybrid-signed app using only one of the hybrid keys as a single signer without a proper rotation, the update fails. Both keys must explicitly be involved in any transition to prevent downgrade attacks.
  9. If any step fails, verification fails.

Stripping protection

To prevent downgrade attacks to lower signature schemes, the v3.2 scheme includes stripping protection attributes similar to previous scheme iterations.

The signing tool writes two specific hybrid stripping protection attributes into the additional attributes of the v3.0 and v3.1 signature blocks. These attributes define the exact SDK version boundaries within which the v3.2 hybrid block must be present and verified:

  • Minimum SDK version attribute (ID 0xbf940529): The value of this attribute dictates the minimum SDK version supported by the hybrid signing block.
  • Maximum SDK version attribute (ID 0x9f06b79c): The value of this attribute dictates the maximum SDK version that the hybrid signing block supports. This attribute lets you transition to a single-signer configuration when higher platform releases don't require the hybrid signature.

If the platform skips v3.2 verification because the block is missing or its SDK range doesn't apply to the device, the platform verifies the APK against the next block present. If that earlier block contains these stripping protection attributes, the platform applies the following checks:

  • Presence and range verification: If a v3.0 or v3.1 signature block contains either the minimum SDK attribute (ID 0xbf940529, value X) or the maximum SDK attribute (ID 0x9f06b79c, value Y), the platform requires that the v3.2 hybrid block exists within the APK. The platform reads the hybrid block to verify that its targeted SDK range matches the bounds specified by these attributes. If the v3.2 block is missing, or if its internal minimum and maximum SDK target values don't equal X and Y, the platform rejects the installation.
  • Enforcement within range: If the device's SDK version falls within the valid range specified by these attributes—which is greater than or equal to X, and less than or equal to Y when you provide the maximum attribute—the platform strictly requires the v3.2 hybrid block for signature verification. If the platform verifies a v3.0 or v3.1 block on a device within this target SDK range, the platform rejects the installation because the v3.2 block was maliciously bypassed or stripped.

By enforcing these boundaries, the platform determines when an APK must contain a v3.2 block. If the block has been stripped, the platform rejects the installation to prevent a downgrade attack.

Validate your implementation

To test your implementation of the v3.2 signature scheme, run the HybridSignatureVerificationTest.java CTS tests located in cts/hostsidetests/appsecurity/src/android/appsecurity/cts/.

These tests cover a comprehensive suite of scenarios, including successful installations, updates from classical-only versions, rollback transitions using the ROLLBACK capability, and verifications of stripping attack mitigations.