mirrors/stenc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add pandoc to makefile (#51)

Browse Source 
* Add check for pandoc
* Generate the man page from reStructuredText
* Install man page after generation by pandoc

Closes: https://github.com/scsitape/stenc/issues/44
Co-authored-by: Paweł Marciniak <sunwire+git@gmail.com>
This commit is contained in:
Paweł Marciniak
2022-04-30 15:34:51 +01:00
committed by GitHub
parent 20edbdcb3d
commit 1ece43b1cb
3 changed files with 14 additions and 251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
man/Makefile.am
View File

@@ -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

250
man/stenc.1
View File

@@ -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]<file to save as>\f[R] [\f[B]-kd\f[R] \f[I]<key descriptor(uKAD)>\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 <device> fsr <count>\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
<https://github.com/scsitape/stenc/issues>
.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 <<http://gnu.org/licenses/gpl.html>>.
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)