Crypt::Mode::XTS(3)

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

•   CryptX, Crypt::Cipher

•   Crypt::AuthEnc::GCM, Crypt::AuthEnc::ChaCha20Poly1305 - authenticated encryption, for data that travels

•   <https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>

•   <https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38e.pdf>