/ 
CryptX-0.091
⭐ Starred 36 / Crypt::Mode::XTS

NAME

Crypt::Mode::XTS - Block cipher mode XTS [XEX-based tweaked-codebook mode with ciphertext stealing]

SYNOPSIS

use Crypt::Mode::XTS;

my $xts = Crypt::Mode::XTS->new('AES', $key);   # $key = key1 || key2

# one complete data unit (sector) per call; same object does both directions
my $ct = $xts->encrypt($plaintext,  $tweak);
my $pt = $xts->decrypt($ciphertext, $tweak);

# tweak: 16-byte string, or a data-unit number
my $ct1 = $xts->encrypt($sector, "\x02" . "\x00" x 15);
my $ct2 = $xts->encrypt($sector, 2);            # same thing (64-bit LE, zero-padded)

# the canonical loop - key schedules computed exactly once, in new()
my $unit = 0;
while (my $n = sysread $in, my $sector, 4096) {
  syswrite $out, $xts->encrypt($sector, $unit++);
}

DESCRIPTION

This module implements the XTS cipher mode as specified by IEEE 1619-2007 and NIST SP 800-38E, including ciphertext stealing for data units that are not a multiple of the block size. Note: It works only with 128-bit block ciphers from CryptX ('AES', 'Twofish', 'Serpent', 'Camellia', 'ARIA', 'SM4', ...).

BEWARE: XTS provides confidentiality only - no integrity, no authentication. A bit-flip in the ciphertext garbles exactly the corresponding 16-byte plaintext block, predictably positioned - that's malleability by design. XTS is for encrypting storage in place, where the tweak is implicit in the location and there is no room for a MAC. For anything that travels - files, messages, backups - use an AEAD mode (Crypt::AuthEnc::*) instead. Also be aware that an attacker with two snapshots of the same device sees which blocks changed.

Unlike the other Crypt::Mode::* modules, XTS is not an online mode (ciphertext stealing needs the complete data unit), so there is no start_encrypt/add/finish API and this module does not subclass Crypt::Mode. One encrypt/decrypt call processes exactly one complete data unit. Ciphertext length always equals plaintext length.

METHODS

new

my $xts = Crypt::Mode::XTS->new($cipher, $key);
#or
my $xts = Crypt::Mode::XTS->new($cipher, $key, $cipher_rounds);

# $cipher .......... [string] cipher with 128-bit blocks, e.g. 'AES', 'Twofish',
#                    'Serpent', 'Camellia', 'ARIA', 'SM4'
#                    or any <NAME> for which there is a Crypt::Cipher::<NAME>
#                    module with a 16-byte block size
# $key ............. [binary string] key1 || key2, each half a valid key for the
#                    cipher; for AES that means 32, 48 or 64 bytes total
# $cipher_rounds ... [integer] optional, number of rounds for the given cipher
#                    (0 or omitted = the cipher's standard number of rounds)

Both key schedules are computed here, exactly once; encrypt/decrypt only use the schedules. The raw key is not stored in the object and the schedules are zeroized on object destruction.

Croaks if the cipher does not have 128-bit blocks, if either key half is not a valid key size for the cipher, and - per FIPS 140 Implementation Guidance A.9 - if key1 equals key2 (that configuration degrades XTS toward ECB on single-block data units).

The returned object is direction-free: the same object encrypts and decrypts.

encrypt

my $ct = $xts->encrypt($plaintext, $tweak);

Encrypts one complete data unit (e.g. one disk sector). Returns the ciphertext as a binary string of the same length as the plaintext.

$plaintext must be at least 16 bytes (one full cipher block); any length above that is fine, including lengths that are not a multiple of 16 (ciphertext stealing handles the final partial block). Croaks above 2^20 blocks (16MiB) - the NIST SP 800-38E bound per data unit.

$tweak is either exactly 16 binary bytes, or a non-negative integer < 2^64 that is encoded as 64-bit little-endian and zero-padded to 16 bytes (the "data unit sequence number" convention - identical to dm-crypt plain64 and to what OpenSSL and kernel test vectors use). Note: a 16-byte string is always taken as a raw binary tweak, even if it consists of digits.

decrypt

my $pt = $xts->decrypt($ciphertext, $tweak);

Decrypts one complete data unit. Returns the plaintext as a binary string of the same length as the ciphertext. Same rules for $ciphertext and $tweak as in "encrypt".

SEE ALSO