| 1 | package Crypt::AuthEnc::SIV; | ||
| 2 | |||
| 3 | 3 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 3 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | 3 | our $VERSION = '0.091'; | |
| 6 | |||
| 7 | 3 | require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import'; | |
| 8 | 3 | our %EXPORT_TAGS = ( all => [qw( siv_encrypt_authenticate siv_decrypt_verify )] ); | |
| 9 | 3 | our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); | |
| 10 | 3 | our @EXPORT = qw(); | |
| 11 | |||
| 12 | 3 | ▶ | use Carp; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 13 | 3 | $Carp::Internal{(__PACKAGE__)}++; | |
| 14 | 3 | ▶ | use CryptX; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 15 | |||
| 16 | 3 | 1; | |
| 17 | |||
| 18 | =pod | ||
| 19 | |||
| 20 | =head1 NAME | ||
| 21 | |||
| 22 | Crypt::AuthEnc::SIV - Authenticated encryption in SIV mode | ||
| 23 | |||
| 24 | =head1 SYNOPSIS | ||
| 25 | |||
| 26 | use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify ); | ||
| 27 | |||
| 28 | my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext); | ||
| 29 | my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext, $adata); | ||
| 30 | my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext, [$ad1, $ad2, ...]); | ||
| 31 | |||
| 32 | my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext); | ||
| 33 | my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext, $adata); | ||
| 34 | my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext, [$ad1, $ad2, ...]); # undef on failure | ||
| 35 | |||
| 36 | =head1 DESCRIPTION | ||
| 37 | |||
| 38 | I<Since: CryptX-0.089> | ||
| 39 | |||
| 40 | SIV (Synthetic IV) is a deterministic authenticated encryption scheme defined in | ||
| 41 | L<RFC 5297|https://www.rfc-editor.org/rfc/rfc5297>. Unlike nonce-based modes, SIV derives | ||
| 42 | the authentication tag (the IV) synthetically from the key, associated data, and plaintext, | ||
| 43 | making it nonce-misuse resistant. | ||
| 44 | |||
| 45 | The output of C<siv_encrypt_authenticate> is the 16-byte SIV tag prepended to the ciphertext | ||
| 46 | (total output length is C<length($plaintext) + 16>). | ||
| 47 | |||
| 48 | B<BEWARE:> SIV requires a key that is twice the length of the underlying cipher key | ||
| 49 | (e.g. 256 bits for AES-128-SIV, 512 bits for AES-256-SIV). | ||
| 50 | |||
| 51 | If you pass associated data as an arrayref, at most 126 components are accepted. | ||
| 52 | |||
| 53 | =head2 No associated data vs. empty associated data | ||
| 54 | |||
| 55 | RFC 5297 feeds C<S2V> a I<list> of strings (C<AD1..ADm>, then the plaintext), and the | ||
| 56 | number of components changes the result. Passing B<no> associated data is therefore | ||
| 57 | not the same as passing B<one empty> associated data string: | ||
| 58 | |||
| 59 | siv_encrypt_authenticate('AES', $key, $pt); # zero AD components | ||
| 60 | siv_encrypt_authenticate('AES', $key, $pt, undef); # zero AD components | ||
| 61 | siv_encrypt_authenticate('AES', $key, $pt, []); # zero AD components | ||
| 62 | |||
| 63 | siv_encrypt_authenticate('AES', $key, $pt, ""); # ONE empty AD component | ||
| 64 | siv_encrypt_authenticate('AES', $key, $pt, [""]); # ONE empty AD component | ||
| 65 | |||
| 66 | The two groups produce different tags, and ciphertext produced by one does not | ||
| 67 | verify under the other. | ||
| 68 | |||
| 69 | Beware that some other libraries expose only a single associated data argument and | ||
| 70 | so cannot express the zero-component case at all; when interoperating with those, | ||
| 71 | an "empty" associated data string usually corresponds to the C<""> form above. | ||
| 72 | |||
| 73 | C<undef> elements inside an arrayref are skipped rather than folded as empty | ||
| 74 | components, so C<[$ad1, undef, $ad2]> is equivalent to C<[$ad1, $ad2]>. | ||
| 75 | |||
| 76 | =head1 EXPORT | ||
| 77 | |||
| 78 | Nothing is exported by default. | ||
| 79 | |||
| 80 | You can export selected functions: | ||
| 81 | |||
| 82 | use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify ); | ||
| 83 | |||
| 84 | =head1 FUNCTIONS | ||
| 85 | |||
| 86 | =head2 siv_encrypt_authenticate | ||
| 87 | |||
| 88 | my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext); | ||
| 89 | #or | ||
| 90 | my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext, $adata); | ||
| 91 | #or | ||
| 92 | my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext, [$ad1, $ad2, ...]); | ||
| 93 | |||
| 94 | # $cipher ... [string] cipher name (e.g. 'AES') | ||
| 95 | # $key ... [binary string] key (must be double the cipher's standard key length) | ||
| 96 | # $plaintext ... [binary string] plaintext to encrypt | ||
| 97 | # $adata ... [binary string | arrayref] optional associated data: a scalar string or an arrayref of up to 126 string/buffer scalars | ||
| 98 | |||
| 99 | Returns a string of C<length($plaintext) + 16> bytes (16-byte SIV tag prepended to ciphertext). | ||
| 100 | |||
| 101 | The required C<$key> and C<$plaintext> arguments must be string/buffer scalars. | ||
| 102 | If C<$adata> is given as a scalar, it must also be a string/buffer scalar. If | ||
| 103 | it is given as an arrayref, each defined element must be a string/buffer scalar. | ||
| 104 | String-overloaded objects are accepted. | ||
| 105 | |||
| 106 | =head2 siv_decrypt_verify | ||
| 107 | |||
| 108 | my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext); | ||
| 109 | #or | ||
| 110 | my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext, $adata); | ||
| 111 | #or | ||
| 112 | my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext, [$ad1, $ad2, ...]); | ||
| 113 | |||
| 114 | # $cipher ... [string] cipher name (e.g. 'AES') | ||
| 115 | # $key ... [binary string] key (must be double the cipher's standard key length) | ||
| 116 | # $ciphertext ... [binary string] ciphertext with 16-byte SIV tag prepended | ||
| 117 | # $adata ... [binary string | arrayref] optional associated data: a scalar string or an arrayref of up to 126 string/buffer scalars | ||
| 118 | |||
| 119 | Returns the plaintext on success, or C<undef> if authentication fails. | ||
| 120 | Malformed ciphertext shorter than 16 bytes croaks because it cannot contain the required | ||
| 121 | prepended SIV tag. | ||
| 122 | |||
| 123 | The required C<$key> and C<$ciphertext> arguments must be string/buffer | ||
| 124 | scalars. If C<$adata> is given as a scalar, it must also be a | ||
| 125 | string/buffer scalar. If it is given as an arrayref, each defined element | ||
| 126 | must be a string/buffer scalar. String-overloaded objects are accepted. | ||
| 127 | |||
| 128 | =head1 SEE ALSO | ||
| 129 | |||
| 130 | =over | ||
| 131 | |||
| 132 | =item * L<CryptX>, L<Crypt::AuthEnc::EAX>, L<Crypt::AuthEnc::GCM> | ||
| 133 | |||
| 134 | =item * L<RFC 5297|https://www.rfc-editor.org/rfc/rfc5297> | ||
| 135 | |||
| 136 | =back | ||
| 137 | |||
| 138 | =cut | ||