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
|
USAGE: apksigner lineage [options]
This modifies the capabilities of one or more signers in the provided SigningCertificateLineage.
This can be used to revoke capabilities of a previous signing certificate once the install base
has been migrated to the new signing certificate.
GENERAL OPTIONS
--in Input SigningCertificateLineage. This file contains a binary representation of
a SigningCertificateLineage object which contains the proof-of-rotation for
different signing certificates.
An APK previously signed with a SigningCertificateLineage can also be
specified; the lineage will then be read from the signed data in the APK.
--out File into which to put the binary representation of a
SigningCertificateLineage object.
--print-certs Show information about the signing certificates and their capabilities
in the SigningCertificateLineage.
--print-certs-pem Show information about the signing certificates and their capabilities
in the SigningCertificateLineage; prints the PEM encoding of each signing
certificate to stdout.
-v, --verbose Verbose output mode.
-h, --help Show help about this command and exit.
PER-SIGNER OPTIONS
This option is required for each signer to be modified in the provided SigningCertificateLineage.
--signer Indicates the start of a new signing certificate to be modified.
PER-SIGNER SIGNING KEY, CERTIFICATE, & CAPABILITY OPTIONS
To modify the capabilities of a previous signer in the lineage the signer's
private key and certificate must be specified. 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).
The --set-xx capability options allow an older signing certificate to still be
used in some situations on the platform even though the APK is now being signed
by a newer signing certificate. By default, the new signer will have all
capabilities, but the capability options can be specified for the new signer
to act as a default level of trust when moving to a newer signing certificate.
The capability options accept an optional boolean value of true or false; if
this value is not specified then the option will default to true.
--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 of old-signer then new-signer 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 of old-signer then new-signer 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.
--set-installed-data Sets whether installed data associated with this previous
signing certificate should be trusted. This capability is
required to perform signing certificate rotation during an
upgrade on-device. Without it, the platform will not
permit the app data from the old signing certificate to
propogate to the new version. Typically this flag should
be set to enable signing certificate rotation and may be
unset later when the install base is as migrated as it
will be.
--set-shared-uid Sets whether apps signed with this previous signing
certificate can share a UID with an app signed with the
new signing certificate. This is useful in situations
where shareUserId apps would like to change their signing
certificate but can not guarantee the order of updates to
those apps.
--set-permission Sets whether apps signed with this previous signing
certificate can be granted SIGNATURE permissions defined
by an app signed with the new signing certificate.
--set-rollback Sets whether the platform should allow an app to be
upgraded to a newer version signed with this previous
signing certificate.
WARNING: This effectively removes any benefit of signing
certificate rotation since a compromised key could retake
control of an app even after the signing certificate
rotation. This option should only be used if a problem is
encountered when attempting to rotate an older signing
certificate.
--set-auth Sets whether apps signed with this previous signing
certificate should be granted privileged access by the
authenticator module using the new signing certificate.
EXAMPLES
1. Remove all capabilities from a previous signer in the linage:
$ apksigner lineage --in /path/to/existing/lineage --out /path/to/new/file \
--signer --ks release.jks --set-installed-data false \
--set-shared-uid false --set-permission false --set-rollback false \
--set-auth false
2. Display details about the signing certificates and their capabilities in the lineage:
$ apksigner lineage --in /path/to/existing/lineage --print-certs -v
|
