STENC(1)

📦
version 2.0.1 · 3 versions
, in ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

stenc — the SCSI Tape Hardware Encryption Manager ✨

okay so bestie, this is the STENC(1) page from your General Commands Manual, and it's literally the tool that bosses your tape drive's hardware encryption around. sit down, grab a boba, we're doing this 💅

🌸 SYNOPSIS 🌸

stenc [-f DEVICE]
stenc [-f DEVICE] [-e ENC-MODE] [-d DEC-MODE] [OPTIONS]

🦋 DESCRIPTION 🦋

stenc handles hardware data encryption on tape devices that speak the SCSI security protocol. no cap, that's the whole gig.

🔐 Controlling device encryption

The encryption mode (aka what happens to data you write to the device) and the decryption mode</c> (aka what happens to data you read from the device) are two totally independent little guys. But here's the tea: if you only hand over one of the following options, the other mode gets inferred so both encryption and decryption move in tandem. besties who sync 💞

  • -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. (yes, that's the original wording, and honestly? it's giving nothing. no encryption, periodt.)
    • 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 will only read data it's actually able to decrypt, and it will not read unencrypted data on the drive. picky queen 🙈
    • mixed — data read from the device will be decrypted, if needed. both encrypted and unencrypted tape blocks can be read. the drive reads both encrypted data and unencrypted data, provided the drive is able to do so. she's flexible, she's versatile, she contains multitudes ✨

👀 Viewing device status

When you give neither of the options that set encryption or decryption mode, stenc spills the tea instead: it prints the encryption settings, the encryption status of the current block, and the capabilities of the device, including a whole list of supported algorithm indexes. so informative, so iconic 💅

The device may display the current block encryption status as Unable to determine if the tape is positioned at a filemark or end of tape. in that case you might need to move the tape position using mt(1). scoot her along bestie 🎀

✨ OPTIONS ✨

  • -f, --file=DEVICE — says which device to use (like /dev/nst0, /dev/nsa0, /dev/rmt0.1). use the lsscsi(8) command on Linux, or camcontrol(8) on FreeBSD, to figure out which device is the right one. highly recommend you use a non-rewinding device (i.e. /dev/nst0 instead of /dev/st0, /dev/rmt0.1 instead of /dev/rmt0) — she's the main character, don't make her rewind. typically, only the superuser can access tape devices, so bring your crown 👑
    • If this option is omitted, and the environment variable TAPE is set, then TAPE is used. Otherwise, a default device defined in the system header mtio.h gets used. defaults are always lurking 🫶
  • -a, --algorithm=index — picks the encryption algorithm to use for the device. changing encryption settings may fail on some devices if this isn't a supported algorithm for the drive (e.g. HP drives use an algorithm index of 1). you can get a list of supported algorithms by requesting device status. if the device only supports one algorithm, you can skip this option and stenc will use the only choice. otherwise, if you omit this option, stenc will print the list of supported algorithms and exit. she's not guessing for you 💀
  • -k, --key-file=FILE | - — reads the encryption key and optional key descriptor from FILE, or from 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 — Clear key on demount. tells the device to clear its encryption keys when the tape is unloaded instead of keeping them 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. memory? cleared. she's onto the next chapter 💅
  • --allow-raw-read | --no-allow-raw-read — tells 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 you can find by requesting the device status. some devices may not support these options. your tape, your rules 🌈
  • -h, --help — prints a usage message and exits. the classic cry for help, but helpful 🫶
  • --version — prints version information and exits. she's telling you who she is ✨

🧚 KEY INPUT SYNTAX 🧚

stenc requires that all keys are entered as text hexadecimal strings, with no delimiters in between bytes. do not put 0x in front of your key input. when you use a key file, the second line in the file can hold an optional key descriptor that will be displayed with the device status (peep KEY DESCRIPTORS).

Keys can be generated using any cryptographically secure entropy source, like the random(4) device or the openssl(1SSL) suite of commands. a 256-bit key file can be created with this command:

openssl rand -hex 32

Example 128 bit key:

000102030405060708090a0b0c0d0e0f

Example 256 bit key:

000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f

Example 256 key file with key descriptor:

000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f
April backup key

💜 KEY DESCRIPTORS 💜

A key file (see KEY INPUT SYNTAX) can optionally include a key descriptor. the descriptor gets written with each tape block, and it gets displayed when you retrieve 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). do not do that bestie, that's not the vibe 🙈

If stenc detects a tape block is encrypted but it can't 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 figuring out which key is used. detective work, but make it cute 🔍✨

🔥 KEY CHANGE AUDITING 🔥

Every single time device encryption settings get changed, stenc writes 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 lets you know when keys were changed, and whether the key you're using is the same as a prior key. receipts, always receipts 🧾💅

🌈 EXAMPLE 🌈

  • 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
  • stenc -f /dev/nst0 -e on -d mixed -k - asks the user to input a key in hexadecimal format and then turns on encryption, with mixed decryption mode, for /dev/nst0
  • stenc -f /dev/nst0 -e off -d off turns off encryption and decryption for /dev/nst0
  • stenc -f /dev/nst0 prints the encryption status of /dev/nst0

💀 BUGS 💀

Report bugs to https://github.com/scsitape/stenc/issues — tell them everything, they wanna know 🫶

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. (the NO WARRANTY is in all caps because it means it, bestie 😭)

🍓 SEE ALSO 🍓

and that's the whole page, periodt 💖 this was STENC(1) from the General Commands Manual, section 1 — go forth and encrypt your tapes responsibly, you absolute icon 👑✨

📦 where this page comes from