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