#1141580 cryptsetup-initramfs: cryptroot-unlock should clarify how newline character from the passphrase are handled #1141580
- Package:
- cryptsetup-initramfs
- Source:
- cryptsetup-initramfs
- Submitter:
- Vincent Lefevre
- Date:
- 2026-07-06 18:25:03 UTC
- Severity:
- normal
/usr/share/doc/cryptsetup/README.Debian.gz says
Or, using a local gpg-encrypted key file:
gpg --decrypt ~/.luks/remote.key.gpg | ssh -TF ~/.luks/ssh.conf root@remote.system.com cryptroot-unlock
but in case the piped content is a text file (usually the case),
i.e. with a newline character after the passphrase, then one gets
an error, e.g.
Please unlock disk nvme0n1p3_crypt
cryptsetup: cryptsetup failed, bad password or options?
and "No key available with this passphrase." on the remote machine.
I could check with "echo -n <passphrase> | ssh ..." that the
passphrase is accepted (but on a machine with multiple users,
one should not use "echo" with the passphrase).
It is the intended behavior, feel free to suggest a better wording for README.Debian.gz but passphrase processing is already documented in cryptsetup(8): | Passphrase processing for LUKS | | From a terminal: The passphrase is read until the first newline and | then processed by PBKDF2 without the newline character. | | From stdin: LUKS will read passphrases from stdin up to the first | newline character or the compiled-in maximum key file length. If | --keyfile-size is given, it is ignored. | | From key file: The complete keyfile is read up to the compiled-in | maximum size. Newline characters do not terminate the input. The | --keyfile-size option can be used to limit what is read. You need to either remove the trailing newline from the keyfile, or force TTY-mode.
Control: reopen -1
The above man page is about the cryptsetup utility:
NAME
cryptsetup - utility for configuring and managing encrypted storage
devices
My bug report refers to cryptroot-unlock, which is a different command.
And there is no way to provide a file to SSH, so this is "from stdin"
(this is a pipe to ssh, and the input is thus read from stdin).
So, either one considers that the conventions from cryptsetup(8) apply
(thus from stdin), and this is clearly an unexpected behavior; or this
is undocumented for cryptroot-unlock, which does not have a man page.
Thus the only documentation is in the README.Debian.gz file Section 8
"8. Remotely unlock encrypted rootfs" (note that this section doesn't
have any reference to the cryptsetup(8) man page), which does not say
anything about newline characters.
Note also that this README.Debian.gz file Section 8 is what
/usr/share/doc/dropbear-initramfs/README.initramfs points to:
Unlocking procedure
-------------------
You can unlock your rootfs on bootup remotely, using SSH to log in to
the booting system while it's running with the initramfs mounted.
Consult cryptsetup's /usr/share/doc/cryptsetup/README.Debian.gz sec. 8
for details.
But I don't see the point in including a newline character in
a passphrase, since such a passphrase will never be accepted
in interactive mode.
BTW, the cryptsetup(8) man page says:
[...] A passphrase stored in a file is called a key file. The only
difference between a passphrase and a key file is that a key file
can contain binary data. Both are processed the same.
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Even for the cryptsetup utility, this is contradictory.
Control: severity -1 minor
Control: retitle -1 cryptsetup-initramfs: cryptroot-unlock should clarify how newline character from the passphrase are handled
It's a wrapper, the passphrase is processed like for
ssh root@remote.com crypsetup --key-file=- /dev/sda1 name </path/to/key/file
(binary key file) or
ssh -t root@remote.com crypsetup /dev/sda1 name
(interactive mode on a TTY).
No it is not. However the proper manual quote should have been:
| --key-file, -d file
|
| Read the passphrase from the file.
|
| If the name given is "-", then the passphrase will be read from
| stdin. In this case, reading will not stop at newline characters.
|
| […]
|
| See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
| more information.
Again, feel free to suggest to suggest an addition or alternative
formulation. BTS ping pong is not going to improve things.
There are valid use cases where the passphrase never needs to be entered
interactively and where the key file should be processed in full,
including newline characters and null characters. For instance
cryptsetup open --type plain --key-file=/dev/urandom \
--key-size 32 […] /dev/sda1 crypt_swap
or
head -c32 /dev/urandom >/path/to/my/binary/keyfile
cryptsetup luksFormat --key-file=/path/to/my/binary/keyfile […] \
/dev/sda1 crypt_root
would end-up being potentially very insecure if the keyfile would be
truncated early.