apksigner

Lo strumento apksigner, disponibile nella revisione 24.0.3 e successive di Android SDK Build Tools, ti consente di firmare gli APK e verificare che La firma dell'APK verrà verificata su tutte le versioni di Android supportata dall'APK.

Questa pagina presenta una breve guida all'uso lo strumento e funge da riferimento per le diverse opzioni della riga di comando supportati dallo strumento. Per una descrizione più completa di come Lo strumento apksigner viene utilizzato per firmare gli APK. Consulta la pagina Firmare l'app.

Attenzione: se firmi l'APK utilizzando apksigner e apportare ulteriori modifiche all'APK, la firma dell'APK viene invalidata. Se utilizzi zipalign per allineare l'APK, usalo prima di firmare l'APK.

Utilizzo

Firma un APK

La sintassi per firmare un APK utilizzando lo strumento apksigner è la seguente: che segue: 

apksigner sign --ks keystore.jks |
  --key key.pk8 --cert cert.x509.pem
  [signer_options] app-name.apk

Se firmi un APK usando lo strumento apksigner, devi fornire la chiave privata e il certificato del firmatario. Puoi includere queste informazioni in due modi:

  • Specifica un file di archivio chiavi utilizzando l'opzione --ks.
  • Specifica separatamente il file della chiave privata e il file del certificato utilizzando il metodo rispettivamente le opzioni --key e --cert. La il file della chiave privata deve essere nel formato PKCS #8 e il file del certificato deve nel formato X.509.

In genere, firmi un APK usando un solo firmatario. Per firmare un APK utilizzando più firmatari, usa l'opzione --next-signer per separare l'insieme di opzioni generali applicare a ciascun firmatario: 

apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

Verificare la firma di un APK

La sintassi per confermare l'esito positivo della verifica della firma di un APK sulle piattaforme supportate è il seguente: 

apksigner verify [options] app-name.apk

Ruota le chiavi di firma

La sintassi per la rotazione di una derivazione di un certificato di firma o di una nuova sequenza di firme, è il seguente:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file \
  --old-signer --ks old-signer-jks \
  --new-signer --ks new-signer-jks

Opzioni

I seguenti elenchi includono l'insieme di opzioni per ogni comando che il Supportati dallo strumento apksigner.

Firma comando

Il comando del simbolo apksigner ha le seguenti opzioni.

Opzioni generali

Le seguenti opzioni specificano le impostazioni di base da applicare a un firmatario:

--out <apk-filename>
La posizione in cui vuoi salvare l'APK firmato. Se questa opzione non è fornito in modo esplicito, il pacchetto APK è già connesso, quindi sovrascrive il file APK di input.
--min-sdk-version <integer>
Il livello API del framework Android più basso utilizzato da apksigner per per confermare che la firma dell'APK verrà verificata. Valori più alti consentono per usare parametri di sicurezza più efficaci durante la firma dell'app, ma limitando la disponibilità dell'APK su dispositivi su cui sono installate versioni più recenti di Android. Per impostazione predefinita, apksigner utilizza il valore dell'attributo minSdkVersion del file manifest dell'app.
--max-sdk-version <integer>
Il più alto livello API del framework Android utilizzato da apksigner per confermare la verifica della firma dell'APK. Per impostazione predefinita, utilizza il livello API più alto possibile.
--rotation-min-sdk-version <integer>
Il livello API più basso della firma a rotazione dell'APK dovrebbe usare per produrre la firma dell'APK. La la chiave di firma originale (non ruotata) per l'APK verrà usata per tutti le versioni precedenti della piattaforma. Per impostazione predefinita, Chiavi di firma ruotate, supportate sui dispositivi con Android 13 (livello API 33) o versioni successive, vengono utilizzati con il blocco di firma v3.1.

Nota : se la tua app è stata firmata da una firma a rotazione su un dispositivo con Android 12L (livello API 32) o versioni precedenti, devi usare --rotation-min-sdk-version 28 per continuare ad accedere la tua app con la chiave di firma ruotata per Android 9 (livello API 28).

--v1-signing-enabled <true | false>
Consente di stabilire se apksigner firma il pacchetto APK specificato usando lo schema di firma tradizionale basato su JAR. Per impostazione predefinita, lo strumento utilizza i valori di --min-sdk-version e --max-sdk-version per decidere quando applicare questa firma .
--v2-signing-enabled <true | false>
Consente di stabilire se apksigner firma il pacchetto APK specificato utilizzando l'APK Schema di firma v2. Per impostazione predefinita, lo strumento utilizza i valori --min-sdk-version e --max-sdk-version a decidere quando applicare questo schema di firma.
--v3-signing-enabled <true | false>
Consente di stabilire se apksigner firma il pacchetto APK specificato utilizzando l'APK Schema di firma v3. Per impostazione predefinita, lo strumento utilizza i valori --min-sdk-version e --max-sdk-version a decidere quando applicare questo schema di firma.
--v4-signing-enabled <true | false | only>

Consente di stabilire se apksigner o meno firma il pacchetto APK specificato utilizzando l'APK Schema di firma v4. Questo schema genera una firma in un file separato (apk-name.apk.idsig). Se true e l'APK non sono firmati, viene visualizzata una firma v2 o v3 viene generato in base ai valori di --min-sdk-version e --max-sdk-version. Il comando produce quindi .idsig in base ai contenuti dell'APK firmato.

Utilizza only per generare solo la versione v4 senza modificare l'APK e le firme che aveva prima della chiamata. only non funziona se l'APK non Avere già una firma v2 o v3 o se la firma ha utilizzato una chiave diversa rispetto a quello fornito per la chiamata attuale.

Per impostazione predefinita, lo strumento utilizza i valori --min-sdk-version e --max-sdk-version a decidere quando applicare questo schema di firma.

-v, --verbose
Utilizza la modalità di output dettagliato.

Opzioni per firmatario

Le seguenti opzioni specificano la configurazione di un particolare firmatario. Questi non sono necessarie se firmi l'app usando un solo firmatario.

--next-signer <signer-options>
Utilizzato per specificare diverse opzioni generali per ciascun firmatario.
--v1-signer-name <basename>
Il nome di base dei file che compongono la firma basata su JAR per firmatario corrente. Per impostazione predefinita, apksigner utilizza l'alias della chiave l'archivio chiavi o il nome base del file della chiave per il firmatario.

Opzioni chiave e certificato

Le seguenti opzioni specificano la chiave privata e il certificato del firmatario:

--ks <filename>
La chiave privata e la catena di certificati del firmatario si trovano nella File di archivio chiavi basato su Java. Se il nome del file è impostato su "NONE", l'archivio chiavi contenente la chiave e il certificato non ha bisogno di un file come specificato per alcuni archivi chiavi PKCS #11.
--ks-key-alias <alias>
Il nome dell'alias che rappresenta la chiave privata del firmatario all'interno dell'archivio chiavi. Se l'archivio chiavi associato firmatario contiene più chiavi, devi specificare questa opzione.
--ks-pass <input-format>

La password dell'archivio chiavi che contiene la chiave privata del firmatario e certificato. Devi fornire una password per aprire un archivio chiavi. La Lo strumento apksigner supporta i seguenti formati:

  • pass:<password> - Password fornita in linea con il resto del comando apksigner sign.
  • env:<name> - La password è memorizzata nel variabile di ambiente.
  • file:<filename> - La password viene memorizzata come singola riga nel file specificato.
  • stdin – La password viene fornita su un'unica riga in il flusso di input standard. Questo è il comportamento predefinito per --ks-pass.

Nota : se includi più password nello stesso indirizzo, specificali su righe separate. Lo strumento apksigner associa le password ai firmatari di un APK in base all'ordine in cui tu specifichi i firmatari. Se hai fornito due password per un firmatario, apksigner interpreta la prima password come un archivio chiavi e la seconda come password della chiave.

--pass-encoding <charset>
Include le codifiche dei caratteri specificate, come ibm437 o utf-8 quando provi a gestire password contenenti caratteri non ASCII.

Keytool spesso cripta gli archivi chiavi convertendo la password utilizzando il metodo . Per impostazione predefinita, apksigner tenta di decriptare utilizzando diverse forme di password:

  • Il modulo Unicode
  • Il formato è codificato utilizzando il set di caratteri predefinito JVM
  • In Java 8 e versioni precedenti, il formato è codificato utilizzando il set di caratteri predefinito della console

    • In Java 9, apksigner non è in grado di rilevare il set di caratteri della console. Potresti dover specificare --pass-encoding quando e una password non ASCII. Potresti dover specificare questa opzione anche per i keystore che keytool creato su un sistema operativo diverso o in una lingua diversa.

    --key-pass <input-format>

    La password per la chiave privata del firmatario, che è necessaria se la chiave privata è protetta da password. Lo strumento apksigner supporta i seguenti formati:

    • pass:<password> - Password fornita in linea con il resto del comando apksigner sign.
    • env:<name> - La password è memorizzata nel variabile di ambiente.
    • file:<filename> - La password viene memorizzata come singola riga nel file specificato.
    • stdin – La password viene fornita su un'unica riga in il flusso di input standard. Questo è il comportamento predefinito per --key-pass.
    --ks-type <algorithm>
    Il tipo o l'algoritmo associato all'archivio chiavi che contiene la funzione chiave privata e il certificato del firmatario. Per impostazione predefinita, apksigner utilizza il tipo definito come costante keystore.type in File delle proprietà di sicurezza.
    --ks-provider-name <name>
    Il nome del provider JCA da utilizzare per richiedere l'archivio chiavi del firmatario implementazione. Per impostazione predefinita, apksigner utilizza con la massima priorità.
    --ks-provider-class <class-name>
    Il nome completo della classe del provider JCA da utilizzare per la richiesta l'implementazione dell'archivio chiavi del firmatario. Questa opzione è un'alternativa per --ks-provider-name. Per impostazione predefinita, apksigner utilizza il fornitore specificato con --ks-provider-name .
    --ks-provider-arg <value>
    Un valore stringa da passare come argomento per il costruttore di JCA Classe provider; la classe stessa è definita con Opzione --ks-provider-class. Per impostazione predefinita, apksigner utilizza il costruttore di argomento zero della classe.
    --key <filename>
    Il nome del file che contiene la chiave privata del firmatario. Questo file deve usare il formato DER PKCS #8. Se la chiave è protetta da password, apksigner richiede la password utilizzando l'input standard a meno che non specifichi un tipo di formato di input diverso utilizzando Opzione --key-pass.
    --cert <filename>
    Il nome del file che contiene la catena di certificati del firmatario. Questo deve usare il formato X.509 PEM o DER.

    Comando di verifica

    Il comando di verifica apksigner offre le seguenti opzioni.

    --print-certs
    Mostra informazioni sui certificati di firma dell'APK.
    --min-sdk-version <integer>
    Il livello API del framework Android più basso utilizzato da apksigner per per confermare che la firma dell'APK sarà verificata. Valori più alti consentono per usare parametri di sicurezza più efficaci durante la firma dell'app, ma limitando la disponibilità dell'APK su dispositivi su cui sono installate versioni più recenti di Android. Per impostazione predefinita, apksigner utilizza il valore dell'attributo minSdkVersion del file manifest dell'app.
    --max-sdk-version <integer>
    Il più alto livello API del framework Android utilizzato da apksigner per confermare che la firma dell'APK sarà verificata. Per impostazione predefinita, utilizza il livello API più alto possibile.
    -v, --verbose
    Utilizza la modalità di output dettagliato.
    -Werr
    Considera gli avvisi come errori.

    Esempi

    Di seguito sono riportati alcuni esempi che utilizzano apksigner.

    Firma un APK

    Firma un APK utilizzando release.jks, che è l'unica chiave nella Archivio chiavi: 

    $ apksigner sign --ks release.jks app.apk

    Firma un APK usando una chiave privata e un certificato archiviati come file separati: 

    $ apksigner sign --key release.pk8 --cert release.x509.pem app.apk

    Firma un APK utilizzando due chiavi: 

    $ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk

    Firma un APK con una chiave di firma ruotata e la versione 28 o versioni successive dell'SDK che ha come target la rotazione: 

    $ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28

    Firma un APK con una chiave di firma ruotata e la versione 33 o versioni successive dell'SDK che ha come target la rotazione: 

    $ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk

    Verificare la firma di un APK

    Controlla se la validità delle firme degli APK dovrebbe essere confermata il giorno tutte le piattaforme Android supportate dall'APK: 

    $ apksigner verify app.apk

    Controlla se la validità delle firme degli APK dovrebbe essere confermata il giorno Android 4.0.3 (livello API 15) e versioni successive: 

    $ apksigner verify --min-sdk-version 15 app.apk

    Ruota le chiavi di firma

    Abilita una derivazione del certificato di firma che supporta la rotazione delle chiavi:

    $ apksigner rotate --out /path/to/new/file --old-signer \
    --ks release.jks --new-signer --ks release2.jks

    Ruota di nuovo le chiavi di firma:

    $ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file --old-signer --ks release2.jks \
  --new-signer --ks release3.jks