|
jpayne@68
|
1 .\"
|
|
jpayne@68
|
2 .\" Copyright (C) 2018 Red Hat, Inc. All Rights Reserved.
|
|
jpayne@68
|
3 .\" Written by David Howells (dhowells@redhat.com)
|
|
jpayne@68
|
4 .\"
|
|
jpayne@68
|
5 .\" This program is free software; you can redistribute it and/or
|
|
jpayne@68
|
6 .\" modify it under the terms of the GNU General Public Licence
|
|
jpayne@68
|
7 .\" as published by the Free Software Foundation; either version
|
|
jpayne@68
|
8 .\" 2 of the Licence, or (at your option) any later version.
|
|
jpayne@68
|
9 .\"
|
|
jpayne@68
|
10 .TH ASYMMETRIC-KEY 7 "8 Nov 2018" Linux "Asymmetric Kernel Key Type"
|
|
jpayne@68
|
11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
12 .SH NAME
|
|
jpayne@68
|
13 asymmetric \- Kernel key type for holding asymmetric keys
|
|
jpayne@68
|
14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
15 .SH OVERVIEW
|
|
jpayne@68
|
16 .PP
|
|
jpayne@68
|
17 A kernel key of
|
|
jpayne@68
|
18 .B asymmetric
|
|
jpayne@68
|
19 type acts as a handle to an asymmetric key as used for public-key
|
|
jpayne@68
|
20 cryptography. The key material itself may be held inside the kernel or it may
|
|
jpayne@68
|
21 be held in hardware with operations being offloaded. This prevents direct
|
|
jpayne@68
|
22 user access to the cryptographic material.
|
|
jpayne@68
|
23 .PP
|
|
jpayne@68
|
24 Keys may be any asymmetric type (RSA, ECDSA, ...) and may have both private and
|
|
jpayne@68
|
25 public components present or just the public component.
|
|
jpayne@68
|
26 .PP
|
|
jpayne@68
|
27 Asymmetric keys can be made use of by both the kernel and userspace. The
|
|
jpayne@68
|
28 kernel can make use of them for module signature verification and kexec image
|
|
jpayne@68
|
29 verification for example. Userspace is provided with a set of
|
|
jpayne@68
|
30 .BR keyctl ( KEYCTL_PKEY_* )
|
|
jpayne@68
|
31 calls for querying and using the key. These are wrapped by
|
|
jpayne@68
|
32 .B libkeyutils
|
|
jpayne@68
|
33 as functions named
|
|
jpayne@68
|
34 .BR keyctl_pkey_*() .
|
|
jpayne@68
|
35 .PP
|
|
jpayne@68
|
36 An asymmetric-type key can be loaded by the keyctl utility using a command
|
|
jpayne@68
|
37 line like:
|
|
jpayne@68
|
38 .PP
|
|
jpayne@68
|
39 .in +4n
|
|
jpayne@68
|
40 .EX
|
|
jpayne@68
|
41 openssl x509 -in key.x509 -outform DER |
|
|
jpayne@68
|
42 keyctl padd asymmetric foo @s
|
|
jpayne@68
|
43 .EE
|
|
jpayne@68
|
44 .in
|
|
jpayne@68
|
45 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
46 .SH DESCRIPTION
|
|
jpayne@68
|
47 .PP
|
|
jpayne@68
|
48 The asymmetric-type key can be viewed as a container that comprises of a
|
|
jpayne@68
|
49 number of components:
|
|
jpayne@68
|
50 .TP
|
|
jpayne@68
|
51 Parsers
|
|
jpayne@68
|
52 The asymmetric key parsers attempt to identify the content of the payload blob
|
|
jpayne@68
|
53 and extract useful data from it with which to instantiate the key. The parser
|
|
jpayne@68
|
54 is only used when adding, instantiating or updating a key and isn't thereafter
|
|
jpayne@68
|
55 associated with the key.
|
|
jpayne@68
|
56 .IP
|
|
jpayne@68
|
57 Available parsers include ones that can deal with
|
|
jpayne@68
|
58 .RB "DER-encoded " X.509 ", DER-encoded " PKCS#8 " and DER-encoded " TPM "-wrapped blobs."
|
|
jpayne@68
|
59 .TP
|
|
jpayne@68
|
60 Public and private keys
|
|
jpayne@68
|
61 These are the cryptographic components of the key pair. The public half
|
|
jpayne@68
|
62 should always be available, but the private half might not be. What
|
|
jpayne@68
|
63 operations are available can be queried, as can the size of the key. The key
|
|
jpayne@68
|
64 material may or may not actually reside in the kernel.
|
|
jpayne@68
|
65 .TP
|
|
jpayne@68
|
66 Identifiers
|
|
jpayne@68
|
67 In addition to the normal key description (which can be generated by the
|
|
jpayne@68
|
68 parser), a number of supplementary identifiers may be available that can be
|
|
jpayne@68
|
69 searched for. These may be obtained, for example, by hashing the public key
|
|
jpayne@68
|
70 material or from the subjectKeyIdentifier in an X.509 certificate.
|
|
jpayne@68
|
71 .IP
|
|
jpayne@68
|
72 Identifier-based searches are selected by passing as the description to
|
|
jpayne@68
|
73 .BR keyctl_search ()
|
|
jpayne@68
|
74 a string constructed of hex characters prefixed with either "id:" or "ex:".
|
|
jpayne@68
|
75 The "id:" prefix indicates that a partial tail match is permissible whereas
|
|
jpayne@68
|
76 "ex:" requires an exact match on the full string. The hex characters indicate
|
|
jpayne@68
|
77 the data to match.
|
|
jpayne@68
|
78 .TP
|
|
jpayne@68
|
79 Subtype
|
|
jpayne@68
|
80 This is the driver inside the kernel that accesses the key material and
|
|
jpayne@68
|
81 performs operations on it. It might be entirely software-based or it may
|
|
jpayne@68
|
82 offload the operations to a hardware key store, such as a
|
|
jpayne@68
|
83 .BR TPM .
|
|
jpayne@68
|
84 .PP
|
|
jpayne@68
|
85 Note that expiry times from the payload are ignored as these patches may be
|
|
jpayne@68
|
86 used during boot before the system clock is set.
|
|
jpayne@68
|
87 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
88 .SH PARSERS
|
|
jpayne@68
|
89 .PP
|
|
jpayne@68
|
90 The asymmetric key parsers can handle keys in a number of forms:
|
|
jpayne@68
|
91 .TP
|
|
jpayne@68
|
92 \fBX.509\fP
|
|
jpayne@68
|
93 DER-encoded X.509 certificates can be accepted. Two identifiers are
|
|
jpayne@68
|
94 constructed: one from from the certificate issuer and serial number and the
|
|
jpayne@68
|
95 other from the subjectKeyIdentifier, if present. If left blank, the key
|
|
jpayne@68
|
96 description will be filled in from the subject field plus either the
|
|
jpayne@68
|
97 subjectKeyIdentifier or the serialNumber. Only the public key is filled in
|
|
jpayne@68
|
98 and only the encrypt and verify operations are supported.
|
|
jpayne@68
|
99 .IP
|
|
jpayne@68
|
100 The signature on the X.509 certificate may be checked by the keyring it is
|
|
jpayne@68
|
101 being added to and it may also be rejected if the key is blacklisted.
|
|
jpayne@68
|
102 .TP
|
|
jpayne@68
|
103 \fBPKCS#8\fP
|
|
jpayne@68
|
104 Unencrypted DER-encoded PKCS#8 key data containers can be accepted. Currently
|
|
jpayne@68
|
105 no identifiers are constructed. The private key and the public key are loaded
|
|
jpayne@68
|
106 from the PKCS#8 blobs. Encrypted PKCS#8 is not currently supported.
|
|
jpayne@68
|
107 .TP
|
|
jpayne@68
|
108 \fBTPM-Wrapped keys\fP
|
|
jpayne@68
|
109 DER-encoded TPM-wrapped TSS key blobs can be accepted. Currently no
|
|
jpayne@68
|
110 identifiers are constructed. The public key is extracted from the blob but
|
|
jpayne@68
|
111 the private key is expected to be resident in the TPM. Encryption and
|
|
jpayne@68
|
112 signature verification is done in software, but decryption and signing are
|
|
jpayne@68
|
113 offloaded to the TPM so as not to expose the private key.
|
|
jpayne@68
|
114 .IP
|
|
jpayne@68
|
115 This parser only supports TPM-1.2 wrappings and enc=pkcs1 encoding type. It
|
|
jpayne@68
|
116 also uses a hard-coded null SRK password; password-protected SRKs are not yet
|
|
jpayne@68
|
117 supported.
|
|
jpayne@68
|
118 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
119 .SH USERSPACE API
|
|
jpayne@68
|
120 .PP
|
|
jpayne@68
|
121 In addition to the standard keyutils library functions, such as
|
|
jpayne@68
|
122 .IR keyctl_update (),
|
|
jpayne@68
|
123 there are five calls specific to the asymmetric key type (though they are open
|
|
jpayne@68
|
124 to being used by other key types also):
|
|
jpayne@68
|
125 .PP
|
|
jpayne@68
|
126 .RS
|
|
jpayne@68
|
127 \fIkeyctl_pkey_query\fP()
|
|
jpayne@68
|
128 .br
|
|
jpayne@68
|
129 \fIkeyctl_pkey_encrypt\fP()
|
|
jpayne@68
|
130 .br
|
|
jpayne@68
|
131 \fIkeyctl_pkey_decrypt\fP()
|
|
jpayne@68
|
132 .br
|
|
jpayne@68
|
133 \fIkeyctl_pkey_sign\fP()
|
|
jpayne@68
|
134 .br
|
|
jpayne@68
|
135 \fIkeyctl_pkey_verify\fP()
|
|
jpayne@68
|
136 .RE
|
|
jpayne@68
|
137 .PP
|
|
jpayne@68
|
138 The query function can be used to retrieve information about an asymmetric key,
|
|
jpayne@68
|
139 such as the key size, the amount of space required by buffers for the other
|
|
jpayne@68
|
140 operations and which operations are actually supported.
|
|
jpayne@68
|
141 .PP
|
|
jpayne@68
|
142 The other operations form two pairs: encrypt/decrypt and create/verify
|
|
jpayne@68
|
143 signature. Not all of these operations will necessarily be available;
|
|
jpayne@68
|
144 typically, encrypt and verify only require the public key to be available
|
|
jpayne@68
|
145 whereas decrypt and sign require the private key as well.
|
|
jpayne@68
|
146 .PP
|
|
jpayne@68
|
147 All of these operations take an information string parameter that supplies
|
|
jpayne@68
|
148 additional information such as encoding type/form and the password(s) needed to
|
|
jpayne@68
|
149 unlock/unwrap the key. This takes the form of a comma-separated list of
|
|
jpayne@68
|
150 "key[=value]" pairs, the exact set of which depends on the subtype driver used
|
|
jpayne@68
|
151 by a particular key.
|
|
jpayne@68
|
152 .PP
|
|
jpayne@68
|
153 Available parameters include:
|
|
jpayne@68
|
154 .TP
|
|
jpayne@68
|
155 enc=<type>
|
|
jpayne@68
|
156 The encoding type for use in an encrypted blob or a signature. An example
|
|
jpayne@68
|
157 might be "enc=pkcs1".
|
|
jpayne@68
|
158 .TP
|
|
jpayne@68
|
159 hash=<name>
|
|
jpayne@68
|
160 The name of the hash algorithm that was used to digest the data to be signed.
|
|
jpayne@68
|
161 Note that this is only used to construct any encoding that is used in a
|
|
jpayne@68
|
162 signature. The data to be signed or verified must have been parsed by the
|
|
jpayne@68
|
163 caller and the hash passed to \fIkeyctl_pkey_sign\fP() or
|
|
jpayne@68
|
164 \fIkeyctl_pkey_verify\fP() beforehand. An example might be "hash=sha256".
|
|
jpayne@68
|
165 .PP
|
|
jpayne@68
|
166 Note that not all parameters are used by all subtypes.
|
|
jpayne@68
|
167 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
168 .SH RESTRICTED KEYRINGS
|
|
jpayne@68
|
169 .PP
|
|
jpayne@68
|
170 An additional keyutils function,
|
|
jpayne@68
|
171 .IR keyctl_restrict_keyring (),
|
|
jpayne@68
|
172 can be used to gate a keyring so that a new key can only be added to the
|
|
jpayne@68
|
173 affected keyring if (a) it's an asymmetric key, (b) it's validly signed by a
|
|
jpayne@68
|
174 key in some appropriate keyring and (c) it's not blacklisted.
|
|
jpayne@68
|
175 .PP
|
|
jpayne@68
|
176 .in +4n
|
|
jpayne@68
|
177 .EX
|
|
jpayne@68
|
178 keyctl_restrict_keyring(keyring, "asymmetric",
|
|
jpayne@68
|
179 "key_or_keyring:<signing-key>[:chain]");
|
|
jpayne@68
|
180 .EE
|
|
jpayne@68
|
181 .in
|
|
jpayne@68
|
182 .PP
|
|
jpayne@68
|
183 Where \fI<signing-key>\fP is the ID of a key or a ring of keys that act as the
|
|
jpayne@68
|
184 authority to permit a new key to be added to the keyring. The \fIchain\fP flag
|
|
jpayne@68
|
185 indicates that keys that have been added to the keyring may also be used to
|
|
jpayne@68
|
186 verify new keys. Authorising keys must themselves be asymmetric-type keys that
|
|
jpayne@68
|
187 can be used to do a signature verification on the key being added.
|
|
jpayne@68
|
188 .PP
|
|
jpayne@68
|
189 Note that there are various system keyrings visible to the root user that may
|
|
jpayne@68
|
190 permit additional keys to be added. These are typically gated by keys that
|
|
jpayne@68
|
191 already exist, preventing unauthorised keys from being used for such things as
|
|
jpayne@68
|
192 module verification.
|
|
jpayne@68
|
193 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
194 .SH BLACKLISTING
|
|
jpayne@68
|
195 .PP
|
|
jpayne@68
|
196 When the attempt is made to add a key to the kernel, a hash of the public key
|
|
jpayne@68
|
197 is checked against the
|
|
jpayne@68
|
198 .BR blacklist.
|
|
jpayne@68
|
199 This is a system keyring named
|
|
jpayne@68
|
200 .B .blacklist
|
|
jpayne@68
|
201 and contains keys of type
|
|
jpayne@68
|
202 .BR blacklist .
|
|
jpayne@68
|
203 If the blacklist contains a key whose description matches the hash of the new
|
|
jpayne@68
|
204 key, that new key will be rejected with error
|
|
jpayne@68
|
205 .BR EKEYREJECTED .
|
|
jpayne@68
|
206 .PP
|
|
jpayne@68
|
207 The blacklist keyring may be loaded from multiple sources, including a list
|
|
jpayne@68
|
208 compiled into the kernel and the UEFI
|
|
jpayne@68
|
209 .B dbx
|
|
jpayne@68
|
210 variable. Further hashes may also be blacklisted by the administrator. Note
|
|
jpayne@68
|
211 that blacklisting is not retroactive, so an asymmetric key that is already on
|
|
jpayne@68
|
212 the system cannot be blacklisted by adding a matching blacklist entry later.
|
|
jpayne@68
|
213 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
214 .SH VERSIONS
|
|
jpayne@68
|
215 The
|
|
jpayne@68
|
216 .B asymmetric
|
|
jpayne@68
|
217 key type first appeared in v3.7 of the Linux kernel, the
|
|
jpayne@68
|
218 .B restriction
|
|
jpayne@68
|
219 function in v4.11 and the
|
|
jpayne@68
|
220 .B public key operations
|
|
jpayne@68
|
221 in v4.20.
|
|
jpayne@68
|
222 .SH SEE ALSO
|
|
jpayne@68
|
223 .ad l
|
|
jpayne@68
|
224 .nh
|
|
jpayne@68
|
225 .BR keyctl (1),
|
|
jpayne@68
|
226 .BR add_key (2),
|
|
jpayne@68
|
227 .BR keyctl (3),
|
|
jpayne@68
|
228 .BR keyctl_pkey_encrypt (3),
|
|
jpayne@68
|
229 .BR keyctl_pkey_query (3),
|
|
jpayne@68
|
230 .BR keyctl_pkey_sign (3),
|
|
jpayne@68
|
231 .BR keyrings (7),
|
|
jpayne@68
|
232 .BR keyutils (7)
|
