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'attributominSdkVersion
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.
--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
). Setrue
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.
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).
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 comandoapksigner 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
outf-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 comandoapksigner 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 costantekeystore.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'attributominSdkVersion
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