apksigner

Lo strumento apksigner, disponibile nella revisione 24.0.3 e versioni successive di Android SDK Build Tools, ti consente di firmare gli APK e confermare che la firma di un APK verrà verificata correttamente su tutte le versioni della piattaforma Android supportate da quell'APK.

Questa pagina presenta una breve guida all'utilizzo dello strumento e funge da riferimento per le diverse opzioni della riga di comando supportate dallo strumento. Per una descrizione più completa di come viene utilizzato lo strumento apksigner per firmare gli APK, consulta Firma la tua app.

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

Utilizzo

Firma un APK

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

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

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

  • Specifica un file KeyStore utilizzando l'opzione --ks.
  • Specifica separatamente il file della chiave privata e il file del certificato utilizzando rispettivamente le opzioni --key e --cert. Il file della chiave privata deve utilizzare il formato PKCS #8 e il file del certificato deve utilizzare il formato X.509.

In genere, un APK viene firmato utilizzando un solo firmatario. Se devi firmare un APK utilizzando più firmatari, utilizza l'opzione --next-signer per separare il set di opzioni generali da applicare a ogni firmatario: 

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

Verificare la firma di un APK

La sintassi per confermare la verifica riuscita della firma di un APK sulle piattaforme supportate è la seguente: 

apksigner verify [options] app-name.apk

Ruotare le chiavi di firma

La sintassi per la rotazione di una genealogia di certificati di firma o di una nuova sequenza di firme è la 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

Gli elenchi seguenti includono il set di opzioni per ogni comando supportato dallo strumento apksigner.

Comando di firma

Il comando 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 è fornita in modo esplicito, il pacchetto APK viene firmato sul posto, sovrascrivendo il file APK di input.
--min-sdk-version <integer>
Il livello API framework Android più basso utilizzato da apksigner per confermare che la firma dell'APK verrà verificata. Valori più elevati consentono allo strumento di utilizzare parametri di sicurezza più efficaci durante la firma dell'app, ma limitano la disponibilità dell'APK ai dispositivi con 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 livello API del framework Android più alto utilizzato da apksigner per confermare che la firma dell'APK verrà verificata. Per impostazione predefinita, lo strumento utilizza il livello API più alto possibile.
--rotation-min-sdk-version <integer>
Il livello API più basso che la chiave di firma ruotata dell'APK deve utilizzare per produrre la firma dell'APK. La chiave di firma originale (non ruotata) per l'APK verrà utilizzata per tutte le versioni precedenti della piattaforma. Per impostazione predefinita, le chiavi di firma ruotate, supportate sui dispositivi con Android 13 (livello API 33) o versioni successive, vengono utilizzate con il blocco di firma v3.1.

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

--v1-signing-enabled <true | false>
Determina se apksigner firma il pacchetto APK specificato utilizzando 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 questo schema di firma.
--v2-signing-enabled <true | false>
Determina se apksigner firma il pacchetto APK specificato utilizzando lo schema di firma dell'APK v2. Per impostazione predefinita, lo strumento utilizza i valori di --min-sdk-version e --max-sdk-version per decidere quando applicare questo schema di firma.
--v3-signing-enabled <true | false>
Determina se apksigner firma il pacchetto APK specificato utilizzando lo schema di firma dell'APK v3. Per impostazione predefinita, lo strumento utilizza i valori di --min-sdk-version e --max-sdk-version per decidere quando applicare questo schema di firma.
--v4-signing-enabled <true | false | only>

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

Utilizza only per generare solo la firma v4 senza modificare l'APK e le firme che aveva prima della chiamata. only non riesce se l'APK non ha già una firma v2 o v3 o se la firma utilizzava una chiave diversa da quella fornita per la chiamata corrente.

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

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

Opzioni per firmatario

Le seguenti opzioni specificano la configurazione di un determinato firmatario. Queste opzioni non sono necessarie se firmi l'app utilizzando un solo firmatario.

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

Opzioni di 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 nel file KeyStore basato su Java specificato. Se il nome file è impostato su "NONE", l'archivio chiavi contenente la chiave e il certificato non richiede la specifica di un file, come nel caso di alcuni archivi chiavi PKCS #11.
--ks-key-alias <alias>
Il nome dell'alias che rappresenta la chiave privata e i dati del certificato del firmatario all'interno dell'archivio chiavi. Se il KeyStore associato al firmatario contiene più chiavi, devi specificare questa opzione.
--ks-pass <input-format>

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

  • pass:<password>: password fornita inline con il resto del comando apksigner sign.
  • env:<name>: la password è memorizzata nella variabile di ambiente specificata.
  • file:<filename>: la password viene memorizzata come singola riga nel file specificato.
  • stdin: la password viene fornita come singola riga nel flusso di input standard. Questo è il comportamento predefinito per --ks-pass.

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

--pass-encoding <charset>
Include le codifiche dei caratteri specificate, ad esempio ibm437 o utf-8, quando si tenta di gestire le password contenenti caratteri non ASCII.

Keytool spesso cripta i keystore convertendo la password utilizzando il set di caratteri predefinito della console. Per impostazione predefinita, apksigner tenta di decriptare utilizzando diverse forme della password:

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

    • Su Java 9, apksigner non riesce a rilevare il set di caratteri della console. Potresti dover specificare --pass-encoding quando viene utilizzata una password non ASCII. Potresti anche dover specificare questa opzione con i KeyStore che keytool ha creato su un sistema operativo diverso o in impostazioni internazionali diverse.

    --key-pass <input-format>

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

    • pass:<password>: la password viene fornita in linea con il resto del comando apksigner sign.
    • env:<name>: la password è memorizzata nella variabile di ambiente specificata.
    • file:<filename>: la password viene memorizzata come singola riga nel file specificato.
    • stdin: la password viene fornita come singola riga nel 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 chiave privata e il certificato del firmatario. Per impostazione predefinita, apksigner utilizza il tipo definito come costante keystore.type nel file delle proprietà di sicurezza.
    --ks-provider-name <name>
    Il nome del provider JCA da utilizzare quando si richiede l'implementazione dell'archivio chiavi del firmatario. Per impostazione predefinita, apksigner utilizza il fornitore con la priorità più alta.
    --ks-provider-class <class-name>
    Nome della classe completo del provider JCA da utilizzare quando si richiede l'implementazione dell'archivio chiavi del firmatario. Questa opzione funge da alternativa per --ks-provider-name. Per impostazione predefinita, apksigner utilizza il fornitore specificato con l'opzione --ks-provider-name.
    --ks-provider-arg <value>
    Un valore stringa da passare come argomento per il costruttore della classe JCA Provider; la classe stessa è definita con l'opzione --ks-provider-class. Per impostazione predefinita, apksigner utilizza il costruttore senza argomenti della classe.
    --key <filename>
    Il nome del file che contiene la chiave privata del firmatario. Questo file deve utilizzare il formato PKCS #8 DER. Se la chiave è protetta da password, apksigner richiede la password utilizzando l'input standard a meno che tu non specifichi un tipo diverso di formato di input utilizzando l'opzione --key-pass.
    --cert <filename>
    Il nome del file che contiene la catena di certificati del firmatario. Questo file deve utilizzare il formato X.509 PEM o DER.

    Verifica comando

    Il comando apksigner verify ha le seguenti opzioni.

    --print-certs
    Mostra informazioni sui certificati di firma dell'APK.
    --print-certs-pem
    Mostra informazioni sui certificati di firma dell'APK e stampa la codifica PEM di ogni certificato di firma in stdout.
    --min-sdk-version <integer>
    Il livello API framework Android più basso utilizzato da apksigner per confermare che la firma dell'APK verrà verificata. Valori più elevati consentono allo strumento di utilizzare parametri di sicurezza più efficaci durante la firma dell'app, ma limitano la disponibilità dell'APK ai dispositivi con 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 livello API del framework Android più alto utilizzato da apksigner per confermare che la firma dell'APK verrà verificata. Per impostazione predefinita, lo strumento utilizza il livello API più alto possibile.
    -v, --verbose
    Utilizza la modalità di output dettagliata.
    -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 nell'archivio chiavi: 

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

    Firma un APK utilizzando 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 rotazione che ha come target l'SDK versione 28 o successive: 

    $ 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 l'SDK di targeting versione 33 o successive: 

    $ 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 le firme dell'APK devono essere confermate come valide su tutte le piattaforme Android supportate dall'APK: 

    $ apksigner verify app.apk

    Verifica se è previsto che le firme dell'APK vengano confermate come valide su Android 4.0.3 (livello API 15) e versioni successive: 

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

    Ruotare le chiavi di firma

    Attiva una genealogia di certificati di firma che supporti la rotazione delle chiavi:

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

    Esegui di nuovo la rotazione delle 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