diff --git a/configure.ac b/configure.ac index a74b851..af1d827 100644 --- a/configure.ac +++ b/configure.ac @@ -104,6 +104,9 @@ else fi +AC_CHECK_PROG(PANDOC, [pandoc], [yes]) +AM_CONDITIONAL([FOUND_PANDOC], [test "x$PANDOC" = xyes]) +AM_COND_IF([FOUND_PANDOC],,[AC_MSG_ERROR([required program 'pandoc' not found.])]) AC_CONFIG_FILES([Makefile src/Makefile man/Makefile tests/Makefile]) AC_OUTPUT diff --git a/man/Makefile.am b/man/Makefile.am index 9d3785e..e782670 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1 +1,11 @@ -dist_man_MANS = stenc.1 +man1_MANS = stenc.1 + +EXTRA_DIST = stenc.rst + +all: stenc.1 + +stenc.1: stenc.rst + pandoc --standalone --to man $< -o $@ + +clean: + rm -f stenc.1 diff --git a/man/stenc.1 b/man/stenc.1 deleted file mode 100644 index 5b1c24d..0000000 --- a/man/stenc.1 +++ /dev/null @@ -1,250 +0,0 @@ -.\" Automatically generated by Pandoc 2.13 -.\" -.TH "" "" "" "" "" -.hy -.SH NAME -.PP -stenc - SCSI Tape Hardware Encryption Manager -.SH SYNOPSIS -.PP -\f[B]stenc\f[R] \f[B]-g\f[R] \f[I]length\f[R] \f[B]-k\f[R] -\f[I]file\f[R] [\f[B]-kd\f[R] \f[I]description\f[R]] -.PD 0 -.P -.PD -\f[B]stenc\f[R] \f[B]-f\f[R] \f[I]device\f[R] [\f[B]--detail\f[R]] -.PD 0 -.P -.PD -\f[B]stenc\f[R] \f[B]-f\f[R] \f[I]device\f[R] \f[B]-e\f[R] -\f[B]on\f[R]|\f[B]mixed\f[R]|\f[B]rawread\f[R] [\f[B]-a\f[R] -\f[I]index\f[R]] [\f[B]-k\f[R] \f[I]file\f[R]] [\f[B]--ckod\f[R]] -[\f[B]--protect\f[R] | \f[B]--unprotect\f[R]] -.PD 0 -.P -.PD -\f[B]stenc\f[R] \f[B]-f\f[R] \f[I]device\f[R] \f[B]-e\f[R] \f[B]off\f[R] -[\f[B]-a\f[R] \f[I]index\f[R]] [\f[B]--ckod\f[R]] [\f[B]--protect\f[R] | -\f[B]--unprotect\f[R]] -.PD 0 -.P -.PD -\f[B]stenc\f[R] \f[B]--version\f[R] -.SH AVAILABILITY -.PP -Linux, AIX -.SH DESCRIPTION -.PP -Allows you to manage hardware encryption on SSP enabled tape devices -(LTO4, LTO5, etc). -.SH OPTIONS -.TP -\f[B]-g\f[R]\f[I]length\f[R] \f[B]-k\f[R] \f[B]\f[R] [\f[B]-kd\f[R] \f[I]\f[R]] -Generates a key file of \f[I]length\f[R] (in bits) containing a random -hexadecimal key. -After entering this option, you will be required to press random keys -followed by the enter key. -This will seed the random number generator so that your key is more -secure. -On systems with \f[B]/dev/random\f[R], the key is automatically -generated from the random content read from this file. -Specify the file to save the key into with the -k option (you will need -write permissions to that file location). -Lastly you can enter an optional key description using the -kd flag (see -\f[I]KEY DESCRIPTORS\f[R]). -This key file can then be used with the \f[B]-k\f[R] option. -You should not generate a key file over an unsecured remote session. -Typically, key files should be set to 256 bits (32 hexadecimal bytes), -however your device may only support 128 bits. -.TP -\f[B]-f\f[R] \f[I]device\f[R] -Specifies the device to use (i.e. -\f[I]/dev/nst0, /dev/rmt0.1, /dev/sg0\f[R]). -Use the \f[B]lsscsi\f[R] command to determine the appropriate device to -use. -You should always use a device name that does not rewind (i.e. -use /dev/nst0 instead of /dev/st0, /dev/rmt0.1 instead of /dev/rmt0). -Use commands like \[aq]cat /proc/scsi/scsi\[aq], \[aq]lsscsi\[aq], and -\[aq]lsdev\[aq] to determine the proper device to use. -On some distros, a /dev/sg device must be used instead of a /dev/st -device. -.PP -If this is the only option specified, the status of the device will be -displayed. -To retrieve more detailed status information, add \f[B]--detail\f[R]. -If you are root and the status command fails, either the -\f[I]device\f[R] is incorrect (try another link to the device: -\f[I]/dev/rmt0.1\f[R], \f[I]/dev/nst0\f[R], \f[I]/dev/tape\f[R], etc.), -a tape may not be in the drive, you may be using the wrong algorithm for -the tape drive (see the \f[B]-a\f[R] option), or the device does not -support SCSI Security Protocol. -\f[B]stenc\f[R] may read up to 100 blocks of the tape, starting at the -current position, in order to determine if the volume has been -encrypted. -For this reason, you should not run the status command while another -process is accessing the drive. -If the device returns \f[I]Unable to determine\f[R] for the volume -encryption status, you may need to move to a section of the tape that -contains data (i.e. -\f[B]mt -f fsr \f[R]) or rewind the tape in order for -\f[B]stenc\f[R] to output the volume status. -.TP -\f[B]-e\f[R] \f[B]on\f[R] | \f[B]mixed\f[R] | \f[B]rawread\f[R] | \f[B]off\f[R] -Sets the encryption mode for the device specified with \f[B]-f\f[R] -option. -Successful operations of this type will create an audit entry in the -\f[I]/var/log/stenc\f[R] file. -If \f[B]off\f[R] is not specified and the \f[B]-k\f[R] option is not -specified, the program will require the user to enter a hexadecimal key -(see \f[I]KEY INPUT SYNTAX\f[R]) and an optional key description (see -\f[I]KEY DESCRIPTORS\f[R]). -.PP -\f[B]on\f[R] - The drive will encrypt all data sent to it and will only -output data it is able to decrypt, ignoring unencrypted data on the -drive. -.PP -\f[B]mixed\f[R] - The drive will encrypt all data sent to it and will -output both encrypted data and unencrypted data, providing the drive is -able to do so. -.PP -\f[B]rawread\f[R] - The drive will encrypt all data sent to it and will -output unencrypted data and raw encrypted data. -You will probably need to have specified \f[B]--unprotect\f[R] when the -data was written in order to read it with this option. -Some drives do not support this option. -See the \f[B]--protect\f[R] option. -.PP -\f[B]off\f[R] - The drive will neither encrypt data sent to it, or -decrypt encrypted data found on the drive. -If this command fails you may have switch your algorithm or specify a -different default key size when you configure the program -.PP -\f[B]WARNING:\f[R] The SCSI device will revert all encryption settings -if the tape device is power cycled (if the tape drive is extenal, it may -keep the settings even if the system is rebooted). -You can modify you local startup script (/etc/rc.local, /etc/rc, etc.) -to set encryption at reboot if need be. -If you do this, you will need to use the \f[B]-k\f[R] option to prevent -the system from waiting on the local console user to enter the -encryption key. -.TP -\f[B]-a\f[R] \f[I]index\f[R] -Only valid when setting encryption (see the \f[B]-e\f[R] option). -Specifies the algorithm index to use for the device (defaults to 0, -which can be changed using the --with-default-algorithm configure -option). -Setting encryption on/off may fail on some devices if this is not the -correct algorithm for the drive (i.e. -HP drives use an algorithm index of 1). -.TP -\f[B]--ckod\f[R] -Only valid when setting encryption (see the \f[B]-e\f[R] option). -Instructs the drive to clear its encryption keys when the volume is -unmounted instead of keeping it until the drive is power cycled. -Some devices may not support this option. -.TP -\f[B]--protect\f[R] | \f[B]--unprotect\f[R] -Only valid when setting encryption (see the \f[B]-e\f[R] option). -Instructs the drive to \f[B]protect\f[R] or \f[B]unprotect\f[R] any -encrypted data from being raw read. -See the \f[B]-e rawread\f[R] option. -Some devices may not support these options. -.TP -\f[B]-k\f[R] \f[I]file\f[R] -Only valid when turning encryption on (see the \f[B]-e\f[R] option) or -generating a new key (see the \f[B]-g\f[R] option). -When turning encryption on, this specifies the location of a key file -previously generated with the \f[B]-g\f[R] option. -When generating a new key with the \f[B]-g\f[R] option, this specifies -the key file that the new key will be saved into. -Key files should be owned by root (\[aq]\f[B]chown root\f[R]\[aq]) and -only readable by root (\[aq]\f[B]chmod 600\f[R]\[aq]). -\f[B]stenc\f[R] automatically chmods key files generated with the -\f[B]-g\f[R] option. -.SH KEY INPUT SYNTAX -.PP -All keys should be a maximum of 256 bits (32 bytes). -\f[B]stenc\f[R] requires that all keys are entered using 2 digit -hexadecimal bytes, with no delimiters in between bytes. -Do not precede your key input with \[aq]0x\[aq]. -If you try to use a key size that the drive does not support, the -command will error. -When using a key file, the second line in the file can contain an -optional key description that will be displayed with the device status -(see the \f[B]-f\f[R] option). -.TP -\f[B]Example 128 bit Key:\f[R] -000102030405060708090a0b0c0d0e0f -.TP -\f[B]Example 256 bit Key:\f[R] -000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f -.SH EXAMPLE -.TP -\f[B]stenc -g 256 -k /etc/tape.key -kd \[dq]September Tape Key\[dq]\f[R] -Generate a random 256 bit key file with the description \[dq]September -Tape Key\[dq] and save it into /etc/tape.key -.TP -\f[B]stenc -f /dev/st0 -e on -k /etc/stenc.key\f[R] -Turns on encryption on /dev/st0 using the key contained in -/etc/stenc.key -.TP -\f[B]stenc -f /dev/st0 -e on\f[R] -Asks user to input a key in hexadecimal format and then turns on -encryption for /dev/st0 using that key -.TP -\f[B]stenc -f /dev/st0 -e off\f[R] -Turns off encryption for /dev/st0 -.TP -\f[B]stenc -f /dev/st0 --detail\f[R] -Outputs the detailed encryption status of /dev/st0 -.TP -\f[B]tail /var/log/stenc\f[R] -Lists the last few key change audit entries -.SH KEY CHANGE AUDITING -.PP -Each time a key is changed using this program, a corresponding entry -will be entered into the \f[I]/var/log/stenc\f[R] file. -These entries will have an \f[I]Key Instance Counter\f[R] corresponding -to the counter listed in the device status (see the \f[B]-f\f[R] -option). -Each time the key is set, a checksum of that key (or a key description) -is also listed in this file. -This allows you to know when keys were changed and if the key you are -using is the same as a prior key. -If an unauthorized party would compromise this log file, your key -security would be decreased if checksums were present in the log. -To prevent this, you should use key descriptors instead of checksums -(see \f[I]KEY DESCRIPTORS\f[R]). -.SH KEY DESCRIPTORS -.PP -Key descriptors are set when using the \f[B]-g\f[R] option or the -\f[B]-e\f[R] option. -They will be displayed when retrieving the drive status (see the -\f[B]-f\f[R] option). -These descriptors will be written to the volume, so they should NEVER -contain information that would reduce the security of the key (i.e. -a checksum, bitlength, algorithm, a portion of the key). -If \f[B]stenc\f[R] detects that the volume is encrypted but it cannot -decrypt the data, the key descriptor on the volume will be displayed as -part of the device status. -This can be useful for determining which key goes to which volume. -.SH REPORTING BUGS -.PP -Report \f[B]stenc\f[R] bugs to - -.SH PROJECT UPDATES -.PP -Visit \f[B]https://github.com/scsitape/stenc\f[R] for more information. -.SH COPYRIGHT -.PP -Copyright 2012-2022 contributing authors. -License GPLv2: GNU GPL version 2 <>. -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH SEE ALSO -.PP -\f[B]mt\f[R](1L) -.PD 0 -.P -.PD -\f[B]lsscsi\f[R](8)