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

Rewrite man page (#88)

Browse Source
This commit is contained in:
James Wilson
2022-06-16 12:49:36 -07:00
committed by GitHub
parent f800dc2f51
commit 918afb35fb
1 changed files with 127 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
man/stenc.rst
View File

@@ -5,122 +5,127 @@ STENC(1) |General Commands Manual
NAME
====
stenc - SCSI Tape Hardware Encryption Manager
SYNOPSIS
========
| **stenc** **-f** *device* [**--detail**]
| **stenc** **-f** *device* **-e** **on**\ \|\ **mixed**\ \|\ **rawread** [**-a** *index*] [**-k** *file*] [**--ckod**] [**--protect** \| **--unprotect**]
| **stenc** **-f** *device* **-e** **off** [**-a** *index*] [**--ckod**] [**--protect** \| **--unprotect**]
| **stenc** **--version**
AVAILABILITY
============
Linux, FreeBSD
| **stenc** [**-f** *DEVICE*]
| **stenc** [**-f** *DEVICE*] [**-e** *ENC-MODE*] [**-d** *DEC-MODE*] [*OPTIONS*]
DESCRIPTION
===========
Allows you to manage hardware encryption on SSP enabled tape devices
(LTO4, LTO5, etc).
**stenc** manages hardware data encryption on tape devices that support
the SCSI security protocol.
Controlling device encryption
-----------------------------
The encryption mode (what happens to data written to the
device), and decryption mode (what happens to data read from the device)
can be controlled independently. If only one of the following options is
given, the other mode will be inferred to set the encryption and decryption
modes in tandem.
**-e, --encrypt**=\ *ENC-MODE*
Sets the encryption mode. *ENC-MODE* is either *off* or *on*.
**off**
Data written to the device will be not encrypted.
**on**
Data written to the device will be encrypted.
**-d, --decrypt**=\ *DEC-MODE*
Sets the decryption mode. *DEC-MODE* is either *off*, *on*, or *mixed*.
**off**
Data read from the device will not be decrypted and only unencrypted
tape blocks can be read.
**on**
Data read from the device will be decrypted and only encrypted tape blocks can
be read. The drive only output data it is able to decrypt, and will not
read unencrypted data on the drive.
**mixed**
Data read from the device will be decrypted, if needed. Both encrypted and
unencrypted tape blocks can be read. The drive will read both encrypted
data and unencrypted data, provided the drive is able to do so.
Viewing device status
---------------------
When neither options to set encryption or decryption mode are given, **stenc**
prints the encryption settings, the encryption status of the current block,
and capabilities of the device, including a list of supported algorithm indexes.
The device may display current block encryption status as *Unable to determine*
if the tape is positioned at a filemark or end of tape, in which case it may be
necessary to move the tape position using **mt**\ (1).
OPTIONS
=======
**-f** *device*
Specifies the device to use (i.e. */dev/nst0*, */dev/rmt0.1*,
*/dev/sg0*). Use the **lsscsi** 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 'cat /proc/scsi/scsi', 'lsscsi', and
'lsdev' to determine the proper device to use. On some distros, a
*/dev/sg* device must be used instead of a */dev/st* device. Typically,
only the superuser can access tape devices.
**-f, --file**=\ *DEVICE*
Specifies the device to use (e.g. */dev/nst0*, */dev/nsa0*, */dev/rmt0.1*).
Use the **lsscsi**\ (8) command on Linux, or **camcontrol**\ (8) on FreeBSD
to determine the appropriate device to use. It is recommended to the use a
non-rewinding device (i.e. */dev/nst0* instead of */dev/st0*, */dev/rmt0.1*
instead of */dev/rmt0*). Typically, only the superuser can access tape
devices.
If this is the only option specified, the status of the device will be
displayed. To retrieve more detailed status information, add
**--detail**. If you are root and the status command fails, either the
*device* is incorrect (try another link to the device: */dev/rmt0.1*,
*/dev/nst0*, */dev/tape*, etc.), a tape may not be in the drive, you may
be using the wrong algorithm for the tape drive (see the **-a** option),
or the device does not support SCSI Security Protocol. **stenc** 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 *Unable to determine* for the volume
encryption status, you may need to move to a section of the tape that
contains data (i.e. **mt -f <device> fsr <count>**) or rewind the tape
in order for **stenc** to output the volume status.
If this option is omitted, and the environment variable **TAPE** is
set, it is used. Otherwise, a default device defined in the system header
*mtio.h* is used.
**-e** **on** \| **mixed** \| **rawread** \| **off**
Sets the encryption mode for the device specified with **-f** option.
Successful operations of this type will create an audit entry in the
system log. If **off** is not specified and the **-k**
option is not specified, the program will require the user to enter a
hexadecimal key (see *KEY INPUT SYNTAX*) and an optional key
description (see *KEY DESCRIPTORS*).
**on** - 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.
**mixed** - 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.
**rawread** - 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 **--unprotect** when the data was written in order to read it
with this option. Some drives do not support this option. See the
**--protect** option.
**off** - 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
**WARNING:** 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 **-k**
option to prevent the system from waiting on the local console user to
enter the encryption key.
**-a** *index*
Only valid when setting encryption (see the **-e** 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
**-a, --algorithm**=\ *index*
Selects the encryption algorithm to use for the device.
Changing encryption settings may fail on some devices if this is not a
supported algorithm for the drive (e.g. HP drives use an algorithm
index of 1). A list of supported algorithms can be obtained by requesting
drive status information with the **--detail** option.
device status. If the device only
supports one algorithm, this option may be omitted and **stenc** will use
the only choice. Otherwise **stenc** will print the list of supported algorithms
and exit if this option is omitted.
**-k, --key-file**=\ *FILE* \| *-*
Read the encryption key and optional key descriptor from *FILE*, or
standard input when *FILE* is *-*. If standard input is a terminal,
this will prompt for the key and optional key
descriptor. This option is required when *ENC-MODE* and *DEC-MODE*
are not both *off*. See *KEY INPUT SYNTAX* for the expected format of the
key file.
**--ckod**
Only valid when setting encryption (see the **-e** 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.
Clear key on demount. Instructs the device to clear its encryption keys when
the tape is unloaded instead of keeping it until the drive is power cycled.
This option may only be given if tape media is presently loaded in the
device. Some devices may not support this option.
**--protect** \| **--unprotect**
Only valid when setting encryption (see the **-e** option). Instructs
the drive to **protect** or **unprotect** any encrypted data from
being raw read. See the **-e rawread** option. Some devices may not
support these options.
**--allow-raw-read** \| **--no-allow-raw-read**
Instructs the device to mark encrypted blocks written to the tape to allow
(or disallow) subsequent raw mode reads. If neither option is given, the
device default is used, which can be found by requesting the device status.
Some devices may not support these options.
**-k** *file*
When turning encryption on, this specifies the location of a key file.
**-h, --help**
Print a usage message and exit.
**--version**
Print version information and exit.
KEY INPUT SYNTAX
================
**stenc** requires that all keys are entered using 2 digit hexadecimal bytes, with no delimiters in between bytes. Do not precede your key input with '0x'. 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 *KEY DESCRIPTORS*).
**stenc** requires that all keys are entered as text hexadecimal strings,
with no delimiters in between bytes. Do not precede your key input with *0x*.
When using a key file, the second line in the file can contain an optional
key descriptor that will be displayed with the device status (see
*KEY DESCRIPTORS*).
Keys can be generated using any cryptographically secure entropy source,
such as the **random**(4) device or the **openssl**(1SSL) suite of commands.
such as the **random**\ (4) device or the **openssl**\ (1SSL) suite of commands.
A 256-bit key file can be created with the following command:
openssl rand -hex 32
@@ -138,56 +143,49 @@ A 256-bit key file can be created with the following command:
| 000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f
| April backup key
EXAMPLE
=======
KEY DESCRIPTORS
===============
**stenc -f /dev/nst0 -e on -k /etc/stenc.key**
Turns on encryption on /dev/nst0 using the key contained in
/etc/stenc.key
**stenc -f /dev/nst0 -e on**
Asks user to input a key in hexadecimal format and then turns on
encryption for /dev/nst0 using that key
**stenc -f /dev/nst0 -e off**
Turns off encryption for /dev/nst0
**stenc -f /dev/nst0 --detail**
Outputs the detailed encryption status of /dev/nst0
A key file (see *KEY INPUT SYNTAX*) can optionally include a key descriptor.
The descriptor will be written with each tape block, and will be displayed
when retrieving the drive status, so it should *never* contain information
that would reduce the security of the key (i.e. a checksum or any portion of
the key). If **stenc** detects a tape block is encrypted but it cannot decrypt
the data, the key descriptor of the current block, if any, will be displayed
as part of the device status. This can be useful for determining which key
is used.
KEY CHANGE AUDITING
===================
Each time a key is changed using this program, a corresponding entry
will be entered in the system log. These entries will have
an *Key Instance Counter* corresponding to the counter listed in the
device status (see the **-f** option). Each time the key is set, the
key descriptor, if any, 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.
Each time device encryption settings are changed, **stenc** will write an
entry to the system log. These entries will have a *Key Instance Counter*
corresponding to the counter listed in the device status. Each time the key
is set, the key descriptor, if any, is also written to the log. This allows
you to know when keys were changed and if the key you are using is the same
as a prior key.
KEY DESCRIPTORS
===============
EXAMPLE
=======
Key descriptors are set when using the **-e**
option. They will be displayed when retrieving the drive status (see the
**-f** 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
**stenc** 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.
**stenc -f /dev/nst0 -e on -d on -k /etc/stenc.key**
Turns on encryption and decryption for */dev/nst0* using the key
in */etc/stenc.key*
REPORTING BUGS
==============
**stenc -f /dev/nst0 -e on -d mixed -k -**
Asks user to input a key in hexadecimal format and then turns on
encryption, with mixed decryption mode, for */dev/nst0*
Report **stenc** bugs to https://github.com/scsitape/stenc/issues
**stenc -f /dev/nst0 -e off -d off**
Turns off encryption and decryption for */dev/nst0*
PROJECT UPDATES
===============
**stenc -f /dev/nst0**
Prints the encryption status of */dev/nst0*
Visit **https://github.com/scsitape/stenc** for more information.
BUGS
====
Report bugs to **https://github.com/scsitape/stenc/issues**
COPYRIGHT
=========