src/apksigner/java/com/android/apksigner/help_rotate.txt

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.


--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> password provided inline
                          env:<name>      password provided in the named
                                          environment variable
                          file:<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> password provided inline
                          env:<name>      password provided in the named
                                          environment variable
                          file:<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