| USAGE: apksigner lineage [options] |
| |
| This modifies the capabilities of one or more signers in the provided SigningCertificateLineage. |
| This can be used to revoke capabilities of a previous signing certificate once the install base |
| has been migrated to the new signing certificate. |
| |
| |
| 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. |
| 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. |
| |
| --print-certs Show information about the signing certificates and their capabilities |
| in the SigningCertificateLineage. |
| |
| -v, --verbose Verbose output mode. |
| |
| -h, --help Show help about this command and exit. |
| |
| |
| PER-SIGNER OPTIONS |
| This option is required for each signer to be modified in the provided SigningCertificateLineage. |
| |
| --signer Indicates the start of a new signing certificate to be modified. |
| |
| |
| PER-SIGNER SIGNING KEY, CERTIFICATE, & CAPABILITY OPTIONS |
| To modify the capabilities of a previous signer in the lineage the signer's |
| private key and certificate must be specified. 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 |
| 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. |
| |
| |
| EXAMPLES |
| |
| 1. Remove all capabilities from a previous signer in the linage: |
| $ apksigner lineage --in /path/to/existing/lineage --out /path/to/new/file \ |
| --signer --ks release.jks --set-installed-data false \ |
| --set-shared-uid false --set-permission false --set-rollback false \ |
| --set-auth false |
| |
| 2. Display details about the signing certificates and their capabilities in the lineage: |
| $ apksigner lineage --in /path/to/existing/lineage --print-certs -v |
| |
