20edbdcb3d
Remove Authors from man. We use now the AUTHORS file as single source. Bugs go to github. Compiled now with pandoc. Closes: https://github.com/scsitape/stenc/issues/45
251 lines
9.9 KiB
Groff
251 lines
9.9 KiB
Groff
.\" 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)
|