diff --git a/man/crypttab.xml b/man/crypttab.xml
index 14bf93a0f7..04695f626f 100644
--- a/man/crypttab.xml
+++ b/man/crypttab.xml
@@ -53,25 +53,36 @@
it is opened as a LUKS device; otherwise, it is assumed to be in
raw dm-crypt (plain mode) format.
- The first field contains the name of the resulting encrypted volume; its block device is set up
- below /dev/mapper/.
+ The four fields of /etc/crypttab are defined as follows:
- The second field contains a path to the underlying block
- device or file, or a specification of a block device via
- UUID= followed by the UUID.
+
- The third field specifies an absolute path to a file with the encryption key. Optionally,
- the path may be followed by : and an fstab device specification (e.g. starting with
- LABEL= or similar); in which case the path is taken relative to the device file system
- root. If the field is not present or is none or -, a key file
- named after the volume to unlock (i.e. the first column of the line), suffixed with
- .key is automatically loaded from the /etc/cryptsetup-keys.d/
- and /run/cryptsetup-keys.d/ directories, if present. Otherwise, the password has to
- be manually entered during system boot. For swap encryption, /dev/urandom may be
- used as key file.
+ The first field contains the name of the resulting volume with decrypted data; its
+ block device is set up below /dev/mapper/.
- The fourth field, if present, is a comma-delimited list of
- options. The following options are recognized:
+ The second field contains a path to the underlying block
+ device or file, or a specification of a block device via
+ UUID= followed by the UUID.
+
+ The third field specifies an absolute path to a file with the encryption
+ key. Optionally, the path may be followed by : and an fstab device specification
+ (e.g. starting with LABEL= or similar); in which case the path is taken relative to
+ the device file system root. If the field is not present or is none or
+ -, a key file named after the volume to unlock (i.e. the first column of the line),
+ suffixed with .key is automatically loaded from the
+ /etc/cryptsetup-keys.d/ and /run/cryptsetup-keys.d/
+ directories, if present. Otherwise, the password has to be manually entered during system boot. For
+ swap encryption, /dev/urandom may be used as key file, resulting in a randomized
+ key.
+
+ If the specified key file path refers to an AF_UNIX stream socket in the
+ file system, the key is acquired by connecting to the socket and reading it from the connection. This
+ allows the implementation of a service to provide key information dynamically, at the moment when it is
+ needed. For details see below.
+
+ The fourth field, if present, is a comma-delimited list of options. The suppported
+ options are listed below.
+
@@ -499,6 +510,34 @@
systemd-cryptsetup-generator8.
+
+ AF_UNIX Key Files
+
+ If the key file path (as specified in the third column of /etc/crypttab
+ entries, see above) refers to an AF_UNIX stream socket in the file system, the key
+ is acquired by connecting to the socket and reading the key from the connection. The connection is made
+ from an AF_UNIX socket name in the abstract namespace, see unix7 for
+ details. The source socket name is chosen according the following format:
+
+ NUL RANDOM /cryptsetup/ VOLUME
+
+ In other words: a NUL byte (as required for abstract namespace sockets),
+ followed by a random string (consisting of alphabenumeric characters only), followed by the literal
+ string /cryptsetup/, followed by the name of the volume to acquire they key
+ for. Example (for a volume myvol):
+
+ \0d7067f78d9827418/cryptsetup/myvol
+
+ Services listening on the AF_UNIX stream socket may query the source socket
+ name with getpeername2,
+ and use it to determine which key to send, allowing a single listening socket to serve keys for a
+ multitude of volumes. If the PKCS#11 logic is used (see below) the socket source name is picked in
+ identical fashion, except that the literal string /cryptsetup-pkcs11/ is used. This is
+ done so that services providing key material know that not a secret key is requested but an encrypted key
+ that will be decrypted via the PKCS#11 logic to acquire the final secret key.
+
Examples