asymmetric-key(7)

1ASYMMETRIC-KEY(7)         Asymmetric Kernel Key Type         ASYMMETRIC-KEY(7)
2
3
4

NAME

6       asymmetric - Kernel key type for holding asymmetric keys
7

OVERVIEW

9       A  kernel  key of asymmetric type acts as a handle to an asymmetric key
10       as used for public-key cryptography.  The key material  itself  may  be
11       held  inside  the  kernel or it may be held in hardware with operations
12       being offloaded.  This prevents direct user access to the cryptographic
13       material.
14
15       Keys  may  be  any  asymmetric type (RSA, ECDSA, ...) and may have both
16       private and public components present or just the public component.
17
18       Asymmetric keys can be made use of by both the  kernel  and  userspace.
19       The  kernel  can make use of them for module signature verification and
20       kexec image verification for example.  Userspace is provided with a set
21       of  keyctl(KEYCTL_PKEY_*)  calls for querying and using the key.  These
22       are wrapped by libkeyutils as functions named keyctl_pkey_*().
23
24       An asymmetric-type key can be loaded by the keyctl utility using a com‐
25       mand line like:
26
27           openssl x509 -in key.x509 -outform DER |
28           keyctl padd asymmetric foo @s
29

DESCRIPTION

31       The  asymmetric-type key can be viewed as a container that comprises of
32       a number of components:
33
34       Parsers
35              The asymmetric key parsers attempt to identify  the  content  of
36              the  payload  blob and extract useful data from it with which to
37              instantiate the key.  The  parser  is  only  used  when  adding,
38              instantiating  or updating a key and isn't thereafter associated
39              with the key.
40
41              Available parsers include ones that can  deal  with  DER-encoded
42              X.509, DER-encoded PKCS#8 and DER-encoded TPM-wrapped blobs.
43
44       Public and private keys
45              These  are  the  cryptographic  components of the key pair.  The
46              public half should always be available,  but  the  private  half
47              might  not be.  What operations are available can be queried, as
48              can the size of the key.  The key material may or may not  actu‐
49              ally reside in the kernel.
50
51       Identifiers
52              In  addition  to the normal key description (which can be gener‐
53              ated by the parser), a number of supplementary  identifiers  may
54              be  available  that can be searched for.  These may be obtained,
55              for example, by hashing the public key material or from the sub‐
56              jectKeyIdentifier in an X.509 certificate.
57
58              Identifier-based   searches  are  selected  by  passing  as  the
59              description to keyctl_search() a string constructed of hex char‐
60              acters  prefixed  with  either "id:" or "ex:".  The "id:" prefix
61              indicates that a partial tail match is permissible whereas "ex:"
62              requires  an exact match on the full string.  The hex characters
63              indicate the data to match.
64
65       Subtype
66              This is the driver inside the kernel that accesses the key mate‐
67              rial  and performs operations on it.  It might be entirely soft‐
68              ware-based or it may offload the operations to  a  hardware  key
69              store, such as a TPM.
70
71       Note  that  expiry  times from the payload are ignored as these patches
72       may be used during boot before the system clock is set.
73

PARSERS

75       The asymmetric key parsers can handle keys in a number of forms:
76
77       X.509  DER-encoded X.509 certificates can be accepted.  Two identifiers
78              are constructed: one from from the certificate issuer and serial
79              number and the other from the subjectKeyIdentifier, if  present.
80              If  left  blank,  the key description will be filled in from the
81              subject field plus either the subjectKeyIdentifier or the  seri‐
82              alNumber.  Only the public key is filled in and only the encrypt
83              and verify operations are supported.
84
85              The signature on the X.509 certificate may  be  checked  by  the
86              keyring  it is being added to and it may also be rejected if the
87              key is blacklisted.
88
89       PKCS#8 Unencrypted  DER-encoded  PKCS#8  key  data  containers  can  be
90              accepted.   Currently  no identifiers are constructed.  The pri‐
91              vate key and the public key are loaded from  the  PKCS#8  blobs.
92              Encrypted PKCS#8 is not currently supported.
93
94       TPM-Wrapped keys
95              DER-encoded  TPM-wrapped  TSS  key  blobs can be accepted.  Cur‐
96              rently no  identifiers  are  constructed.   The  public  key  is
97              extracted  from  the  blob but the private key is expected to be
98              resident in the TPM.  Encryption and signature  verification  is
99              done  in  software,  but decryption and signing are offloaded to
100              the TPM so as not to expose the private key.
101
102              This parser only supports TPM-1.2 wrappings and enc=pkcs1 encod‐
103              ing  type.   It  also uses a hard-coded null SRK password; pass‐
104              word-protected SRKs are not yet supported.
105

USERSPACE API

107       In addition  to  the  standard  keyutils  library  functions,  such  as
108       keyctl_update(),  there  are  five calls specific to the asymmetric key
109       type (though they are open to being used by other key types also):
110
111              keyctl_pkey_query()
112              keyctl_pkey_encrypt()
113              keyctl_pkey_decrypt()
114              keyctl_pkey_sign()
115              keyctl_pkey_verify()
116
117       The query function can be used to retrieve information about  an  asym‐
118       metric  key, such as the key size, the amount of space required by buf‐
119       fers for the other operations and which operations  are  actually  sup‐
120       ported.
121
122       The  other operations form two pairs: encrypt/decrypt and create/verify
123       signature.  Not all of these operations will necessarily be  available;
124       typically,  encrypt and verify only require the public key to be avail‐
125       able whereas decrypt and sign require the private key as well.
126
127       All of these operations take an information string parameter that  sup‐
128       plies  additional  information such as encoding type/form and the pass‐
129       word(s) needed to unlock/unwrap the key.  This  takes  the  form  of  a
130       comma-separated  list  of  "key[=value]"  pairs, the exact set of which
131       depends on the subtype driver used by a particular key.
132
133       Available parameters include:
134
135       enc=<type>
136              The encoding type for use in an encrypted blob or  a  signature.
137              An example might be "enc=pkcs1".
138
139       hash=<name>
140              The  name of the hash algorithm that was used to digest the data
141              to be signed.  Note that this is  only  used  to  construct  any
142              encoding  that is used in a signature.  The data to be signed or
143              verified must have been parsed by the caller and the hash passed
144              to  keyctl_pkey_sign()  or  keyctl_pkey_verify() beforehand.  An
145              example might be "hash=sha256".
146
147       Note that not all parameters are used by all subtypes.
148

RESTRICTED KEYRINGS

150       An additional keyutils function, keyctl_restrict_keyring(), can be used
151       to  gate  a keyring so that a new key can only be added to the affected
152       keyring if (a) it's an asymmetric key, (b) it's validly signed by a key
153       in some appropriate keyring and (c) it's not blacklisted.
154
155            keyctl_restrict_keyring(keyring, "asymmetric",
156                                    "key_or_keyring:<signing-key>[:chain]");
157
158       Where  <signing-key>  is  the ID of a key or a ring of keys that act as
159       the authority to permit a new key to be  added  to  the  keyring.   The
160       chain  flag indicates that keys that have been added to the keyring may
161       also be used to verify new keys.  Authorising keys must  themselves  be
162       asymmetric-type keys that can be used to do a signature verification on
163       the key being added.
164
165       Note that there are various system keyrings visible to  the  root  user
166       that may permit additional keys to be added.  These are typically gated
167       by keys that already exist, preventing  unauthorised  keys  from  being
168       used for such things as module verification.
169

BLACKLISTING

171       When the attempt is made to add a key to the kernel, a hash of the pub‐
172       lic key is checked against the blacklist.  This  is  a  system  keyring
173       named .blacklist and contains keys of type blacklist.  If the blacklist
174       contains a key whose description matches the hash of the new key,  that
175       new key will be rejected with error EKEYREJECTED.
176
177       The  blacklist keyring may be loaded from multiple sources, including a
178       list compiled into the kernel  and  the  UEFI  dbx  variable.   Further
179       hashes  may also be blacklisted by the administrator.  Note that black‐
180       listing is not retroactive, so an asymmetric key that is already on the
181       system  cannot  be  blacklisted  by  adding  a matching blacklist entry
182       later.
183

VERSIONS

185       The asymmetric key type first appeared in v3.7 of the Linux kernel, the
186       restriction function in v4.11 and the public key operations in v4.20.
187