diff --git a/man/stenc.rst b/man/stenc.rst index 4963740..b093d7f 100644 --- a/man/stenc.rst +++ b/man/stenc.rst @@ -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 fsr **) 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 =========