| 1 | package Crypt::Mac::XCBC; | ||
| 2 | |||
| 3 | ### BEWARE - GENERATED FILE, DO NOT EDIT MANUALLY! | ||
| 4 | |||
| 5 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 2 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | 2 | our $VERSION = '0.091'; | |
| 8 | |||
| 9 | 2 | ▶ | use base qw(Crypt::Mac Exporter); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | 2 | our %EXPORT_TAGS = ( all => [qw( xcbc xcbc_hex xcbc_b64 xcbc_b64u )] ); | |
| 11 | 2 | our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); | |
| 12 | 2 | our @EXPORT = qw(); | |
| 13 | |||
| 14 | 2 | 1; | |
| 15 | |||
| 16 | =pod | ||
| 17 | |||
| 18 | =head1 NAME | ||
| 19 | |||
| 20 | Crypt::Mac::XCBC - Message authentication code XCBC (RFC 3566) | ||
| 21 | |||
| 22 | =head1 SYNOPSIS | ||
| 23 | |||
| 24 | ### Functional interface: | ||
| 25 | use Crypt::Mac::XCBC qw( xcbc xcbc_hex xcbc_b64 xcbc_b64u ); | ||
| 26 | |||
| 27 | # calculate MAC from string/buffer | ||
| 28 | my $xcbc_raw = xcbc($cipher_name, $key, 'data buffer'); | ||
| 29 | my $xcbc_hex = xcbc_hex($cipher_name, $key, 'data buffer'); | ||
| 30 | my $xcbc_b64 = xcbc_b64($cipher_name, $key, 'data buffer'); | ||
| 31 | my $xcbc_b64u = xcbc_b64u($cipher_name, $key, 'data buffer'); | ||
| 32 | |||
| 33 | ### OO interface: | ||
| 34 | use Crypt::Mac::XCBC; | ||
| 35 | |||
| 36 | my $d = Crypt::Mac::XCBC->new($cipher_name, $key); | ||
| 37 | $d->add('any data'); | ||
| 38 | my $result_hex = $d->hexmac; # finalizes the object | ||
| 39 | |||
| 40 | # for another output encoding use a fresh object (or clone before finalizing) | ||
| 41 | my $result_b64u = Crypt::Mac::XCBC->new($cipher_name, $key)->add('any data')->b64umac; | ||
| 42 | |||
| 43 | # or MAC a file instead | ||
| 44 | my $file_result_raw = Crypt::Mac::XCBC->new($cipher_name, $key)->addfile('filename.dat')->mac; | ||
| 45 | |||
| 46 | =head1 DESCRIPTION | ||
| 47 | |||
| 48 | Provides an interface to the XCBC message authentication code (MAC) algorithm. | ||
| 49 | |||
| 50 | =head1 EXPORT | ||
| 51 | |||
| 52 | Nothing is exported by default. | ||
| 53 | |||
| 54 | You can export selected functions: | ||
| 55 | |||
| 56 | use Crypt::Mac::XCBC qw( xcbc xcbc_hex xcbc_b64 xcbc_b64u ); | ||
| 57 | |||
| 58 | Or all of them at once: | ||
| 59 | |||
| 60 | use Crypt::Mac::XCBC ':all'; | ||
| 61 | |||
| 62 | =head1 FUNCTIONS | ||
| 63 | |||
| 64 | =head2 xcbc | ||
| 65 | |||
| 66 | Joins all arguments into a single string and returns its XCBC message authentication code encoded as a binary string. | ||
| 67 | |||
| 68 | Data arguments for the functional helpers are converted to byte strings using | ||
| 69 | Perl's usual scalar stringification. Defined scalars, including numbers and | ||
| 70 | string-overloaded objects, are accepted. C<undef> is treated as an empty | ||
| 71 | string and may emit Perl's usual "uninitialized value" warning. The same | ||
| 72 | rules apply to C<xcbc_hex>, C<xcbc_b64>, and | ||
| 73 | C<xcbc_b64u>. | ||
| 74 | |||
| 75 | my $xcbc_raw = xcbc($cipher_name, $key, 'data buffer'); | ||
| 76 | #or | ||
| 77 | my $xcbc_raw = xcbc($cipher_name, $key, 'any data', 'more data', 'even more data'); | ||
| 78 | |||
| 79 | =head2 xcbc_hex | ||
| 80 | |||
| 81 | Joins all arguments into a single string and returns its XCBC message authentication code encoded as a hexadecimal string. | ||
| 82 | |||
| 83 | my $xcbc_hex = xcbc_hex($cipher_name, $key, 'data buffer'); | ||
| 84 | #or | ||
| 85 | my $xcbc_hex = xcbc_hex($cipher_name, $key, 'any data', 'more data', 'even more data'); | ||
| 86 | |||
| 87 | =head2 xcbc_b64 | ||
| 88 | |||
| 89 | Joins all arguments into a single string and returns its XCBC message authentication code encoded as a Base64 string. | ||
| 90 | |||
| 91 | my $xcbc_b64 = xcbc_b64($cipher_name, $key, 'data buffer'); | ||
| 92 | #or | ||
| 93 | my $xcbc_b64 = xcbc_b64($cipher_name, $key, 'any data', 'more data', 'even more data'); | ||
| 94 | |||
| 95 | =head2 xcbc_b64u | ||
| 96 | |||
| 97 | Joins all arguments into a single string and returns its XCBC message authentication code encoded as a Base64 URL-safe string (see RFC 4648 section 5). | ||
| 98 | |||
| 99 | my $xcbc_b64url = xcbc_b64u($cipher_name, $key, 'data buffer'); | ||
| 100 | #or | ||
| 101 | my $xcbc_b64url = xcbc_b64u($cipher_name, $key, 'any data', 'more data', 'even more data'); | ||
| 102 | |||
| 103 | =head1 METHODS | ||
| 104 | |||
| 105 | Unless noted otherwise, assume C<$d> is an existing MAC object created via | ||
| 106 | C<new>, for example: | ||
| 107 | |||
| 108 | my $d = Crypt::Mac::XCBC->new($cipher_name, $key); | ||
| 109 | |||
| 110 | =head2 new | ||
| 111 | |||
| 112 | my $d = Crypt::Mac::XCBC->new($cipher_name, $key); | ||
| 113 | |||
| 114 | # $cipher_name .. [string] one of 'AES', 'Camellia', 'Twofish', 'Serpent', etc. | ||
| 115 | # any <NAME> for which there is a Crypt::Cipher::<NAME> module | ||
| 116 | # $key .......... [binary string] key of valid length for the chosen cipher (e.g. 16/24/32 bytes for AES) | ||
| 117 | |||
| 118 | =head2 clone | ||
| 119 | |||
| 120 | $d->clone(); | ||
| 121 | |||
| 122 | =head2 add | ||
| 123 | |||
| 124 | Appends data to the message. Returns the object itself (for chaining). | ||
| 125 | Croaks if the object has already been finalized by C<mac>, C<hexmac>, | ||
| 126 | C<b64mac>, or C<b64umac>. | ||
| 127 | |||
| 128 | Each argument is converted to bytes using Perl's usual scalar stringification. | ||
| 129 | Defined scalars, including numbers and string-overloaded objects, are | ||
| 130 | accepted. C<undef> is treated as an empty string and may emit Perl's usual | ||
| 131 | "uninitialized value" warning. | ||
| 132 | |||
| 133 | $d->add('any data'); | ||
| 134 | #or | ||
| 135 | $d->add('any data', 'more data', 'even more data'); | ||
| 136 | |||
| 137 | =head2 addfile | ||
| 138 | |||
| 139 | Reads the file content and appends it to the message. Returns the object itself | ||
| 140 | (for chaining). Croaks if the object has already been finalized by C<mac>, | ||
| 141 | C<hexmac>, C<b64mac>, or C<b64umac>. | ||
| 142 | |||
| 143 | $d->addfile('filename.dat'); | ||
| 144 | #or | ||
| 145 | my $filehandle = ...; # existing binary-mode filehandle | ||
| 146 | $d->addfile($filehandle); | ||
| 147 | |||
| 148 | =head2 mac | ||
| 149 | |||
| 150 | Returns the binary MAC (raw bytes) and finalizes the object. After the first | ||
| 151 | call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>, later calls to C<add>, | ||
| 152 | C<addfile>, or any MAC getter croak. | ||
| 153 | |||
| 154 | my $result_raw = $d->mac(); | ||
| 155 | |||
| 156 | =head2 hexmac | ||
| 157 | |||
| 158 | Returns the MAC encoded as a lowercase hexadecimal string and finalizes the | ||
| 159 | object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>, | ||
| 160 | later calls to C<add>, C<addfile>, or any MAC getter croak. | ||
| 161 | |||
| 162 | my $result_hex = $d->hexmac(); | ||
| 163 | |||
| 164 | =head2 b64mac | ||
| 165 | |||
| 166 | Returns the MAC encoded as a Base64 string with trailing C<=> padding and | ||
| 167 | finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or | ||
| 168 | C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak. | ||
| 169 | |||
| 170 | my $result_b64 = $d->b64mac(); | ||
| 171 | |||
| 172 | =head2 b64umac | ||
| 173 | |||
| 174 | Returns the MAC encoded as a Base64 URL-safe string (no trailing C<=>) and | ||
| 175 | finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or | ||
| 176 | C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak. | ||
| 177 | |||
| 178 | my $result_b64url = $d->b64umac(); | ||
| 179 | |||
| 180 | =head1 SEE ALSO | ||
| 181 | |||
| 182 | =over | ||
| 183 | |||
| 184 | =item * L<CryptX> | ||
| 185 | |||
| 186 | =item * L<https://www.rfc-editor.org/rfc/rfc3566> | ||
| 187 | |||
| 188 | =back | ||
| 189 | |||
| 190 | =cut | ||