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