apksigner

Lo strumento apksigner, disponibile nella versione 24.0.3 e successive di Build Tools dell'SDK Android, 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 tale APK.

Questa pagina presenta una breve guida per l'utilizzo dello strumento e funge da riferimento per le diverse opzioni della riga di comando supportate dallo strumento. Per una descrizione più completa della modalità di utilizzo dello strumento apksigner per la firma degli APK, consulta la pagina Firmare l'app.

Attenzione: se firmi l'APK usando apksigner e apporti ulteriori modifiche all'APK, la firma dell'APK verrà invalidata. Se usi zipalign per allineare l'APK, usalo prima di firmare l'APK.

Utilizzo

Firma un APK

La sintassi per firmare un APK usando 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 usando lo strumento apksigner, devi fornire la chiave privata e il certificato del firmatario. Puoi includere queste informazioni in due modi:

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

In genere si firma un APK usando un solo firmatario. Se devi firmare un APK utilizzando più firmatari, utilizza l'opzione --next-signer per separare l'insieme di opzioni generali da 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 la riuscita della verifica della firma di un APK sulle piattaforme supportate è la seguente: 

apksigner verify [options] app-name.apk

Ruota le chiavi di firma

La sintassi per la rotazione di una discendenza del certificato 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

I seguenti elenchi includono l'insieme di opzioni per ciascun comando supportato dallo strumento apksigner.

Firma comando

Il comando del simbolo apksigner prevede 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 viene fornita esplicitamente, il pacchetto APK è firmato e il file APK di input viene sovrascritto.
--min-sdk-version <integer>
Il livello API framework Android più basso che apksigner utilizza per confermare che la firma dell'APK verrà verificata. Valori più elevati consentono allo strumento di usare parametri di sicurezza più efficaci durante la firma dell'app, ma limitano la disponibilità dell'APK ai 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 livello API framework Android più elevato che apksigner utilizza per confermare che la firma dell'APK verrà verificata. Per impostazione predefinita, lo strumento utilizza il livello API più elevato possibile.
--rotation-min-sdk-version <integer>
Il livello API più basso che deve essere utilizzato dalla chiave di firma ruotata dell'APK per produrre la firma dell'APK. La chiave di firma originale (non ruotata) dell'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 usare --rotation-min-sdk-version 28 per continuare a firmare l'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 --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 --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 --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.

Usa only per generare solo la firma v4 senza modificare l'APK e le eventuali firme che aveva prima della chiamata. only non va a buon fine 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 --min-sdk-version e --max-sdk-version per 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 determinato firmatario. Queste opzioni non sono necessarie se firmi la tua app utilizzando un solo firmatario.

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

Opzioni relative a chiavi e certificati

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

--ks <filename>
La chiave privata e la catena di certificati del firmatario risiedono nel file KeyStore basato su Java fornito. Se il nome del file è impostato su "NONE", l'archivio chiavi contenente la chiave e il certificato non richiede l'indicazione 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 l'archivio chiavi 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 archivio chiavi. Lo strumento apksigner supporta i seguenti formati:

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

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

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

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

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

    • Su Java 9, apksigner non è in grado di rilevare il set di caratteri della console. Potrebbe essere necessario specificare --pass-encoding quando viene utilizzata una password non ASCII. Potrebbe anche essere necessario specificare questa opzione con gli archivi chiavi creati da keytool su un sistema operativo o impostazioni internazionali diversi.

    --key-pass <input-format>

    La password per la 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 è archiviata nella variabile di ambiente specificata.
    • file:<filename> - La password viene memorizzata su una singola riga nel file specificato.
    • stdin - La password viene fornita su una 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 massima priorità.
    --ks-provider-class <class-name>
    Il nome completo della classe 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 provider specificato con l'opzione --ks-provider-name.
    --ks-provider-arg <value>
    Un valore stringa da trasmettere come argomento per il costruttore della classe provider JCA; la classe stessa viene definita con l'opzione --ks-provider-class. Per impostazione predefinita, apksigner utilizza il costruttore a zero argomenti della classe.
    --key <filename>
    Il nome del file che contiene la chiave privata del firmatario. Questo file deve utilizzare 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 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 offre le seguenti opzioni.

    --print-certs
    Mostra informazioni sui certificati di firma dell'APK.
    --min-sdk-version <integer>
    Il livello API framework Android più basso che apksigner utilizza per confermare che la firma dell'APK verrà verificata. Valori più elevati consentono allo strumento di usare parametri di sicurezza più efficaci durante la firma dell'app, ma limitano la disponibilità dell'APK ai 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 livello API framework Android più elevato che apksigner utilizza per confermare che la firma dell'APK verrà verificata. Per impostazione predefinita, lo strumento utilizza il livello API più elevato possibile.
    -v, --verbose
    Utilizza la modalità di output dettagliato.
    -Werr
    Tratta gli avvisi come errori.

    Esempi

    Di seguito sono riportati alcuni esempi in cui viene utilizzato apksigner.

    Firma un APK

    Firma un APK usando release.jks, che è l'unica chiave nell'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 usando 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 l'SDK per il targeting per rotazione 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 per il targeting per rotazione 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 è prevista la conferma della validità delle firme dell'APK su tutte le piattaforme Android supportate dall'APK: 

    $ apksigner verify app.apk

    Controlla se è prevista una conferma della validità delle firme dell'APK su 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 supporti la rotazione della chiave:

    $ 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