systemd-cryptsetup supports a FIDO2 mode with manual parameters, where
the user provides all the information necessary for recreating the
secret, such as: credential ID, relaying party ID and the salt. This
feature works great for implementing 2FA schemes, where the salt file
is for example a secret unsealed from the TPM or some other source.
While the unlocking part is quite straightforward to set up, enrolling
such a keyslot - not so easy. There is no clearly documented
way on how to set this up and online resources are scarce on this topic
too. By implementing a straightforward way to enroll such a keyslot
directly from systemd-cryptenroll we streamline the enrollment process
and reduce chances for user error when doing such things manually.
When in FIDO2 mode with manual parameters, i.e. when not reading the
parameters off the LUKS2 header, the current behavior in regards to PIN,
UP and UV features is to default to v248 logic, where we use PIN + UP
when needed, and do not configure UV at all. Let's allow users to
configure those features in manual mode too.
cryptsetup 2.7.0 adds feature to link effective volume key in custom
kernel keyring during device activation. It can be used later to pass
linked volume key to other services.
For example: kdump enabled systems installed on LUKS2 device.
This feature allows it to store volume key linked in a kernel keyring
to the kdump reserved memory and reuse it to reactivate LUKS2 device
in case of kernel crash.
Since EC keys doesn't support encryption directly, we use ECDH protocol.
We generate a pair of EC keys in the same EC group, then derive a shared secret using the generated private key and the public key in the token.
The derived shared secret is used as a volume key. The generated public key is stored in the LUKS2 JSON token header area. The generated private key is erased.
To unlock a volume, we derive the shared secret with the stored public key and a private key in the token.
Co-authored-by: MkfsSion <mkfssion@mkfssion.com>
The header and keyfile are necessary only for opening the device, not
for closing, so it is not necessary to deactivate the generated
cryptsetup unit when the header or keyfile backing store are removed.
This is especially useful in the case of softreboot, when the new
mount root is setup under /run/nextroot/ but we don't want to close
the cryptsetup devices for encrypted /var/ or so, and we simply
mount it directly on /run/nextroot/var/ before the soft-reboot.
As pointed out in https://github.com/systemd/systemd/issues/29814, we need to
use phrases are are meaningful on their own, because the man page formatter
creates a list at the bottom. With <ulink>see docs</ulink>, we end up with:
NOTES:
1. see docs
https://some.url/page
2. see docs
https://some.url/page2
which is not very useful :(
Also, the text inside the tag should not include punctuation.
Python helper:
from xml_helper import xml_parse
for p in glob.glob('../man/*.xml'):
t = xml_parse(p)
ulinks = t.iterfind('.//ulink')
for ulink in ulinks:
if ulink.text is None: continue
text = ' '.join(ulink.text.split())
print(f'{p}: {text}')
As I noticed a lot of missing information when trying to implement checking
for missing info. I reimplemented the version information script to be more
robust, and here is the result.
Follow up to ec07c3c80b
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
(s) is just ugly with a vibe of DOS. In most cases just using the normal plural
form is more natural and gramatically correct.
There are some log_debug() statements left, and texts in foreign licenses or
headers. Those are not touched on purpose.
In most cases we refernced the concept as "initrd". Let's convert most
remaining uses of "initramfs" to "initrd" too, to stay internally
consistent.
This leaves "initramfs" only where it's relevant to explain historical
concepts or where "initramfs" is part of the API (i.e. in
/run/initramfs).
Follow-up for: b66a6e1a58
Handle the case where TPM2 metadata is not available and explicitly
provided in crypttab. This adds a new "tpm2-pin" option to crypttab
options for this purpose.
Use the option name 'password-echo' instead of the generic term
'silent'.
Make the option take an argument for better control over echoing
behavior.
Related discussion in https://github.com/systemd/systemd/pull/19619
Previously, we supported only "," as separator. This adds support for
"+" and makes it the documented choice.
This is to make specifying PCRs in crypttab easier, since commas are
already used there for separating volume options, and needless escaping
sucks.
"," continues to be supported, but in order to keep things minimal not
documented.
Fixe: #19205
Adds a crypttab option 'silent' that enables the AskPasswordFlag
ASK_PASSWORD_SILENT. This allows usage of systemd-cryptsetup to default
to silent mode, rather than requiring the user to press tab every time.
On headless setups, in case other methods fail, asking for a password/pin
is not useful as there are no users on the terminal, and generates
unwanted noise. Add a parameter to /etc/crypttab to skip it.
This commit adds support for disabling the read and write
workqueues with the new crypttab options no-read-workqueue
and no-write-workqueue. These correspond to the cryptsetup
options --perf-no_read_workqueue and --perf-no_write_workqueue
respectively.
The comment is pointless, ECC systematically doesn't allow
encryption/decryption directly, only RSA does that. If you want to use
ECC for asymmetric encryption/decryption you have to combine it with key
exchange scheme and symmetric scheme. This all is not a limitation of
the Yubikey, hence don't claim so. It's just how ECC is.
Feature introduced in 50d2eba27b. Also documented
as part of the kernel parameter syntax in systemd-cryptsetup-generator(8), but
should also be documented here as part of the overall file syntax.
This option is an indication for PID1 that the entry in crypttab is handled by
initrd only and therefore it shouldn't interfer during the usual start-up and
shutdown process.
It should be primarily used with the encrypted device containing the root FS as
we want to keep it (and thus its encrypted device) until the very end of the
shutdown process, i.e. when initrd takes over.
This option is the counterpart of "x-initrd.mount" used in fstab.
Note that the slice containing the cryptsetup services also needs to drop the
usual shutdown dependencies as it's required by the cryptsetup services.
Fixes: #14224
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
