apksigner

The apksigner tool, available in revision 24.0.3 and higher of the Android SDK Build Tools, allows you to sign APKs and to confirm that an APK's signature will be verified successfully on all versions of the Android platform supported by those APKs. 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 the Sign your app guide.

Caution: If you sign your APK using apksigner and make further changes to the APK, the APK's signature is invalidated. Therefore, you must use tools such as zipalign before signing your APK.

Usage

Sign an APK

The syntax for signing an APK using the apksigner tool is as follows:

  1. apksigner sign --ks keystore.jks |
  2.   --key key.pk8 --cert cert.x509.pem
  3.   [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 different 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. In the event that 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:
  1. apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

Verify the signature of an APK

The syntax for confirming that an APK's signature will be verified successfully on supported platforms is as follows:

  1. 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:

  1. $ apksigner rotate --in /path/to/existing/lineage \
  2.   --out /path/to/new/file \
  3.   --old-signer --ks old-signer-jks \
  4.   --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

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, overwriting 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 the minSdkVersion 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.
  • —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.
  • -v, —verbose
  • Use the verbose output mode.

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 the apksigner 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 or utf-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, and, on Java 8 and older, the form encoded using the console's default charset. On Java 9, apksigner cannot detect the console's charset. So, 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 provided inline with the rest of the apksigner 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.
      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.

  • —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 the keystore.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 0-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

  • —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 the minSdkVersion 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

Sign an APK

Sign an APK using release.jks, which is the only key in the KeyStore:

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

Sign an APK using a private key and certificate, stored as separate files:

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

Sign an APK using two keys:

  1. $ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks 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:

  1. $ 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:

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

Rotate signing keys

Enable a signing certificate lineage that supports key rotation:

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

Rotate your signing keys again:

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