Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man7/asymmetric-key.7 @ 68:5028fdace37b

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