The apksigner
tool, available in revision 24.0.3 and higher of
the Android SDK Build Tools, lets you sign APKs and confirm that an
APK's signature will be verified successfully on all versions of the Android
platform supported by that APK.
This page presents a short guide for using
the tool and serves as a reference for the different command-line options that
the tool supports. For a more complete description of how the
apksigner
tool is used for signing your APKs, see Sign your app.
Caution: If you sign your APK using apksigner
and make further changes to the APK, the APK's signature is invalidated.
If you use
zipalign
to align
your APK, use it before signing the APK.
Usage
Sign an APK
The syntax for signing an APK using the apksigner
tool is as
follows:
apksigner sign --ks keystore.jks | --key key.pk8 --cert cert.x509.pem [signer_options] app-name.apk
When you sign an APK using the apksigner
tool, you must provide
the signer's private key and certificate. You can include this information in
two ways:
-
Specify a KeyStore file using the
--ks
option. -
Specify the private key file and certificate file separately using the
--key
and--cert
options, respectively. The private key file must use the PKCS #8 format, and the certificate file must use the X.509 format.
Usually, you sign an APK using only one signer. If you need to
sign an APK using multiple signers, use the --next-signer
option
to separate the set of general options to
apply to each signer:
apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk
Verify the signature of an APK
The syntax for confirming the successful verification of an APK's signature on supported platforms is as follows:
apksigner verify [options] app-name.apk
Rotate signing keys
The syntax for rotating a signing certificate lineage, or a new sequence of signatures, is as follows:
$ apksigner rotate --in /path/to/existing/lineage \ --out /path/to/new/file \ --old-signer --ks old-signer-jks \ --new-signer --ks new-signer-jks
Options
The following lists include the set of options for each command that the
apksigner
tool supports.
Sign command
The apksigner
sign command has the following options.
General options
The following options specify basic settings to apply to a signer:
--out <apk-filename>
- The location where you'd like to save the signed APK. If this option isn't provided explicitly, the APK package is signed in place, which overwrites the input APK file.
--min-sdk-version <integer>
-
The lowest Android framework API level that
apksigner
uses to confirm that the APK's signature will be verified. Higher values allow the tool to use stronger security parameters when signing the app but limit the APK's availability to devices running more recent versions of Android. By default,apksigner
uses the value of theminSdkVersion
attribute from the app's manifest file. --max-sdk-version <integer>
-
The highest Android framework API level that
apksigner
uses to confirm that the APK's signature will be verified. By default, the tool uses the highest possible API level. --rotation-min-sdk-version <integer>
- The lowest API level the APK's rotated signing key should use to produce the APK's signature. The original (unrotated) signing key for the APK will be used for all previous platform versions. By default, rotated signing keys, which are supported on devices that run Android 13 (API level 33) or higher, are used with the v3.1 signing block.
--v1-signing-enabled <true | false>
-
Determines whether
apksigner
signs the given APK package using the traditional, JAR-based signing scheme. By default, the tool uses the values of--min-sdk-version
and--max-sdk-version
to decide when to apply this signature scheme. --v2-signing-enabled <true | false>
-
Determines whether
apksigner
signs the given APK package using the APK Signature Scheme v2. By default, the tool uses the values of--min-sdk-version
and--max-sdk-version
to decide when to apply this signature scheme. --v3-signing-enabled <true | false>
-
Determines whether
apksigner
signs the given APK package using the APK Signature Scheme v3. By default, the tool uses the values of--min-sdk-version
and--max-sdk-version
to decide when to apply this signature scheme. --v4-signing-enabled <true | false | only>
-
Determines whether
apksigner
signs the given APK package using the APK Signature Scheme v4. This scheme produces a signature in a separate file (apk-name.apk.idsig
). Iftrue
and the APK is not signed, then a v2 or v3 signature is generated based on the values of--min-sdk-version
and--max-sdk-version
. The command then produces the.idsig
file based on the content of the signed APK.Use
only
to generate only the v4 signature without modifying the APK and any signatures it had before the invocation.only
fails if the APK doesn't have a v2 or v3 signature already or if the signature used a different key than the one provided for the current invocation.By default, the tool uses the values of
--min-sdk-version
and--max-sdk-version
to decide when to apply this signature scheme. -v
,--verbose
- Use the verbose output mode.
Note: If your app has been signed by a rotated signing
key on a device that runs Android 12L (API level 32) or lower, then you
must use --rotation-min-sdk-version 28
to continue signing
your app with the rotated signing key for Android 9 (API level 28).
Per-signer options
The following options specify the configuration of a particular signer. These options aren't necessary if you sign your app using only one signer.
--next-signer <signer-options>
- Used for specifying different general options for each signer.
--v1-signer-name <basename>
-
The base name for the files that comprise the JAR-based signature for the
current signer. By default,
apksigner
uses the key alias of the KeyStore or the basename of the key file for this signer.
Key and certificate options
The following options specify the signer's private key and certificate:
--ks <filename>
-
The signer's private key and certificate chain reside in the given
Java-based KeyStore file. If the filename is set to
"NONE"
, the KeyStore containing the key and certificate doesn't need a file specified, which is the case for some PKCS #11 KeyStores. --ks-key-alias <alias>
- The name of the alias that represents the signer's private key and certificate data within the KeyStore. If the KeyStore associated with the signer contains multiple keys, you must specify this option.
--ks-pass <input-format>
-
The password for the KeyStore that contains the signer's private key and certificate. You must provide a password to open a KeyStore. The
apksigner
tool supports the following formats:-
pass:<password>
– Password provided inline with the rest of theapksigner sign
command. -
env:<name>
– Password is stored in the given environment variable. -
file:<filename>
– Password is stored as a single line in the given file. -
stdin
– Password is provided as a single line in the standard input stream. This is the default behavior for--ks-pass
.
Note: If you include multiple passwords in the same file, specify them on separate lines. The
apksigner
tool associates passwords with an APK's signers based on the order in which you specify the signers. If you've provided two passwords for a signer,apksigner
interprets the first password as the KeyStore password and the second one as the key password. -
--pass-encoding <charset>
-
Includes the specified character encodings, such as
ibm437
orutf-8
, when trying to handle passwords containing non-ASCII characters.Keytool often encrypts keystores by converting the password using the console's default charset. By default,
apksigner
tries to decrypt using several forms of the password:- The Unicode form
- The form encoded using the JVM default charset
- On Java 8 and older, the form encoded using the console's default charset
On Java 9,
apksigner
cannot detect the console's charset. You may need to specify--pass-encoding
when a non-ASCII password is used. You may also need to specify this option with KeyStores that keytool created on a different OS or in a different locale. --key-pass <input-format>
-
The password for the signer's private key, which is needed if the private key is password protected. The
apksigner
tool supports the following formats:-
pass:<password>
– Password is provided inline with the rest of theapksigner sign
command. -
env:<name>
– Password is stored in the given environment variable. -
file:<filename>
– Password is stored as a single line in the given file. -
stdin
– Password is provided as a single line in the standard input stream. This is the default behavior for--key-pass
.
-
--ks-type <algorithm>
-
The type or algorithm associated with the KeyStore that contains the
signer's private key and certificate. By default,
apksigner
uses the type defined as thekeystore.type
constant in the Security properties file. --ks-provider-name <name>
-
The name of the JCA Provider to use when requesting the signer's KeyStore
implementation. By default,
apksigner
uses the highest-priority provider. --ks-provider-class <class-name>
-
The fully qualified class name of the JCA Provider to use when requesting
the signer's KeyStore implementation. This option serves as an alternative
for
--ks-provider-name
. By default,apksigner
uses the provider specified with the--ks-provider-name
option. --ks-provider-arg <value>
-
A string value to pass in as the argument for the constructor of the JCA
Provider class; the class itself is defined with the
--ks-provider-class
option. By default,apksigner
uses the class's zero-argument constructor. --key <filename>
-
The name of the file that contains the signer's private key. This file
must use the PKCS #8 DER format. If the key is password protected,
apksigner
prompts for the password using standard input unless you specify a different kind of input format using the--key-pass
option. --cert <filename>
- The name of the file that contains the signer's certificate chain. This file must use the X.509 PEM or DER format.
Verify command
The apksigner
verify command has the following options.
--print-certs
- Show information about the APK's signing certificates.
--min-sdk-version <integer>
-
The lowest Android framework API level that
apksigner
uses to confirm that the APK's signature will be verified. Higher values allow the tool to use stronger security parameters when signing the app but limit the APK's availability to devices running more recent versions of Android. By default,apksigner
uses the value of theminSdkVersion
attribute from the app's manifest file. --max-sdk-version <integer>
-
The highest Android framework API level that
apksigner
uses to confirm that the APK's signature will be verified. By default, the tool uses the highest possible API level. -v
,--verbose
- Use the verbose output mode.
-Werr
- Treat warnings as errors.
Examples
The following are examples using apksigner
.
Sign an APK
Sign an APK using release.jks
, which is the only key in the
KeyStore:
$ apksigner sign --ks release.jks app.apk
Sign an APK using a private key and certificate stored as separate files:
$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk
Sign an APK using two keys:
$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk
Sign an APK with a rotated signing key and the rotation targeting SDK version 28+:
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \ --lineage /path/to/signing/history/lineage app.apk \ --rotation-min-sdk-version 28
Sign an APK with a rotated signing key and the rotation targeting SDK version 33+:
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \ --lineage /path/to/signing/history/lineage app.apk
Verify the signature of an APK
Check whether the APK's signatures are expected to be confirmed as valid on all Android platforms that the APK supports:
$ apksigner verify app.apk
Check whether the APK's signatures are expected to be confirmed as valid on Android 4.0.3 (API level 15) and higher:
$ apksigner verify --min-sdk-version 15 app.apk
Rotate signing keys
Enable a signing certificate lineage that supports key rotation:
$ apksigner rotate --out /path/to/new/file --old-signer \ --ks release.jks --new-signer --ks release2.jks
Rotate your signing keys again:
$ apksigner rotate --in /path/to/existing/lineage \ --out /path/to/new/file --old-signer --ks release2.jks \ --new-signer --ks release3.jks