| .. SPDX-License-Identifier: GPL-2.0 | |
| ==================================== | |
| The per-namespace NFS client keyring | |
| ==================================== | |
| The NFS client holds one keyring, named ".nfs", per network | |
| namespace. An xprtsec=mtls mount presents the client certificate and | |
| private key named by its cert_serial= and privkey_serial= mount | |
| options, and the handshake links the mount's namespace .nfs keyring | |
| into tlshd before tlshd reads those keys. Keys placed on the .nfs | |
| keyring therefore need not grant user read permission: tlshd reaches | |
| them as a possessor, and a tlshd in another network namespace never | |
| possesses them. | |
| The keyring is owned by the owner of the network namespace's user | |
| namespace, with KEY_POS_ALL and KEY_USR_ALL less SETATTR. It is not | |
| charged to any quota. Keys added to it by userspace are charged to | |
| the user that adds them. | |
| Finding the keyring serial number | |
| ================================= | |
| The .nfs keyring is not linked into any keyring that userspace | |
| possesses, so a serial number is the only way to name it. The NFS | |
| client registers a key type, "nfs_keyring", whose sole purpose is to | |
| hand that serial number out. Its request_key handler runs in the | |
| caller's context and does not upcall to /sbin/request-key. | |
| To obtain the serial number, request a key of type "nfs_keyring" with | |
| the description ".nfs" and read its payload:: | |
| id=$(keyctl request2 nfs_keyring .nfs "" @s) | |
| serial=$(keyctl print $id) | |
| The contract of the key type is: | |
| * The description is the string ".nfs". Any other description is | |
| rejected with EINVAL before a key is allocated. | |
| * The callout info must be present. request_key() with a NULL | |
| callout_info never invokes a handler and returns ENOKEY when no | |
| matching key exists, so use request_key() with an empty string, or | |
| ``keyctl request2`` rather than ``keyctl request``. The content of | |
| the callout info is ignored. | |
| * The payload is the keyring serial number as decimal ASCII digits | |
| with no terminating NUL. The return value of keyctl_read() gives | |
| the length; a buffer of 12 bytes is sufficient. | |
| * add_key() with this type accepts only that payload. A key carrying | |
| any other value is rejected with EINVAL, so a key found in the | |
| caller's keyrings always holds the serial number of the caller's | |
| namespace. | |
| * The key type carries KEY_TYPE_NET_DOMAIN. A key instantiated in one | |
| network namespace does not answer a request made in another, so a | |
| process that keeps its session keyring across setns() receives the | |
| serial number of the namespace it is in at the time of the request. | |
| The serial number is not a secret. The keyring's own permissions | |
| decide what a caller can do with it. | |
| Provisioning credentials | |
| ======================== | |
| Add the client certificate and private key to the .nfs keyring as | |
| keys that grant no user read permission, then pass their serial | |
| numbers as cert_serial= and privkey_serial= mount options. |