1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
USAGE: apksigner sign [options] apk
This signs the provided APK, stripping out any pre-existing signatures. Signing
is performed using one or more signers, each represented by an asymmetric key
pair and a corresponding certificate. Typically, an APK is signed by just one
signer. For each signer, you need to provide the signer's private key and
certificate.
GENERAL OPTIONS
--in Input APK file to sign. This is an alternative to
specifying the APK as the very last parameter, after all
options. Unless --out is specified, this file will be
overwritten with the resulting signed APK.
--out File into which to output the signed APK. By default, the
APK is signed in-place, overwriting the input file.
-v, --verbose Verbose output mode
--v1-signing-enabled Whether to enable signing using JAR signing scheme (aka v1
signing scheme) used in Android since day one. By default,
signing using this scheme is enabled based on min and max
SDK version (see --min-sdk-version and --max-sdk-version).
--v2-signing-enabled Whether to enable signing using APK Signature Scheme v2
(aka v2 signing scheme) introduced in Android Nougat,
API Level 24. By default, signing using this scheme is
enabled based on min and max SDK version (see
--min-sdk-version and --max-sdk-version).
--v3-signing-enabled Whether to enable signing using APK Signature Scheme v3
(aka v3 signing scheme) introduced in Android P,
API Level 28. By default, signing using this scheme is
enabled based on min and max SDK version (see
--min-sdk-version and --max-sdk-version). Multiple
signers are not supported when using v3 signing, but
multiple signers may be provided in conjunction with the
"lineage" option to make sure that the app is signed by
an appropriate signer on all supported platform versions.
--v4-signing-enabled Whether to enable signing using APK Signature Scheme v4
(aka v4 signing scheme) introduced in Android 11,
API Level 30. By default, signing using this scheme is
enabled based on min and max SDK version (see
--min-sdk-version and --max-sdk-version).
--force-stamp-overwrite Whether to overwrite existing source stamp in the
APK, if found. By default, it is set to false. It has no
effect if no source stamp signer config is provided.
--verity-enabled Whether to enable the verity signature algorithm for the
v2 and v3 signature schemes.
--min-sdk-version Lowest API Level on which this APK's signatures will be
verified. By default, the value from AndroidManifest.xml
is used. The higher the value, the stronger security
parameters are used when signing.
--max-sdk-version Highest API Level on which this APK's signatures will be
verified. By default, the highest possible value is used.
--rotation-min-sdk-version Lowest API Level for which an APK's rotated signing
key should be used to produce the APK's signature. The
original signing key for the APK will be used for all
previous platform versions. Specifying a value <= 32
(Android Sv2) will result in the original V3 signing block
being used without platform targeting. By default,
rotated signing keys will be used with the V3.1 signing
block which supports Android T+.
--rotation-targets-dev-release The specified rotation-min-sdk-version is intended
for a platform release under development. During development
of a new platform, the API Level of the previously released
platform is used as the API Level of the development
platform until the SDK is finalized. This flag allows
targeting signing key rotation to a development platform
with API Level X while preventing the rotated key from being
used on the latest release platform with API Level X.
--debuggable-apk-permitted Whether to permit signing android:debuggable="true"
APKs. Android disables some of its security protections
for such apps. For example, anybody with ADB shell access
can execute arbitrary code in the context of a debuggable
app and can read/write persistently stored data of the
app. It is a good security practice to not sign
debuggable APKs with production signing keys, because
such APKs puts users at risk once leaked.
By default, signing debuggable APKs is permitted, for
backward compatibility with older apksigner versions.
--lineage Signing certificate history to use in the event that
signing certificates changed for an APK using APK
Signature Scheme v3 supported signing certificate
rotation. This object may be created by the apksigner
"rotate" command. If used, all signers used to sign the
APK must be present in the signing lineage,
and if v1 or v2 signing is enabled, the first (oldest)
entry in the lineage must have a signer provided, so that
it can be used for those v1 and/or v2 signing. Multiple
signers are not supported when using APK Signature Scheme
v3, so multiple signers input will correspond to different
points in the lineage and will be used on older platform
versions when the newest signer in the lineage is
unsupported.
An APK previously signed with a SigningCertificateLineage
can also be specified; the lineage will then be read from
the signed data in the APK.
--deterministic-dsa-signing When signing with the DSA signature algorithm,
whether to use the deterministic version as specified in
RFC 6979.
--append-signature Appends the current signature to any signatures that
already exist within the APK. This option can be used
when an APK is signed by multiple independent signers to
allow each to add their own signature without needing to
share their private key. This option can also be used to
preserve existing key / value blocks that exist within the
APK signing block.
-h, --help Show help about this command and exit
PER-SIGNER OPTIONS
These options specify the configuration of a particular signer. To delimit
options of different signers, use --next-signer.
--next-signer Delimits options of two different signers. There is no
need to use this option when only one signer is used.
--v1-signer-name Basename for files comprising the JAR signature scheme
(aka v1 scheme) signature of this signer. By default,
KeyStore key alias or basename of key file is used.
--stamp-signer The signing information for the signer of the source stamp
to be included in the APK.
PER-SIGNER SIGNING KEY & CERTIFICATE OPTIONS
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).
--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 in which signers are specified 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 in which signers are specified 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.
JCA PROVIDER INSTALLATION OPTIONS
These options enable you to install additional Java Crypto Architecture (JCA)
Providers, such as PKCS #11 providers. Use --next-provider to delimit options of
different providers. Providers are installed in the order in which they appear
on the command-line.
--provider-class Fully-qualified class name of the JCA Provider.
--provider-arg Value to pass into the constructor of the JCA Provider
class specified by --provider-class. The value is passed
into the constructor as java.lang.String. By default, the
no-arg provider's constructor is used.
--provider-pos Position / priority at which to install this provider in
the JCA provider list. By default, the provider is
installed as the lowest priority provider.
See java.security.Security.insertProviderAt.
EXAMPLES
1. Sign an APK, in-place, using the one and only key in keystore release.jks:
$ apksigner sign --ks release.jks app.apk
1. Sign an APK, without overwriting, using the one and only key in keystore
release.jks:
$ apksigner sign --ks release.jks --in app.apk --out app-signed.apk
3. Sign an APK using a private key and certificate stored as individual files:
$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk
4. Sign an APK using two keys:
$ apksigner sign --ks release.jks --next-signer --ks magic.jks app.apk
5. Sign an APK using PKCS #11 JCA Provider:
$ apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 \
--provider-arg token.cfg --ks NONE --ks-type PKCS11 app.apk
6. Sign an APK using a non-ASCII password KeyStore created on English Windows.
The --pass-encoding parameter is not needed if apksigner is being run on
English Windows with Java 8 or older.
$ apksigner sign --ks release.jks --pass-encoding ibm437 app.apk
7. Sign an APK on Windows using a non-ASCII password KeyStore created on a
modern OSX or Linux machine:
$ apksigner sign --ks release.jks --pass-encoding utf-8 app.apk
8. Sign an APK with rotated signing certificate:
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
--lineage /path/to/signing/history/lineage app.apk
|
