nbdkit-luks-filter(1)

1nbdkit-luks-filter(1)               NBDKIT               nbdkit-luks-filter(1)
2
3
4

NAME

6       nbdkit-luks-filter - read and write LUKS-encrypted disks and partitions
7

SYNOPSIS

9        nbdkit file encrypted-disk.img --filter=luks passphrase=+/tmp/secret
10

DESCRIPTION

12       "nbdkit-luks-filter" is a filter for nbdkit(1) which transparently
13       opens a LUKS-encrypted disk image.  LUKS ("Linux Unified Key Setup") is
14       the Full Disk Encryption (FDE) system commonly used by Linux systems.
15       This filter is compatible with LUKSv1 as implemented by the Linux
16       kernel (dm_crypt), and by qemu.
17
18       You can place this filter on top of nbdkit-file-plugin(1) to decrypt a
19       local file:
20
21        nbdkit file encrypted-disk.img --filter=luks passphrase=+/tmp/secret
22
23       If LUKS is present inside a partition in the disk image then you will
24       have to combine this filter with nbdkit-partition-filter(1).  The order
25       of the filters is important:
26
27        nbdkit file encrypted-disk.img \
28                    --filter=luks passphrase=+/tmp/secret \
29                    --filter=partition partition=1
30
31       This filter also works on top of other plugins such as
32       nbdkit-curl-plugin(1):
33
34        nbdkit curl https://example.com/encrypted-disk.img \
35                    --filter=luks passphrase=+/tmp/secret
36
37       The web server sees only the encrypted data.  Without knowing the
38       passphrase, the web server cannot access the decrypted disk.  Only
39       encrypted data is sent over the HTTP connection.  nbdkit itself will
40       serve unencrypted disk data over the NBD connection (if this is a
41       problem see nbdkit-tls(1), or use a Unix domain socket -U).
42
43       The passphrase can be stored in a file (as shown), passed directly on
44       the command line (insecure), entered interactively, or passed to nbdkit
45       over a file descriptor.
46
47       This filter can read and write LUKSv1.  It cannot create disks, change
48       passphrases, add keyslots, etc.  To do that, you can use ordinary Linux
49       tools like cryptsetup(8).  Note you must force LUKSv1 (eg. using
50       cryptsetup --type luks1).  qemu-img(1) can also create compatible disk
51       images:
52
53        qemu-img create -f luks \
54                        --object secret,data=SECRET,id=sec0 \
55                        -o key-secret=sec0 \
56                        encrypted-disk.img 1G
57

PARAMETERS

59       passphrase=SECRET
60           Use the secret passphrase when decrypting the disk.
61
62           Note that passing this on the command line is not secure on shared
63           machines.
64
65       passphrase=-
66           Ask for the passphrase (interactively) when nbdkit starts up.
67
68       passphrase=+FILENAME
69           Read the passphrase from the named file.  This is a secure method
70           to supply a passphrase, as long as you set the permissions on the
71           file appropriately.
72
73       passphrase=-FD
74           Read the passphrase from file descriptor number "FD", inherited
75           from the parent process when nbdkit starts up.  This is also a
76           secure method to supply a passphrase.
77

FILES

79       $filterdir/nbdkit-luks-filter.so
80           The plugin.
81
82           Use "nbdkit --dump-config" to find the location of $filterdir.
83

VERSION

85       "nbdkit-luks-filter" first appeared in nbdkit 1.32.
86

AUTHORS

93       Richard W.M. Jones
94

COPYRIGHT

96       Copyright (C) 2013-2022 Red Hat Inc.
97

LICENSE

99       Redistribution and use in source and binary forms, with or without
100       modification, are permitted provided that the following conditions are
101       met:
102
103       •   Redistributions of source code must retain the above copyright
104           notice, this list of conditions and the following disclaimer.
105
106       •   Redistributions in binary form must reproduce the above copyright
107           notice, this list of conditions and the following disclaimer in the
108           documentation and/or other materials provided with the
109           distribution.
110
111       •   Neither the name of Red Hat nor the names of its contributors may
112           be used to endorse or promote products derived from this software
113           without specific prior written permission.
114
115       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
116       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
117       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
118       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
119       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
120       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
121       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
122       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
123       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
124       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
125       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
126
127
128
129nbdkit-1.32.5                     2023-01-03             nbdkit-luks-filter(1)