USAGE: apksigner rotate [options] This takes the provided keys and creates a SigningCertificateLineage entry linking the old to the new, for use in a key rotation scenario using APK Signature Scheme v3. GENERAL OPTIONS --in Input SigningCertificateLineage. This file contains a binary representation of a SigningCertificateLineage object, which contains the proof-of-rotation for different signing certificates. This can be used with APK Signature Scheme v3 to rotate the signing certificate for an APK. An APK previously signed with a SigningCertificateLineage can also be specified; the lineage will then be read from the signed data in the APK. --out File into which to put the binary representation of a SigningCertificateLineage object. -v, --verbose Verbose output mode -h, --help Show help about this command and exit PER-SIGNER OPTIONS These options specify the configuration of a particular signer. To rotate keys, two signers must be specified, an old and a new. --old-signer The signing information for the signer from which to be rotated. This will be used to sign a new entry in the SigningCertificateLineage allowing the addition of the new-signer. If an input SigningCertificateLineage object was provided, this signer must match the leaf descendant so that the existing signing certificate history may be extended. --new-signer The signing information for the signer to which you want to rotate. This will be the last key in the SigningCertificate object, signed by the old-signer. PER-SIGNER SIGNING KEY, CERTIFICATE, & CAPABILITY OPTIONS There are two ways to provide the signer's private key and certificate: (1) Java KeyStore (see --ks), or (2) private key file in PKCS #8 format and certificate file in X.509 format (see --key and --cert). The --set-xx capability options allow an older signing certificate to still be used in some situations on the platform even though the APK is now being signed by a newer signing certificate. By default, the new signer will have all capabilities, but the capability options can be specified for the new signer during rotation to act as a default level of trust when moving to a newer signing certificate. The capability options accept an optional boolean value of true or false; if this value is not specified then the option will default to true. Prior to Android 12, if multiple apps shared a common signer in their signing lineage with distinct capabilities assigned, a bug in the platform would cause the capabilities declared for this signer in one of the app's signing lineage to be assigned to this same common signer in the lineage of the rest of the apps. Apps that use the default capabilities, or that assign the same capabilities to a common signer in their lineage, are not impacted by this bug. --ks Load private key and certificate chain from the Java KeyStore initialized from the specified file. NONE means no file is needed by KeyStore, which is the case for some PKCS #11 KeyStores. --ks-key-alias Alias under which the private key and certificate are stored in the KeyStore. This must be specified if the KeyStore contains multiple keys. --ks-pass KeyStore password (see --ks). The following formats are supported: pass: password provided inline env: password provided in the named environment variable file: password provided in the named file, as a single line stdin password provided on standard input, as a single line A password is required to open a KeyStore. By default, the tool will prompt for password via console or standard input. When the same file (including standard input) is used for providing multiple passwords, the passwords are read from the file one line at a time. Passwords are read in the order of old-signer then new-signer and, within each signer, KeyStore password is read before the key password is read. --key-pass Password with which the private key is protected. The following formats are supported: pass: password provided inline env: password provided in the named environment variable file: password provided in the named file, as a single line stdin password provided on standard input, as a single line If --key-pass is not specified for a KeyStore key, this tool will attempt to load the key using the KeyStore password and, if that fails, will prompt for key password and attempt to load the key using that password. If --key-pass is not specified for a private key file key, this tool will prompt for key password only if a password is required. When the same file (including standard input) is used for providing multiple passwords, the passwords are read from the file one line at a time. Passwords are read in the order of old-signer then new-signer and, within each signer, KeyStore password is read before the key password is read. --pass-encoding Additional character encoding (e.g., ibm437 or utf-8) to try for passwords containing non-ASCII characters. KeyStores created by keytool are often encrypted not using the Unicode form of the password but rather using the form produced by encoding the password using the console's character encoding. apksigner by default 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 charset. On Java 9, apksigner cannot detect the console's charset and may need to be provided with --pass-encoding when a non-ASCII password is used. --pass-encoding may also need to be provided for a KeyStore created by keytool on a different OS or in a different locale. --ks-type Type/algorithm of KeyStore to use. By default, the default type is used. --ks-provider-name Name of the JCA Provider from which to request the KeyStore implementation. By default, the highest priority provider is used. See --ks-provider-class for the alternative way to specify a provider. --ks-provider-class Fully-qualified class name of the JCA Provider from which to request the KeyStore implementation. By default, the provider is chosen based on --ks-provider-name. --ks-provider-arg Value to pass into the constructor of the JCA Provider class specified by --ks-provider-class. The value is passed into the constructor as java.lang.String. By default, the no-arg provider's constructor is used. --key Load private key from the specified file. If the key is password-protected, the password will be prompted via standard input unless specified otherwise using --key-pass. The file must be in PKCS #8 DER format. --cert Load certificate chain from the specified file. The file must be in X.509 PEM or DER format. --set-installed-data Sets whether installed data associated with this previous signing certificate should be trusted. This capability is required to perform signing certificate rotation during an upgrade on-device. Without it, the platform will not permit the app data from the old signing certificate to propogate to the new version. Typically this flag should be set to enable signing certificate rotation and may be unset later when the install base is as migrated as it will be. --set-shared-uid Sets whether apps signed with this previous signing certificate can share a UID with an app signed with the new signing certificate. This is useful in situations where shareUserId apps would like to change their signing certificate but can not guarantee the order of updates to those apps. --set-permission Sets whether apps signed with this previous signing certificate can be granted SIGNATURE permissions defined by an app signed with the new signing certificate. --set-rollback Sets whether the platform should allow an app to be upgraded to a newer version signed with this previous signing certificate. WARNING: This effectively removes any benefit of signing certificate rotation since a compromised key could retake control of an app even after the signing certificate rotation. This option should only be used if a problem is encountered when attempting to rotate an older signing certificate. --set-auth Sets whether apps signed with this previous signing certificate should be granted privileged access by the authenticator module using the new signing certificate. JCA PROVIDER INSTALLATION OPTIONS These options enable you to install additional Java Crypto Architecture (JCA) Providers, such as PKCS #11 providers. Use --next-provider to delimit options of different providers. Providers are installed in the order in which they appear on the command-line. --provider-class Fully-qualified class name of the JCA Provider. --provider-arg Value to pass into the constructor of the JCA Provider class specified by --provider-class. The value is passed into the constructor as java.lang.String. By default, the no-arg provider's constructor is used. --provider-pos Position / priority at which to install this provider in the JCA provider list. By default, the provider is installed as the lowest priority provider. See java.security.Security.insertProviderAt. EXAMPLES 1. Create a new SigningCertificateLineage to enable rotation: $ apksigner rotate --out /path/to/new/file --old-signer --ks release.jks \ --new-signer --ks release2.jks 2. Extend an existing SigningCertificateLineage to rotate again after previous rotation: $ apksigner rotate --in /path/to/existing/lineage --out /path/to/new/file \ --old-signer --ks release2.jks --new-signer --ks release3.jks 3. Create a new SigningCertificateLineage with explicit capabilities for the previous signer: $ apksigner rotate --out /path/to/new/file --old-signer --ks release.jks \ --set-installed-data true --set-shared-uid true --set-permission true --set-rollback false \ --set-auth true --new-signer --ks release2.jks