Crypt::Mode::XTS(3)   User Contributed Perl Documentation  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
       o   CryptX, Crypt::Cipher

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

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

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

perl v5.42.2                      2026-08-10               Crypt::Mode::XTS(3)