blib/lib/Crypt/Mac/HMAC.pm

filter: Statementstmt 100% 15 / 15 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 100% 18 / 18 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« blib/lib/Crypt/Mac/F9.pm ↑ Summary blib/lib/Crypt/Mac/KMAC.pm »
1 package Crypt::Mac::HMAC;
2  
3 ### BEWARE - GENERATED FILE, DO NOT EDIT MANUALLY!
4  
5 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 5 our $VERSION = '0.091';
8  
9 5 ▶use base qw(Crypt::Mac Exporter);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 5 our %EXPORT_TAGS = ( all => [qw( hmac hmac_hex hmac_b64 hmac_b64u )] );
11 5 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
12 5 our @EXPORT = qw();
13  
14 5 1;
15  
16 =pod
17  
18 =head1 NAME
19  
20 Crypt::Mac::HMAC - Message authentication code HMAC
21  
22 =head1 SYNOPSIS
23  
24 ### Functional interface:
25 use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u );
26  
27 # calculate MAC from string/buffer
28 my $hmac_raw = hmac('SHA256', $key, 'data buffer');
29 my $hmac_hex = hmac_hex('SHA256', $key, 'data buffer');
30 my $hmac_b64 = hmac_b64('SHA256', $key, 'data buffer');
31 my $hmac_b64u = hmac_b64u('SHA256', $key, 'data buffer');
32  
33 ### OO interface:
34 use Crypt::Mac::HMAC;
35  
36 my $d = Crypt::Mac::HMAC->new('SHA256', $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::HMAC->new('SHA256', $key)->add('any data')->b64umac;
42  
43 # or MAC a file instead
44 my $file_result_raw = Crypt::Mac::HMAC->new('SHA256', $key)->addfile('filename.dat')->mac;
45  
46 =head1 DESCRIPTION
47  
48 Provides an interface to the HMAC 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::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u );
57  
58 Or all of them at once:
59  
60 use Crypt::Mac::HMAC ':all';
61  
62 =head1 FUNCTIONS
63  
64 =head2 hmac
65  
66 Joins all arguments into a single string and returns its HMAC 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<hmac_hex>, C<hmac_b64>, and
73 C<hmac_b64u>.
74  
75 my $hmac_raw = hmac($hash_name, $key, 'data buffer');
76 #or
77 my $hmac_raw = hmac($hash_name, $key, 'any data', 'more data', 'even more data');
78  
79 # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
80 # $key ......... [binary string] the key (octets/bytes)
81  
82 =head2 hmac_hex
83  
84 Joins all arguments into a single string and returns its HMAC message authentication code encoded as a hexadecimal string.
85  
86 my $hmac_hex = hmac_hex($hash_name, $key, 'data buffer');
87 #or
88 my $hmac_hex = hmac_hex($hash_name, $key, 'any data', 'more data', 'even more data');
89  
90 # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
91 # $key ......... [binary string] the key (not hex!)
92  
93 =head2 hmac_b64
94  
95 Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 string.
96  
97 my $hmac_b64 = hmac_b64($hash_name, $key, 'data buffer');
98 #or
99 my $hmac_b64 = hmac_b64($hash_name, $key, 'any data', 'more data', 'even more data');
100  
101 # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
102 # $key ......... [binary string] the key (not Base64!)
103  
104 =head2 hmac_b64u
105  
106 Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 URL-safe string (see RFC 4648 section 5).
107  
108 my $hmac_b64url = hmac_b64u($hash_name, $key, 'data buffer');
109 #or
110 my $hmac_b64url = hmac_b64u($hash_name, $key, 'any data', 'more data', 'even more data');
111  
112 # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
113 # $key ......... [binary string] the key (not Base64url!)
114  
115 =head1 METHODS
116  
117 Unless noted otherwise, assume C<$d> is an existing MAC object created via
118 C<new>, for example:
119  
120 my $d = Crypt::Mac::HMAC->new('SHA256', $key);
121  
122 =head2 new
123  
124 my $d = Crypt::Mac::HMAC->new($hash_name, $key);
125  
126 # $hash_name ... [string] one of 'SHA256', 'SHA384', 'SHA512', 'SHA1', 'SHA3_256', 'BLAKE2b_256',
127 # 'RIPEMD160', etc. - any <NAME> for which there is a Crypt::Digest::<NAME> module
128 # $key ......... [binary string] the key (any length - internally padded/hashed as per RFC 2104)
129  
130 =head2 clone
131  
132 $d->clone();
133  
134 =head2 add
135  
136 Appends data to the message. Returns the object itself (for chaining).
137 Croaks if the object has already been finalized by C<mac>, C<hexmac>,
138 C<b64mac>, or C<b64umac>.
139  
140 Each argument is converted to bytes using Perl's usual scalar stringification.
141 Defined scalars, including numbers and string-overloaded objects, are
142 accepted. C<undef> is treated as an empty string and may emit Perl's usual
143 "uninitialized value" warning.
144  
145 $d->add('any data');
146 #or
147 $d->add('any data', 'more data', 'even more data');
148  
149 =head2 addfile
150  
151 Reads the file content and appends it to the message. Returns the object itself
152 (for chaining). Croaks if the object has already been finalized by C<mac>,
153 C<hexmac>, C<b64mac>, or C<b64umac>.
154  
155 $d->addfile('filename.dat');
156 #or
157 my $filehandle = ...; # existing binary-mode filehandle
158 $d->addfile($filehandle);
159  
160 =head2 mac
161  
162 Returns the binary MAC (raw bytes) and finalizes the object. After the first
163 call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>, later calls to C<add>,
164 C<addfile>, or any MAC getter croak.
165  
166 my $result_raw = $d->mac();
167  
168 =head2 hexmac
169  
170 Returns the MAC encoded as a lowercase hexadecimal string and finalizes the
171 object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>,
172 later calls to C<add>, C<addfile>, or any MAC getter croak.
173  
174 my $result_hex = $d->hexmac();
175  
176 =head2 b64mac
177  
178 Returns the MAC encoded as a Base64 string with trailing C<=> padding and
179 finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or
180 C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak.
181  
182 my $result_b64 = $d->b64mac();
183  
184 =head2 b64umac
185  
186 Returns the MAC encoded as a Base64 URL-safe string (no trailing C<=>) and
187 finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or
188 C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak.
189  
190 my $result_b64url = $d->b64umac();
191  
192 =head1 SEE ALSO
193  
194 =over
195  
196 =item * L<CryptX>
197  
198 =item * L<https://en.wikipedia.org/wiki/Hmac>
199  
200 =item * L<https://www.rfc-editor.org/rfc/rfc2104>
201  
202 =back
203  
204 =cut
« blib/lib/Crypt/Mac/F9.pm ↑ Summary blib/lib/Crypt/Mac/KMAC.pm »