| 1 | package Crypt::Mode::XTS; | ||
| 2 | |||
| 3 | ### hand-written module - unlike other Crypt::Mode::* this file is NOT generated | ||
| 4 | |||
| 5 | 3 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 3 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | 3 | our $VERSION = '0.091'; | |
| 8 | |||
| 9 | 3 | ▶ | use CryptX; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | |||
| 11 | # new, encrypt, decrypt are implemented in XS | ||
| 12 | |||
| 13 | 0 | ▶ | sub CLONE_SKIP { 1 } # prevent cloning |
|
Subroutine
CLONE_SKIP: not called CC=1 SCAR=6.9
| |||
| 14 | |||
| 15 | 3 | 1; | |
| 16 | |||
| 17 | =pod | ||
| 18 | |||
| 19 | =head1 NAME | ||
| 20 | |||
| 21 | Crypt::Mode::XTS - Block cipher mode XTS [XEX-based tweaked-codebook mode with ciphertext stealing] | ||
| 22 | |||
| 23 | =head1 SYNOPSIS | ||
| 24 | |||
| 25 | use Crypt::Mode::XTS; | ||
| 26 | |||
| 27 | my $xts = Crypt::Mode::XTS->new('AES', $key); # $key = key1 || key2 | ||
| 28 | |||
| 29 | # one complete data unit (sector) per call; same object does both directions | ||
| 30 | my $ct = $xts->encrypt($plaintext, $tweak); | ||
| 31 | my $pt = $xts->decrypt($ciphertext, $tweak); | ||
| 32 | |||
| 33 | # tweak: 16-byte string, or a data-unit number | ||
| 34 | my $ct1 = $xts->encrypt($sector, "\x02" . "\x00" x 15); | ||
| 35 | my $ct2 = $xts->encrypt($sector, 2); # same thing (64-bit LE, zero-padded) | ||
| 36 | |||
| 37 | # the canonical loop - key schedules computed exactly once, in new() | ||
| 38 | my $unit = 0; | ||
| 39 | while (my $n = sysread $in, my $sector, 4096) { | ||
| 40 | syswrite $out, $xts->encrypt($sector, $unit++); | ||
| 41 | } | ||
| 42 | |||
| 43 | =head1 DESCRIPTION | ||
| 44 | |||
| 45 | This module implements the XTS cipher mode as specified by IEEE 1619-2007 and | ||
| 46 | NIST SP 800-38E, including ciphertext stealing for data units that are not a | ||
| 47 | multiple of the block size. B<Note:> It works only with 128-bit block ciphers | ||
| 48 | from L<CryptX> ('AES', 'Twofish', 'Serpent', 'Camellia', 'ARIA', 'SM4', ...). | ||
| 49 | |||
| 50 | B<BEWARE: XTS provides confidentiality only - no integrity, no authentication.> | ||
| 51 | A bit-flip in the ciphertext garbles exactly the corresponding 16-byte | ||
| 52 | plaintext block, predictably positioned - that's malleability by design. XTS | ||
| 53 | is for encrypting storage in place, where the tweak is implicit in the | ||
| 54 | location and there is no room for a MAC. For anything that travels - files, | ||
| 55 | messages, backups - use an AEAD mode (C<Crypt::AuthEnc::*>) instead. Also be | ||
| 56 | aware that an attacker with two snapshots of the same device sees which | ||
| 57 | blocks changed. | ||
| 58 | |||
| 59 | Unlike the other C<Crypt::Mode::*> modules, XTS is not an online mode | ||
| 60 | (ciphertext stealing needs the complete data unit), so there is no | ||
| 61 | C<start_encrypt>/C<add>/C<finish> API and this module does not subclass | ||
| 62 | L<Crypt::Mode>. One C<encrypt>/C<decrypt> call processes exactly one complete | ||
| 63 | data unit. Ciphertext length always equals plaintext length. | ||
| 64 | |||
| 65 | =head1 METHODS | ||
| 66 | |||
| 67 | =head2 new | ||
| 68 | |||
| 69 | my $xts = Crypt::Mode::XTS->new($cipher, $key); | ||
| 70 | #or | ||
| 71 | my $xts = Crypt::Mode::XTS->new($cipher, $key, $cipher_rounds); | ||
| 72 | |||
| 73 | # $cipher .......... [string] cipher with 128-bit blocks, e.g. 'AES', 'Twofish', | ||
| 74 | # 'Serpent', 'Camellia', 'ARIA', 'SM4' | ||
| 75 | # or any <NAME> for which there is a Crypt::Cipher::<NAME> | ||
| 76 | # module with a 16-byte block size | ||
| 77 | # $key ............. [binary string] key1 || key2, each half a valid key for the | ||
| 78 | # cipher; for AES that means 32, 48 or 64 bytes total | ||
| 79 | # $cipher_rounds ... [integer] optional, number of rounds for the given cipher | ||
| 80 | # (0 or omitted = the cipher's standard number of rounds) | ||
| 81 | |||
| 82 | Both key schedules are computed here, exactly once; C<encrypt>/C<decrypt> | ||
| 83 | only use the schedules. The raw key is not stored in the object and the | ||
| 84 | schedules are zeroized on object destruction. | ||
| 85 | |||
| 86 | Croaks if the cipher does not have 128-bit blocks, if either key half is not | ||
| 87 | a valid key size for the cipher, and - per FIPS 140 Implementation Guidance | ||
| 88 | A.9 - if C<key1> equals C<key2> (that configuration degrades XTS toward ECB | ||
| 89 | on single-block data units). | ||
| 90 | |||
| 91 | The returned object is direction-free: the same object encrypts and decrypts. | ||
| 92 | |||
| 93 | =head2 encrypt | ||
| 94 | |||
| 95 | my $ct = $xts->encrypt($plaintext, $tweak); | ||
| 96 | |||
| 97 | Encrypts one complete data unit (e.g. one disk sector). Returns the | ||
| 98 | ciphertext as a binary string of the same length as the plaintext. | ||
| 99 | |||
| 100 | C<$plaintext> must be at least 16 bytes (one full cipher block); any length | ||
| 101 | above that is fine, including lengths that are not a multiple of 16 | ||
| 102 | (ciphertext stealing handles the final partial block). Croaks above 2^20 | ||
| 103 | blocks (16MiB) - the NIST SP 800-38E bound per data unit. | ||
| 104 | |||
| 105 | C<$tweak> is either exactly 16 binary bytes, or a non-negative integer | ||
| 106 | < 2^64 that is encoded as 64-bit little-endian and zero-padded to 16 bytes | ||
| 107 | (the "data unit sequence number" convention - identical to dm-crypt plain64 | ||
| 108 | and to what OpenSSL and kernel test vectors use). B<Note:> a 16-byte string | ||
| 109 | is always taken as a raw binary tweak, even if it consists of digits. | ||
| 110 | |||
| 111 | =head2 decrypt | ||
| 112 | |||
| 113 | my $pt = $xts->decrypt($ciphertext, $tweak); | ||
| 114 | |||
| 115 | Decrypts one complete data unit. Returns the plaintext as a binary string of | ||
| 116 | the same length as the ciphertext. Same rules for C<$ciphertext> and | ||
| 117 | C<$tweak> as in L</encrypt>. | ||
| 118 | |||
| 119 | =head1 SEE ALSO | ||
| 120 | |||
| 121 | =over | ||
| 122 | |||
| 123 | =item * L<CryptX>, L<Crypt::Cipher> | ||
| 124 | |||
| 125 | =item * L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::ChaCha20Poly1305> - authenticated encryption, for data that travels | ||
| 126 | |||
| 127 | =item * L<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS> | ||
| 128 | |||
| 129 | =item * L<https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38e.pdf> | ||
| 130 | |||
| 131 | =back | ||
| 132 | |||
| 133 | =cut | ||