1USAGE: apksigner lineage [options] 2 3This modifies the capabilities of one or more signers in the provided SigningCertificateLineage. 4This can be used to revoke capabilities of a previous signing certificate once the install base 5has been migrated to the new signing certificate. 6 7 8 GENERAL OPTIONS 9 10--in Input SigningCertificateLineage. This file contains a binary representation of 11 a SigningCertificateLineage object which contains the proof-of-rotation for 12 different signing certificates. 13 An APK previously signed with a SigningCertificateLineage can also be 14 specified; the lineage will then be read from the signed data in the APK. 15 16--out File into which to put the binary representation of a 17 SigningCertificateLineage object. 18 19--print-certs Show information about the signing certificates and their capabilities 20 in the SigningCertificateLineage. 21 22-v, --verbose Verbose output mode. 23 24-h, --help Show help about this command and exit. 25 26 27 PER-SIGNER OPTIONS 28This option is required for each signer to be modified in the provided SigningCertificateLineage. 29 30--signer Indicates the start of a new signing certificate to be modified. 31 32 33 PER-SIGNER SIGNING KEY, CERTIFICATE, & CAPABILITY OPTIONS 34To modify the capabilities of a previous signer in the lineage the signer's 35private key and certificate must be specified. There are two ways to provide 36the signer's private key and certificate: (1) Java KeyStore (see --ks), or 37(2) private key file in PKCS #8 format and certificate file in X.509 format 38(see --key and --cert). 39 40The --set-xx capability options allow an older signing certificate to still be 41used in some situations on the platform even though the APK is now being signed 42by a newer signing certificate. By default, the new signer will have all 43capabilities, but the capability options can be specified for the new signer 44to act as a default level of trust when moving to a newer signing certificate. 45The capability options accept an optional boolean value of true or false; if 46this value is not specified then the option will default to true. 47 48--ks Load private key and certificate chain from the Java 49 KeyStore initialized from the specified file. NONE means 50 no file is needed by KeyStore, which is the case for some 51 PKCS #11 KeyStores. 52 53--ks-key-alias Alias under which the private key and certificate are 54 stored in the KeyStore. This must be specified if the 55 KeyStore contains multiple keys. 56 57--ks-pass KeyStore password (see --ks). The following formats are 58 supported: 59 pass:<password> password provided inline 60 env:<name> password provided in the named 61 environment variable 62 file:<file> password provided in the named 63 file, as a single line 64 stdin password provided on standard input, 65 as a single line 66 A password is required to open a KeyStore. 67 By default, the tool will prompt for password via console 68 or standard input. 69 When the same file (including standard input) is used for 70 providing multiple passwords, the passwords are read from 71 the file one line at a time. Passwords are read in the 72 order of old-signer then new-signer and, within each 73 signer, KeyStore password is read before the key password 74 is read. 75 76--key-pass Password with which the private key is protected. 77 The following formats are supported: 78 pass:<password> password provided inline 79 env:<name> password provided in the named 80 environment variable 81 file:<file> password provided in the named 82 file, as a single line 83 stdin password provided on standard input, 84 as a single line 85 If --key-pass is not specified for a KeyStore key, this 86 tool will attempt to load the key using the KeyStore 87 password and, if that fails, will prompt for key password 88 and attempt to load the key using that password. 89 If --key-pass is not specified for a private key file key, 90 this tool will prompt for key password only if a password 91 is required. 92 When the same file (including standard input) is used for 93 providing multiple passwords, the passwords are read from 94 the file one line at a time. Passwords are read in the 95 order of old-signer then new-signer and, within each 96 signer, KeyStore password is read before the key password 97 is read. 98 99--pass-encoding Additional character encoding (e.g., ibm437 or utf-8) to 100 try for passwords containing non-ASCII characters. 101 KeyStores created by keytool are often encrypted not using 102 the Unicode form of the password but rather using the form 103 produced by encoding the password using the console's 104 character encoding. apksigner by default tries to decrypt 105 using several forms of the password: the Unicode form, the 106 form encoded using the JVM default charset, and, on Java 8 107 and older, the form encoded using the console's charset. 108 On Java 9, apksigner cannot detect the console's charset 109 and may need to be provided with --pass-encoding when a 110 non-ASCII password is used. --pass-encoding may also need 111 to be provided for a KeyStore created by keytool on a 112 different OS or in a different locale. 113 114--ks-type Type/algorithm of KeyStore to use. By default, the default 115 type is used. 116 117--ks-provider-name Name of the JCA Provider from which to request the 118 KeyStore implementation. By default, the highest priority 119 provider is used. See --ks-provider-class for the 120 alternative way to specify a provider. 121 122--ks-provider-class Fully-qualified class name of the JCA Provider from which 123 to request the KeyStore implementation. By default, the 124 provider is chosen based on --ks-provider-name. 125 126--ks-provider-arg Value to pass into the constructor of the JCA Provider 127 class specified by --ks-provider-class. The value is 128 passed into the constructor as java.lang.String. By 129 default, the no-arg provider's constructor is used. 130 131--key Load private key from the specified file. If the key is 132 password-protected, the password will be prompted via 133 standard input unless specified otherwise using 134 --key-pass. The file must be in PKCS #8 DER format. 135 136--cert Load certificate chain from the specified file. The file 137 must be in X.509 PEM or DER format. 138 139--set-installed-data Sets whether installed data associated with this previous 140 signing certificate should be trusted. This capability is 141 required to perform signing certificate rotation during an 142 upgrade on-device. Without it, the platform will not 143 permit the app data from the old signing certificate to 144 propogate to the new version. Typically this flag should 145 be set to enable signing certificate rotation and may be 146 unset later when the install base is as migrated as it 147 will be. 148 149--set-shared-uid Sets whether apps signed with this previous signing 150 certificate can share a UID with an app signed with the 151 new signing certificate. This is useful in situations 152 where shareUserId apps would like to change their signing 153 certificate but can not guarantee the order of updates to 154 those apps. 155 156--set-permission Sets whether apps signed with this previous signing 157 certificate can be granted SIGNATURE permissions defined 158 by an app signed with the new signing certificate. 159 160--set-rollback Sets whether the platform should allow an app to be 161 upgraded to a newer version signed with this previous 162 signing certificate. 163 WARNING: This effectively removes any benefit of signing 164 certificate rotation since a compromised key could retake 165 control of an app even after the signing certificate 166 rotation. This option should only be used if a problem is 167 encountered when attempting to rotate an older signing 168 certificate. 169 170--set-auth Sets whether apps signed with this previous signing 171 certificate should be granted privileged access by the 172 authenticator module using the new signing certificate. 173 174 175 EXAMPLES 176 1771. Remove all capabilities from a previous signer in the linage: 178$ apksigner lineage --in /path/to/existing/lineage --out /path/to/new/file \ 179 --signer --ks release.jks --set-installed-data false \ 180 --set-shared-uid false --set-permission false --set-rollback false \ 181 --set-auth false 182 1832. Display details about the signing certificates and their capabilities in the lineage: 184$ apksigner lineage --in /path/to/existing/lineage --print-certs -v 185 186