blib/lib/Crypt/Mode/XTS.pm

filter: Statementstmt 91.6% 11 / 12 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 75.0% 3 / 4 Podpod n/a totaltotal 87.5% 14 / 16 CC 1 SCAR 2.2
CC
1
Cov
92%
CLONE_SKIP
2.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.2
« blib/lib/Crypt/AuthEnc/EAX.pm ↑ Summary blib/lib/Crypt/Digest/BLAKE2b_160.pm »
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
« blib/lib/Crypt/AuthEnc/EAX.pm ↑ Summary blib/lib/Crypt/Digest/BLAKE2b_160.pm »