Update cgd(4) man page.
- Highlight security model at top. - Add adiantum and aes-xts. - Split ciphers into `ciphers' and `obsolete ciphers'. - Specify the parameters to the ciphers: tweak, CBC IV. - Relegate obsolete `IV method' concept to a much shorter section. - Add references.
This commit is contained in:
riastradh
parent
94b00ca35c
commit
9493ed8295
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: cgd.4,v 1.22 2018/08/31 18:20:10 sevan Exp $
|
||||
.\" $NetBSD: cgd.4,v 1.23 2020/08/17 00:43:15 riastradh Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2002, 2003 The NetBSD Foundation, Inc.
|
||||
.\" All rights reserved.
|
||||
@ -27,7 +27,7 @@
|
||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd August 31, 2018
|
||||
.Dd August 16, 2020
|
||||
.Dt CGD 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -38,112 +38,147 @@
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
driver provides the capability of encrypting blocks on their way
|
||||
to and from a disk or partition.
|
||||
.Pp
|
||||
In order to compile support for the
|
||||
driver, configured with the
|
||||
.Xr cgdconfig 8
|
||||
tool, implements a logical disk device by encrypting or decrypting disk
|
||||
sectors on their way to and from a physical backing disk or partition.
|
||||
.Ss Security model
|
||||
As long as you keep the key secret,
|
||||
.Nm
|
||||
into your kernel, you must add the driver to your kernel configuration
|
||||
file.
|
||||
To do this, add a line similar to:
|
||||
.Bd -unfilled -offset indent
|
||||
pseudo-device cgd # cryptographic disk driver
|
||||
.Ed
|
||||
keeps the content of the disk secret from a
|
||||
.Em passive
|
||||
adversary, such as a thief who steals your disk or a border patrol
|
||||
agent who detains you and takes a snapshot of your laptop's disk while
|
||||
you are crossing a border.
|
||||
.Pp
|
||||
The
|
||||
.Nm
|
||||
devices are allocated as needed.
|
||||
.Ss Encryption Algorithms
|
||||
Currently the following cryptographic algorithms are supported:
|
||||
.Bl -tag -width indentxxxxxxx
|
||||
.It Ic aes-cbc
|
||||
.Em does not
|
||||
detect tampering by an
|
||||
.Em active
|
||||
adversary who can modify the content of the backing store, such as a
|
||||
man-in-the-middle between you and an
|
||||
.Tn iSCSI
|
||||
target, or after the border patrol returns your laptop to you.
|
||||
.Ss Ciphers
|
||||
The following ciphers are supported:
|
||||
.Bl -tag -width "abcd"
|
||||
.It Li "adiantum" (key size: 256 bits)
|
||||
The Adiantum tweakable wide-block cipher.
|
||||
The Adiantum tweak for each disk sector is taken to be the
|
||||
little-endian encoding of the disk sector number.
|
||||
.Pp
|
||||
Adiantum provides the best security by encrypting entire disk sectors
|
||||
at a time (512 bytes), and generally provides the best performance on
|
||||
machines without CPU support for accelerating
|
||||
.Tn AES .
|
||||
.It Li "aes-cbc" (key sizes: 128, 192, or 256 bits)
|
||||
.Tn AES
|
||||
in
|
||||
.Tn CBC
|
||||
mode.
|
||||
The
|
||||
.Tn CBC
|
||||
initialization vector for each disk sector is chosen to be the
|
||||
encryption under
|
||||
.Tn AES
|
||||
uses a 128 bit blocksize and can accept keys of length 128, 192, or 256.
|
||||
The default key length is 128.
|
||||
.It Ic aes-xts
|
||||
of the little-endian encoding of the disk sector number.
|
||||
The default key length is 128 bits.
|
||||
.It Li "aes-xts" (key sizes: 256 or 512 bits)
|
||||
.Tn AES
|
||||
in
|
||||
.Tn XTS
|
||||
mode.
|
||||
The
|
||||
.Tn XTS
|
||||
tweak for each disk sector is chosen to be the little-endian encoding
|
||||
of the disk sector number.
|
||||
.Tn AES-XTS
|
||||
uses a 128 bit blocksize and can accept keys of length 256 or 512.
|
||||
Note that an
|
||||
.Tn AES-XTS
|
||||
key consists of two
|
||||
.Tn AES
|
||||
keys of equal size.
|
||||
The second key is used solely to encrypt the block number of the physical
|
||||
disk block.
|
||||
The default key length is 256.
|
||||
.It Ic 3des-cbc
|
||||
uses a 256-bit or 512-bit key, composed of a pair of
|
||||
.Tn AES-128
|
||||
or
|
||||
.Tn AES-256
|
||||
keys.
|
||||
The default key length is 256, meaning
|
||||
.Tn AES-128.
|
||||
.El
|
||||
.Ss Obsolete Ciphers
|
||||
The following obsolete ciphers are supported for compatibility with
|
||||
old disks.
|
||||
.Pp
|
||||
.Sy WARNING:
|
||||
These obsolete ciphers are implemented without timing side channel
|
||||
protection, so, for example, JavaScript code in a web browser that can
|
||||
measure the timing of disk activity may be able to recover the secret
|
||||
key.
|
||||
These are also based on 64-bit block ciphers and are therefore unsafe
|
||||
for disks much larger than a gigabyte.
|
||||
You should not use these except where compatibility with old disks is
|
||||
necessary.
|
||||
.Bl -tag -width "abcd"
|
||||
.It Li "3des-cbc" (key size: 192 bits)
|
||||
.Tn 3DES
|
||||
.Po
|
||||
Triple
|
||||
.Tn DES
|
||||
with
|
||||
.Tn EDE3
|
||||
.Pc
|
||||
in
|
||||
.Tn CBC
|
||||
mode.
|
||||
Triple
|
||||
.Tn DES
|
||||
uses a 64 bit blocksize and is performed in
|
||||
The
|
||||
.Tn CBC
|
||||
initialization vector for each disk sector is chosen to be the
|
||||
encryption under
|
||||
.Tn 3DES
|
||||
of the little-endian encoding of the disk sector number, which has no
|
||||
impact on security but reduces performance.
|
||||
.Pp
|
||||
Note: Internally, the
|
||||
.Sq parity bits
|
||||
of the 192-bit key are ignored, so there are only 168 bits of key
|
||||
material, and owing to generic attacks on 64-bit block ciphers and to
|
||||
meet-in-the-middle attacks on compositions of ciphers as in
|
||||
.Tn EDE3
|
||||
mode with a 168 bit key.
|
||||
The key passed to the kernel is 192 bits but the parity bits are ignored.
|
||||
.It Ic blowfish-cbc
|
||||
the security is much lower than one might expect even for a 168-bit
|
||||
key.
|
||||
.It Li "blowfish-cbc" (key sizes: 40, 48, 56, 64, ..., 432, 440, or 448 bits)
|
||||
Blowfish in
|
||||
.Tn CBC
|
||||
mode.
|
||||
Blowfish uses a 64 bit blocksize and can accept keys between 40 and
|
||||
448 bits in multiples of 8.
|
||||
It is strongly encouraged that keys be at least 128 bits long.
|
||||
There are no performance advantages of using shorter keys.
|
||||
The default key length is 128 bits.
|
||||
.El
|
||||
.Ss IV Methods
|
||||
Currently, the following
|
||||
.Tn IV
|
||||
Methods are supported:
|
||||
.Bl -tag -width encblkno1
|
||||
.It Ic encblkno1
|
||||
This method encrypts the block number of the physical disk block once with
|
||||
the cipher and key provided and uses the result as the
|
||||
.Tn IV
|
||||
for
|
||||
.Tn CBC
|
||||
mode.
|
||||
This method should ensure that each block has a different
|
||||
.Tn IV
|
||||
and that the
|
||||
.Tn IV
|
||||
is reasonably unpredictable.
|
||||
This is the default method used by
|
||||
.Xr cgdconfig 8
|
||||
when configuring a new
|
||||
.Nm .
|
||||
.It Ic encblkno8
|
||||
This is the original
|
||||
.Tn IV
|
||||
method used by
|
||||
A very early version of
|
||||
.Nm
|
||||
and provided for backward compatibility.
|
||||
It repeatedly encrypts the block number of the physical disk block
|
||||
eight times and uses the result as the
|
||||
.Tn IV
|
||||
for
|
||||
had a bug in the
|
||||
.Tn CBC Ns -based
|
||||
ciphers
|
||||
.Li "aes-cbc" ,
|
||||
.Li "3des-cbc" ,
|
||||
and
|
||||
.Li "blowfish-cbc" :
|
||||
the
|
||||
.Tn CBC
|
||||
mode.
|
||||
This method should ensure that each block has a different
|
||||
.Tn IV
|
||||
and that the
|
||||
.Tn IV
|
||||
is reasonably unpredictable.
|
||||
The eightfold encryption was not intended and causes a notable
|
||||
performance loss with little (if any) increase in security over a
|
||||
single encryption.
|
||||
.El
|
||||
.Ss IOCTLS
|
||||
initialization vector was chosen to be the
|
||||
.Em eight-fold
|
||||
encryption under the block cipher of the little-endian encoding of the
|
||||
disk sector number.
|
||||
For compatibility with such disks, the
|
||||
.Sq IV method
|
||||
must be set to
|
||||
.Li encblkno8 .
|
||||
Otherwise the
|
||||
.Sq IV method
|
||||
should always be
|
||||
.Li encblkno1 .
|
||||
The parameter is meaningless for
|
||||
.Li adiantum
|
||||
and
|
||||
.Li aes-xts .
|
||||
.Sh IOCTLS
|
||||
A
|
||||
.Nm
|
||||
responds to all of the standard disk
|
||||
@ -151,7 +186,7 @@ responds to all of the standard disk
|
||||
calls defined in
|
||||
.Xr sd 4 ,
|
||||
and also defines the following:
|
||||
.Bl -tag -width CGDIOCSET -offset indent
|
||||
.Bl -tag -width CGDIOCSET
|
||||
.It Dv CGDIOCSET
|
||||
Configure the
|
||||
.Nm .
|
||||
@ -179,19 +214,6 @@ to configure a
|
||||
.Nm ,
|
||||
then you have irrevocably lost all of the data on the disk.
|
||||
Please ensure that you are using an appropriate backup strategy.
|
||||
.Pp
|
||||
A
|
||||
.Nm
|
||||
device doesn't authenticate data and thus it can't guarantee integrity
|
||||
of the encrypted data.
|
||||
In particular, if the plaintext is known to an adversary, it is
|
||||
possible to change every second block on a disk encrypted in the
|
||||
.Tn CBC
|
||||
mode to plaintext blocks of their choice.
|
||||
The
|
||||
.Tn XTS
|
||||
mode isn't vulnerable to this particular attack but a lack of
|
||||
integrity should be taken into account when evaluating security risks.
|
||||
.Sh FILES
|
||||
.Bl -tag -width indentxxxxxxxxxxx
|
||||
.It /dev/{,r}cgd*
|
||||
@ -212,7 +234,63 @@ device special files.
|
||||
.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference
|
||||
.%P 179-186
|
||||
.%D June 9-14, 2003
|
||||
.%U http://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf
|
||||
.%U https://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf
|
||||
.Re
|
||||
.Rs
|
||||
.%A Paul Crowley
|
||||
.%A Eric Biggers
|
||||
.%T Adiantum: length-preserving encryption for entry-level processors
|
||||
.%I International Association of Cryptologic Research
|
||||
.%J Transactions on Symmetric Cryptology
|
||||
.%V 2018
|
||||
.%N 4
|
||||
.%P 39-61
|
||||
.%U https://doi.org/10.13154/tosc.v2018.i4.39-61
|
||||
.Re
|
||||
.Rs
|
||||
.%T FIPS PUB 46-3: Data Encryption Standard (DES)
|
||||
.%Q United States Department of Commerce
|
||||
.%I National Institute of Standards and Technology
|
||||
.%O withdrawn May 19, 2005
|
||||
.%D October 25, 1999
|
||||
.%U https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25
|
||||
.Re
|
||||
.Rs
|
||||
.%T FIPS PUB 197: Advanced Encryption Standard (AES)
|
||||
.%Q United States Department of Commerce
|
||||
.%I National Institute of Standards and Technology
|
||||
.%D November 2001
|
||||
.%U https://csrc.nist.gov/publications/detail/fips/197/final
|
||||
.Re
|
||||
.Rs
|
||||
.%A Morris Dworkin
|
||||
.%T Recommendation for Block Cipher Modes of Operation: Methods and Techniques
|
||||
.%D December 2001
|
||||
.%Q United States Department of Commerce
|
||||
.%I National Institute of Standards and Technology
|
||||
.%O NIST Special Publication 800-38A
|
||||
.%U https://csrc.nist.gov/publications/detail/sp/800-38a/final
|
||||
.Re
|
||||
.Rs
|
||||
.%A Morris Dworkin
|
||||
.%T Recommendation for Block Cipher Modes of Operation: the XTS-AES Mode for Confidentiality on Storage Devices
|
||||
.%D January 2010
|
||||
.%Q United States Department of Commerce
|
||||
.%I National Institute of Standards and Technology
|
||||
.%O NIST Special Publication 800-38E
|
||||
.%U https://csrc.nist.gov/publications/detail/sp/800-38e/final
|
||||
.Re
|
||||
.Rs
|
||||
.%A Bruce Schneier
|
||||
.%T The Blowfish Encryption Algorithm
|
||||
.%O superseded by Twofish, superseded by Threefish
|
||||
.%U https://www.schneier.com/academic/blowfish
|
||||
.Re
|
||||
.Rs
|
||||
.%A Karthikeyan Bhargavan
|
||||
.%A Ga\(:etan Leurent
|
||||
.%T Sweet32: Birthday attacks on 64-bit block ciphers in TLS and OpenVPN
|
||||
.%U https://sweet32.info
|
||||
.Re
|
||||
.Sh HISTORY
|
||||
The
|
||||
@ -223,3 +301,11 @@ The
|
||||
.Nm
|
||||
driver originally appeared in
|
||||
.Nx 2.0 .
|
||||
The
|
||||
.Li aes-xts
|
||||
cipher was added in
|
||||
.Nx 8.0 .
|
||||
The
|
||||
.Li adiantum
|
||||
cipher was added in
|
||||
.Nx 10.0 .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user