From 39a5408e98ccd9351c8e3cb4cbb8af0fb5386ce2 Mon Sep 17 00:00:00 2001 From: Milan Broz Date: Fri, 8 Jun 2012 22:40:57 +0200 Subject: [PATCH] Add man page. --- man/Makefile.am | 6 +- man/veritysetup.8 | 116 +++++++++++++++++++++++++++++++++++++++ src/veritysetup.c | 3 +- tests/verity-compat-test | 2 +- 4 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 man/veritysetup.8 diff --git a/man/Makefile.am b/man/Makefile.am index 1825d66..520e5ea 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,3 +1,7 @@ man8_MANS = cryptsetup.8 -EXTRA_DIST = cryptsetup.8 \ No newline at end of file +if VERITYSETUP +man8_MANS += veritysetup.8 +endif + +EXTRA_DIST = $(man8_MANS) diff --git a/man/veritysetup.8 b/man/veritysetup.8 new file mode 100644 index 0000000..066c486 --- /dev/null +++ b/man/veritysetup.8 @@ -0,0 +1,116 @@ +.TH VERITYSETUP "8" "June 2012" "veritysetup" "Maintenance Commands" +.SH NAME +veritysetup - manage dm-verity (block level verification) volumes +.SH SYNOPSIS +.B veritysetup +.SH DESCRIPTION +.PP +veritysetup is used to configure dm-verity managed device-mapper mappings. + +Device-mapper verity target provides read-only transparent integrity +checking of block devices using kernel crypto API. + +The dm-verity devices are always read-only. + +veritysetup supports these operations: +.PP +\fIformat\fR +.IP +Calculates and permanently stores hash verification data for data_device. +Hash area can be located on the smae device after data if specified +by \-\-hash\-start option. +Note you need to provide reported roo hash for device verification +or activation. This hash must be trusted. + +\fB\fR can be [\-\-hash, \-\-no-superblock, \-\-format, +\-\-data-block-size, \-\-hash-block-size, \-\-data-blocks, \-\-hash-start, +\-\-salt] +.PP +\fIcreate\fR +.IP +Creates a mapping with backed by device and using + for in-kernel verification. + +The is a hexadecimal string. + +\fB\fR can be [\-\-hash-start, \-\-no-superblock] + +If option \-\-no-superblock is used, you have to use the same options +as in format operation. +.PP +\fIremove\fR +.IP +Removes the existing mapping . +.PP +\fIstatus\fR +.IP +Reports the status for the active verity mapping . +.PP +\fIdump\fR +.IP +Reports the parameters of verity device from on-disk stored superblock. +\fB\fR can be [\-\-no-superblock] +.SH OPTIONS +.TP +.B "\-\-verbose, \-v" +Print more information on command execution. +.TP +.B "\-\-debug" +Run in debug mode with full diagnostic logs. Debug output +lines are always prefixed by '#'. +.TP +.B "\-\-no-superblock +Create or use dm-verity without permanent on-disk superblock. +.TP +.B "\-\-format=number +Specifies the hash version type. +Format type 0 is original Chrome OS verion. Format type 1 si default. +.TP +.B "\-\-data-block-size=bytes +Used block size for the data device. +(Note kernel supports only page-size as maximum here.) +.TP +.B "\-\-hash-block-size=bytes +Used block size for the hash device. +(Note kernel supports only page-size as maximum here.) +.TP +.B "\-\-data-blocks=blocks +Size of data device used in verification. +If not specified, the whole device is used. +.TP +.B "\-\-hash-start=512-bytes sectors +Offset of hash area/superblock on hash_device. +.TP +.B "\-\-salt=hex string +Salt used for format or verification. +Format is hexadecimal string. +.TP +.B "\-\-version" +Show the program version. +.SH RETURN CODES +Veritysetup returns 0 on success and a non-zero value on error. + +Error codes are: 1 wrong parameters, 2 no permission, +3 out of memory, 4 wrong device specified, 5 device already exists +or device is busy. +.SH REPORTING BUGS +Report bugs, including ones in the documentation, on +the cryptsetup mailing list at +or in the 'Issues' section on LUKS website. +Please attach the output of the failed command with the +\-\-debug option added. +.SH AUTHORS +The first implementation of veritysetup was written by Chromium OS authors. + +This version is based on verification code written by Mikulas Patocka +and rewritten for libcryptsetup by Milan Broz . +.SH COPYRIGHT +Copyright \(co 2012 Red Hat, Inc. + +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH SEE ALSO +The project website at \fBhttp://code.google.com/p/cryptsetup/\fR + +The verity on-disk format specification available at +\fBhttp://code.google.com/p/cryptsetup/wiki/DMCrypt\fR diff --git a/src/veritysetup.c b/src/veritysetup.c index ee331be..c9d16c9 100644 --- a/src/veritysetup.c +++ b/src/veritysetup.c @@ -22,7 +22,6 @@ * - extend superblock (UUID) * - add api tests * - salt string "-" - * - man page */ #include @@ -423,7 +422,7 @@ int main(int argc, const char **argv) { "hash-block-size", 0, POPT_ARG_INT, &hash_block_size, 0, N_("Block size on the hash device"), N_("bytes") }, { "data-blocks", 0, POPT_ARG_STRING, &popt_tmp, 1, N_("The number of blocks in the data file"), N_("blocks") }, { "hash-start", 0, POPT_ARG_STRING, &popt_tmp, 2, N_("Starting block on the hash device"), N_("512-byte sectors") }, - { "algorithm", 'h', POPT_ARG_STRING, &hash_algorithm, 0, N_("Hash algorithm"), N_("string") }, + { "hash", 'h', POPT_ARG_STRING, &hash_algorithm, 0, N_("Hash algorithm"), N_("string") }, { "salt", 's', POPT_ARG_STRING, &salt_string, 0, N_("Salt"), N_("hex string") }, POPT_TABLEEND }; diff --git a/tests/verity-compat-test b/tests/verity-compat-test index 59ceb0f..056821f 100755 --- a/tests/verity-compat-test +++ b/tests/verity-compat-test @@ -84,7 +84,7 @@ function check_root_hash() # $1 size, $2 hash, $3 salt, $4 version, $5 hash, [$6 echo -n "V$4 $5 block size $1: " $VERITYSETUP format $DEV_PARAMS --format=$4 \ --data-block-size=$1 --hash-block-size=$1 \ - --algorithm=$5 --salt=$3 \ + --hash=$5 --salt=$3 \ >$DEV_OUT || fail echo -n "[root hash]" -- 2.34.1