[src/trunk]: src/share/man/man4 Update cgd(4) man page.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/76ba7b0ba4b6
branches:  trunk
changeset: 942712:76ba7b0ba4b6
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Mon Aug 17 00:43:15 2020 +0000

description:
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.

diffstat:

 share/man/man4/cgd.4 |  276 +++++++++++++++++++++++++++++++++-----------------
 1 files changed, 181 insertions(+), 95 deletions(-)

diffs (truncated from 350 to 300 lines):

diff -r 131bdb66bb64 -r 76ba7b0ba4b6 share/man/man4/cgd.4
--- a/share/man/man4/cgd.4      Sun Aug 16 20:43:01 2020 +0000
+++ b/share/man/man4/cgd.4      Mon Aug 17 00:43:15 2020 +0000
@@ -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.
+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
+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
-In order to compile support for the
 .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
+.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
-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
+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.
-.Tn AES-XTS
-uses a 128 bit blocksize and can accept keys of length 256 or 512.
-Note that an
+The
+.Tn XTS
+tweak for each disk sector is chosen to be the little-endian encoding
+of the disk sector number.
 .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
+A very early version of
+.Nm
+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.
-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
-.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
-.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 @@
 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 @@
 .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 @@
 .%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