Clarify option syntax for 2.0

[jmwilson]

Continuing from #61, I think the option names could use some clarifying in 2.0 where we can consider breaking changes. I've mocked up a few possibilities and command option trees, in increasing order of complexity of documenting them and implementing.

As noted in #61 raw mode is an advanced feature made for duplicating blocks from one tape to another without having to enroll the encryption key into both drives. There's a good case for leaving this out of a utility where it won't be used. On the other hand, to actually support advanced functionality, we should also allow the external encryption mode where writes to the drive are assumed to be pre-encrypted.

Option 1 (subcommands and simplified syntax, remove raw mode):

stenc [-f device] on [--mixed-decrypt] [-a index|--algorithm=index]
    [-k file|--key-file=file] [--key-descriptor=key name] [--ckod]
stenc [-f device] off [-a index|--algorithm=index]
stenc [-f device] status
stenc [-f device] --version
stenc [-f device] [-h|--help]

Option 2 (subcommands with clarified option names, keep raw mode):

stenc [-f device] on [--mixed-decrypt|--raw-decrypt] [-a index|--algorithm=index]
    [-k file|--key-file=file] [--key-descriptor=key name] [--allow-raw-read|--disallow-raw-read] [--ckod]
stenc [-f device] off [-a index|--algorithm=index]
stenc [-f device] status
stenc [-f device] --version
stenc [-f device] [-h|--help]

Option 3 (independent encrypt and decrypt settings):

stenc [-f device] [-e (off|on|external)|--encrypt=(off|on|external)]
    [-d (off|on|mixed|raw)|--decrypt=(off|on|mixed|raw)] [-a index|--algorithm=index]
    [-k file|--key-file=file] [--key-descriptor=key name]
    [--allow-raw-read|--disallow-raw-read] [--ckod]
stenc [-f device] --status
stenc [-f device] --version
stenc [-f device] [-h|--help]

Constraints:

• if --encrypt=on, and --decrypt not given, use --decrypt=on (backward compatible with current syntax)
• if --decrypt=on|mixed, and --encrypt not given, use --encrypt=on
• if --encrypt=external, and --decrypt not given, use --decrypt=on when a key file is given and --decrypt=off when no key file given
• cannot give --key-file or --key-descriptor without either --encrypt=on or --decrypt=on|mixed
• cannot give --ckod without either --encrypt=on or --decrypt=on|mixed
• cannot give --allow-raw-read or --disallow-raw-read with --encrypt=off

[jmwilson]

Researching about the external mode, I found it may need a "metadata KAD" obtained from the copy source before it will work. Hence my hesitation about these advanced modes; by cutting out external & raw, most of the not recommended states can be avoided. The following table is for IBM drives. A metadata KAD is required in external encrypt mode and prohibited otherwise. In working with a HP drive, the metadata KAD is also needed for RAW read regardless of encrypt mode, so correctly handling external & raw modes looks like it requires vendor-specific code.

[jmwilson]

I did some tests with raw decrypt mode on my HP LTO-6 drive and getting it to work was a bit complicated. First I see an error when trying to dump the encrypted block:

# stenc -f /dev/st0 -e rawread -a 1 -k test_key.key
# dd if=/dev/st0 bs=256K | od -t x1
dd: error reading '/dev/st0': Input/output error
# dmesg -t
st 1:0:0:0: [st0] Sense Key : 0x7 [current]
st 1:0:0:0: [st0] ASC=0x74 ASCQ=0xb

The HP LTO-6 reference says this about the error:

So I made a hack to stenc to do exactly this. After turning on raw decrypt mode, it gets the next block encryption status and re-sends the command to set encryption, using this key descriptor it received. The key descriptor that is returned is a metadata KAD (type 3) and 140 bytes long. It includes the key identifier string I used but a lot of other data. Now the dd command above succeeds.

I think only HP drives do this, and it is based on an interpretation of the SCSI Stream Commands reference:

If the encryption algorithm in use by the KCSLU (keyless copy source drive) requires key-associated data to be included in the Set Data Encryption page if the ENCRYPTION MODE field is set to EXTERNAL, then an attempt to read or verify an encrypted logical block while the decryption mode is set to RAW shall cause the KCSLU to compare all key-associated data associated with each encrypted logical block that is read or verified to the corresponding key-associated data that are part of the current encryption parameters. Key-associated data required to be compared by the decryption algorithm that do not match or are not present shall cause the KCSLU to terminate the command with CHECK CONDITION status, with the sense key set to DATA PROTECT, and the additional sense code set to INCORRECT ENCRYPTION PARAMETERS. The KCSLU shall establish the logical position at the BOP side of the logical block.

I do not have an IBM drive to test, but IBM's reference manual (see earlier comment) says the metadata KAD is not required (in fact, prohibited) when using raw decrypt mode, and required for external encrypt mode.

This means to do raw mode and external encrypt mode correctly, stenc will need to support getting, saving, and sending the metadata KAD from a tape block. Because of the complexity and chance for error, I recommend simply removing raw mode from the program. HP even says this about keyless copy in their LTO-8 reference manual:

For these reasons, Hewlett Packard Enterprise does not recommend supporting keyless copy in applications. The safest way to successfully and securely create copies of encrypted tapes is to use the encryption key when reading, transfer the data to the new tape in the clear, and re-encrypt it in the destination tape drive using the same key (and key-associated data).

After thinking some more about the command syntax, it is probably better to keep compatibility instead of using a subcommand syntax that will break scripts, but also drop support for raw mode that is a headache. This change still allows for independent settings for encrypt mode and decrypt mode:

stenc [-f device] [-e on|off] [-d on|mixed|off] [-a algorithm-index] [-k file] [--ckod]
stenc --version
stenc [-h|--help]

• Setting only one of -e or -d without the other will set both encrypt and decrypt modes in tandem for backward compatibility. -d mixed without -e will use -e on.
• -k only allowed when a key is being set (-e on or -d on or -d mixed)
• --ckod only allowed when a key is being set and tape is loaded
• when neither -e nor -d given, print the detailed status (no need for explicit --status)