[src/trunk]: src/share/man/man4 Document AES-XTS in cgd(4).

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

details:   https://anonhg.NetBSD.org/src/rev/660049e5bb5c
branches:  trunk
changeset: 349448:660049e5bb5c
user:      alnsn <alnsn%NetBSD.org@localhost>
date:      Sun Dec 11 00:24:48 2016 +0000

description:
Document AES-XTS in cgd(4).

diffstat:

 share/man/man4/cgd.4 |  33 +++++++++++++++++++++++++++++++--
 1 files changed, 31 insertions(+), 2 deletions(-)

diffs (66 lines):

diff -r 4e46204730a0 -r 660049e5bb5c share/man/man4/cgd.4
--- a/share/man/man4/cgd.4      Sun Dec 11 00:23:44 2016 +0000
+++ b/share/man/man4/cgd.4      Sun Dec 11 00:24:48 2016 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: cgd.4,v 1.19 2016/06/01 01:34:43 pgoyette Exp $
+.\" $NetBSD: cgd.4,v 1.20 2016/12/11 00:24:48 alnsn 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 November 30, 2013
+.Dd December 11, 2016
 .Dt CGD 4
 .Os
 .Sh NAME
@@ -64,6 +64,21 @@
 .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
+.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
+.Tn AES-XTS
+key is made 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
 Triple
 .Tn DES
@@ -159,11 +174,25 @@
 .In dev/cgdvar.h
 header.
 .Sh WARNINGS
+.Pp
 It goes without saying that if you forget the passphrase that you used
 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 accout when evaluating security risks.
 .Sh FILES
 .Bl -tag -width indentxxxxxxxxxxx
 .It /dev/{,r}cgd*