From: Milan Broz Date: Sun, 2 Dec 2012 20:21:14 +0000 (+0100) Subject: Add TCRYPT documentation, X-Git-Tag: upstream/1.6~128 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5aef0809d4fa3c6ed9ab1175dfccb62c51e0dd0d;p=platform%2Fupstream%2Fcryptsetup.git Add TCRYPT documentation, --- diff --git a/lib/libcryptsetup.h b/lib/libcryptsetup.h index 3709a51..0f19f03 100644 --- a/lib/libcryptsetup.h +++ b/lib/libcryptsetup.h @@ -302,7 +302,7 @@ int crypt_memory_lock(struct crypt_device *cd, int lock); #define CRYPT_LOOPAES "LOOPAES" /** dm-verity mode */ #define CRYPT_VERITY "VERITY" -/** TCRYPT mode */ +/** TCRYPT (TrueCrypt-compatible) mode */ #define CRYPT_TCRYPT "TCRYPT" /** @@ -397,10 +397,10 @@ struct crypt_params_verity { #define CRYPT_TCRYPT_BACKUP_HEADER (1 << 2) struct crypt_params_tcrypt { - const char *passphrase; - size_t passphrase_size; - const char **keyfiles; - unsigned int keyfiles_count; + const char *passphrase; /**< passphrase to unlock header (input only) */ + size_t passphrase_size; /**< passphrase size (input only) */ + const char **keyfiles; /**< keyfile paths to unlock header (input only) */ + unsigned int keyfiles_count;/**< keyfiles count (input only) */ const char *hash_name; /**< hash function for PBKDF */ const char *cipher; /**< cipher chain c1[-c2[-c3]] */ const char *mode; /**< cipher block mode */ @@ -788,6 +788,8 @@ int crypt_activate_by_keyfile(struct crypt_device *cd, * @note For VERITY the volume key means root hash required for activation. * Because kernel dm-verity is always read only, you have to provide * CRYPT_ACTIVATE_READONLY flag always. + * @note For TCRYPT the volume key should be always NULL and because master + * key from decrypted header is used instead. */ int crypt_activate_by_volume_key(struct crypt_device *cd, const char *name, @@ -820,6 +822,9 @@ int crypt_deactivate(struct crypt_device *cd, const char *name); * @param passphrase_size size of @e passphrase * * @return unlocked key slot number or negative errno otherwise. + * + * @note For TCRYPT cipher chain is the volume key concatenated + * for all ciphers in chain. */ int crypt_volume_key_get(struct crypt_device *cd, int keyslot, diff --git a/lib/tcrypt/tcrypt.c b/lib/tcrypt/tcrypt.c index 4d6d4aa..9bb31b6 100644 --- a/lib/tcrypt/tcrypt.c +++ b/lib/tcrypt/tcrypt.c @@ -1,5 +1,5 @@ /* - * TCRYPT compatible volume handling + * TCRYPT (TrueCrypt-compatible) volume handling * * Copyright (C) 2012, Red Hat, Inc. All rights reserved. * Copyright (C) 2012, Milan Broz diff --git a/lib/tcrypt/tcrypt.h b/lib/tcrypt/tcrypt.h index d67f8f1..2cc4db0 100644 --- a/lib/tcrypt/tcrypt.h +++ b/lib/tcrypt/tcrypt.h @@ -1,5 +1,5 @@ /* - * TCRYPT - header defitinion + * TCRYPT (TrueCrypt-compatible) header defitinion * * Copyright (C) 2012, Red Hat, Inc. All rights reserved. * Copyright (C) 2012, Milan Broz diff --git a/man/cryptsetup.8 b/man/cryptsetup.8 index 65de31b..a8e2561 100644 --- a/man/cryptsetup.8 +++ b/man/cryptsetup.8 @@ -361,6 +361,68 @@ Identical to \fIremove\fR. .PP See also section 7 of the FAQ and \fBhttp://loop-aes.sourceforge.net\fR for more information regarding loop-AES. +.SH TCRYPT (TrueCrypt-compatible) EXTENSION +cryptsetup supports mapping of TrueCrypt or tcplay encrypted partition +using a native Linux kernel API. +Header formatting and TCRYPT header change is not supported, cryptsetup +never changes TCRYPT header on-device. + +TCRYPT extension requires kernel userspace crypto API to be available +(kernel af_alg and algif_skcipher modules, introduced in Linux kernel 2.6.38). + +Because TCRYPT header is encrypted, you have to always provide valid +passphrase and keyfiles. + +Cryptsetup should recognize all header variants, except legacy cipher chains +using LRW encryption mode with 64 bits encryption block (namely Blowfish +in LRW mode is not recognized, this is limitation of kernel crypto API). + +\fBNOTE:\fR Activation with \fBtcryptOpen\fR is supported only for cipher chains +using LRW or XTS encryption modes. + +The \fBtcryptDump\fR command should work for all recognized TCRYPT devices +and doesn't require superuser privilege. + +To use hidden header (and map hidden device, if available), +use \fB\-\-hidden\fR option. +.PP +\fItcryptOpen\fR \-\-key-file +.IP +Opens the TCRYPT (a TrueCrypt-compatible) and sets up a mapping . + +\fB\fR can be [\-\-key-file, \-\-hidden, \-\-readonly, +\-\-test-passphrase]. + +The keyfile parameter allows combination of file content with the +passphrase and can be repeated. Note that using keyfiles is compatible +with TCRYPT and is different from LUKS keyfile logic. +.PP +\fItcryptDump\fR +.IP +Dump the header information of a TCRYPT device. + +If the \-\-dump-master-key option is used, the TCRYPT device master key is +dumped instead of TCRYPT header info. Beware that the master key +(or concatenated master keys if cipher chain is used) +can be used to decrypt the data stored in the TCRYPT container without +a passphrase. +This means that if the master key is compromised, the whole device has +to be erased to prevent further access. Use this option carefully. + +\fB\fR can be [\-\-dump-master-key, \-\-key-file, \-\-hidden]. + +The keyfile parameter allows combination of file content with the +passphrase and can be repeated. +.PP +\fItcryptClose\fR +.IP +Identical to \fIremove\fR. +.PP +See also \fBhttp://www.truecrypt.org\fR for more information regarding +TrueCrypt. + +Please note that cryptsetup does not use TrueCrypt code, please report +all problems related to this compatibility extension to cryptsetup project. .SH MISCELLANEOUS .PP \fIbenchmark\fR @@ -374,8 +436,8 @@ and \fB\-\-key-size\fR options. \fBNOTE:\fR This benchmark is using memory only and is only informative. You cannot directly predict real storage encryption speed from it. -This benchmark requires kernel userspace crypto API interface to be available -(kernel af_alg and af_skcipher modules, introduced in Linux kernel 2.6.38). +This benchmark requires kernel userspace crypto API to be available +(kernel af_alg and algif_skcipher modules, introduced in Linux kernel 2.6.38). \fB\fR can be [\-\-cipher, \-\-key-size]. .SH OPTIONS @@ -837,6 +899,8 @@ Copyright \(co 2004-2006 Clemens Fruhwirth .br Copyright \(co 2009-2012 Red Hat, Inc. .br +Copyright \(co 2009-2012 Milan Broz +.br Copyright \(co 2012 Arno Wagner This is free software; see the source for copying conditions. There is NO