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 50Prior to Android 12, if multiple apps shared a common signer in their signing lineage 51with distinct capabilities assigned, a bug in the platform would cause the capabilities 52declared for this signer in one of the app's signing lineage to be assigned to this same 53common signer in the lineage of the rest of the apps. Apps that use the default capabilities, 54or that assign the same capabilities to a common signer in their lineage, are not impacted 55by this bug. 56 57 58--ks Load private key and certificate chain from the Java 59 KeyStore initialized from the specified file. NONE means 60 no file is needed by KeyStore, which is the case for some 61 PKCS #11 KeyStores. 62 63--ks-key-alias Alias under which the private key and certificate are 64 stored in the KeyStore. This must be specified if the 65 KeyStore contains multiple keys. 66 67--ks-pass KeyStore password (see --ks). The following formats are 68 supported: 69 pass:<password> password provided inline 70 env:<name> password provided in the named 71 environment variable 72 file:<file> password provided in the named 73 file, as a single line 74 stdin password provided on standard input, 75 as a single line 76 A password is required to open a KeyStore. 77 By default, the tool will prompt for password via console 78 or standard input. 79 When the same file (including standard input) is used for 80 providing multiple passwords, the passwords are read from 81 the file one line at a time. Passwords are read in the 82 order of old-signer then new-signer and, within each 83 signer, KeyStore password is read before the key password 84 is read. 85 86--key-pass Password with which the private key is protected. 87 The following formats are supported: 88 pass:<password> password provided inline 89 env:<name> password provided in the named 90 environment variable 91 file:<file> password provided in the named 92 file, as a single line 93 stdin password provided on standard input, 94 as a single line 95 If --key-pass is not specified for a KeyStore key, this 96 tool will attempt to load the key using the KeyStore 97 password and, if that fails, will prompt for key password 98 and attempt to load the key using that password. 99 If --key-pass is not specified for a private key file key, 100 this tool will prompt for key password only if a password 101 is required. 102 When the same file (including standard input) is used for 103 providing multiple passwords, the passwords are read from 104 the file one line at a time. Passwords are read in the 105 order of old-signer then new-signer and, within each 106 signer, KeyStore password is read before the key password 107 is read. 108 109--pass-encoding Additional character encoding (e.g., ibm437 or utf-8) to 110 try for passwords containing non-ASCII characters. 111 KeyStores created by keytool are often encrypted not using 112 the Unicode form of the password but rather using the form 113 produced by encoding the password using the console's 114 character encoding. apksigner by default tries to decrypt 115 using several forms of the password: the Unicode form, the 116 form encoded using the JVM default charset, and, on Java 8 117 and older, the form encoded using the console's charset. 118 On Java 9, apksigner cannot detect the console's charset 119 and may need to be provided with --pass-encoding when a 120 non-ASCII password is used. --pass-encoding may also need 121 to be provided for a KeyStore created by keytool on a 122 different OS or in a different locale. 123 124--ks-type Type/algorithm of KeyStore to use. By default, the default 125 type is used. 126 127--ks-provider-name Name of the JCA Provider from which to request the 128 KeyStore implementation. By default, the highest priority 129 provider is used. See --ks-provider-class for the 130 alternative way to specify a provider. 131 132--ks-provider-class Fully-qualified class name of the JCA Provider from which 133 to request the KeyStore implementation. By default, the 134 provider is chosen based on --ks-provider-name. 135 136--ks-provider-arg Value to pass into the constructor of the JCA Provider 137 class specified by --ks-provider-class. The value is 138 passed into the constructor as java.lang.String. By 139 default, the no-arg provider's constructor is used. 140 141--key Load private key from the specified file. If the key is 142 password-protected, the password will be prompted via 143 standard input unless specified otherwise using 144 --key-pass. The file must be in PKCS #8 DER format. 145 146--cert Load certificate chain from the specified file. The file 147 must be in X.509 PEM or DER format. 148 149--set-installed-data Sets whether installed data associated with this previous 150 signing certificate should be trusted. This capability is 151 required to perform signing certificate rotation during an 152 upgrade on-device. Without it, the platform will not 153 permit the app data from the old signing certificate to 154 propogate to the new version. Typically this flag should 155 be set to enable signing certificate rotation and may be 156 unset later when the install base is as migrated as it 157 will be. 158 159--set-shared-uid Sets whether apps signed with this previous signing 160 certificate can share a UID with an app signed with the 161 new signing certificate. This is useful in situations 162 where shareUserId apps would like to change their signing 163 certificate but can not guarantee the order of updates to 164 those apps. 165 166--set-permission Sets whether apps signed with this previous signing 167 certificate can be granted SIGNATURE permissions defined 168 by an app signed with the new signing certificate. 169 170--set-rollback Sets whether the platform should allow an app to be 171 upgraded to a newer version signed with this previous 172 signing certificate. 173 WARNING: This effectively removes any benefit of signing 174 certificate rotation since a compromised key could retake 175 control of an app even after the signing certificate 176 rotation. This option should only be used if a problem is 177 encountered when attempting to rotate an older signing 178 certificate. 179 180--set-auth Sets whether apps signed with this previous signing 181 certificate should be granted privileged access by the 182 authenticator module using the new signing certificate. 183 184 185 JCA PROVIDER INSTALLATION OPTIONS 186These options enable you to install additional Java Crypto Architecture (JCA) 187Providers, such as PKCS #11 providers. Use --next-provider to delimit options of 188different providers. Providers are installed in the order in which they appear 189on the command-line. 190 191--provider-class Fully-qualified class name of the JCA Provider. 192 193--provider-arg Value to pass into the constructor of the JCA Provider 194 class specified by --provider-class. The value is passed 195 into the constructor as java.lang.String. By default, the 196 no-arg provider's constructor is used. 197 198--provider-pos Position / priority at which to install this provider in 199 the JCA provider list. By default, the provider is 200 installed as the lowest priority provider. 201 See java.security.Security.insertProviderAt. 202 203 EXAMPLES 204 2051. Create a new SigningCertificateLineage to enable rotation: 206$ apksigner rotate --out /path/to/new/file --old-signer --ks release.jks \ 207 --new-signer --ks release2.jks 208 2092. Extend an existing SigningCertificateLineage to rotate again after previous rotation: 210$ apksigner rotate --in /path/to/existing/lineage --out /path/to/new/file \ 211 --old-signer --ks release2.jks --new-signer --ks release3.jks 212 2133. Create a new SigningCertificateLineage with explicit capabilities for the previous signer: 214$ apksigner rotate --out /path/to/new/file --old-signer --ks release.jks \ 215 --set-installed-data true --set-shared-uid true --set-permission true --set-rollback false \ 216 --set-auth true --new-signer --ks release2.jks 217