blib/lib/Crypt/Mac/Pelican.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/PMAC.pm ↑ Summary blib/lib/Crypt/Mac/Poly1305.pm »
1 package Crypt::Mac::Pelican;
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( pelican pelican_hex pelican_b64 pelican_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::Pelican - Message authentication code Pelican (AES based MAC)
21  
22 =head1 SYNOPSIS
23  
24 ### Functional interface:
25 use Crypt::Mac::Pelican qw( pelican pelican_hex pelican_b64 pelican_b64u );
26  
27 # calculate MAC from string/buffer
28 my $pelican_raw = pelican($key, 'data buffer');
29 my $pelican_hex = pelican_hex($key, 'data buffer');
30 my $pelican_b64 = pelican_b64($key, 'data buffer');
31 my $pelican_b64u = pelican_b64u($key, 'data buffer');
32  
33 ### OO interface:
34 use Crypt::Mac::Pelican;
35  
36 my $d = Crypt::Mac::Pelican->new($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::Pelican->new($key)->add('any data')->b64umac;
42  
43 # or MAC a file instead
44 my $file_result_raw = Crypt::Mac::Pelican->new($key)->addfile('filename.dat')->mac;
45  
46 =head1 DESCRIPTION
47  
48 Provides an interface to the Pelican 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::Pelican qw( pelican pelican_hex pelican_b64 pelican_b64u );
57  
58 Or all of them at once:
59  
60 use Crypt::Mac::Pelican ':all';
61  
62 =head1 FUNCTIONS
63  
64 =head2 pelican
65  
66 Joins all arguments into a single string and returns its Pelican 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<pelican_hex>, C<pelican_b64>, and
73 C<pelican_b64u>.
74  
75 my $pelican_raw = pelican($key, 'data buffer');
76 #or
77 my $pelican_raw = pelican($key, 'any data', 'more data', 'even more data');
78  
79 =head2 pelican_hex
80  
81 Joins all arguments into a single string and returns its Pelican message authentication code encoded as a hexadecimal string.
82  
83 my $pelican_hex = pelican_hex($key, 'data buffer');
84 #or
85 my $pelican_hex = pelican_hex($key, 'any data', 'more data', 'even more data');
86  
87 =head2 pelican_b64
88  
89 Joins all arguments into a single string and returns its Pelican message authentication code encoded as a Base64 string.
90  
91 my $pelican_b64 = pelican_b64($key, 'data buffer');
92 #or
93 my $pelican_b64 = pelican_b64($key, 'any data', 'more data', 'even more data');
94  
95 =head2 pelican_b64u
96  
97 Joins all arguments into a single string and returns its Pelican message authentication code encoded as a Base64 URL-safe string (see RFC 4648 section 5).
98  
99 my $pelican_b64url = pelican_b64u($key, 'data buffer');
100 #or
101 my $pelican_b64url = pelican_b64u($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::Pelican->new($key);
109  
110 =head2 new
111  
112 my $d = Crypt::Mac::Pelican->new($key);
113  
114 # $key .. [binary string] exactly 16 bytes (AES-128 key; Pelican is AES-based)
115  
116 =head2 clone
117  
118 $d->clone();
119  
120 =head2 add
121  
122 Appends data to the message. Returns the object itself (for chaining).
123 Croaks if the object has already been finalized by C<mac>, C<hexmac>,
124 C<b64mac>, or C<b64umac>.
125  
126 Each argument is converted to bytes using Perl's usual scalar stringification.
127 Defined scalars, including numbers and string-overloaded objects, are
128 accepted. C<undef> is treated as an empty string and may emit Perl's usual
129 "uninitialized value" warning.
130  
131 $d->add('any data');
132 #or
133 $d->add('any data', 'more data', 'even more data');
134  
135 =head2 addfile
136  
137 Reads the file content and appends it to the message. Returns the object itself
138 (for chaining). Croaks if the object has already been finalized by C<mac>,
139 C<hexmac>, C<b64mac>, or C<b64umac>.
140  
141 $d->addfile('filename.dat');
142 #or
143 my $filehandle = ...; # existing binary-mode filehandle
144 $d->addfile($filehandle);
145  
146 =head2 mac
147  
148 Returns the binary MAC (raw bytes) and finalizes the object. After the first
149 call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>, later calls to C<add>,
150 C<addfile>, or any MAC getter croak.
151  
152 my $result_raw = $d->mac();
153  
154 =head2 hexmac
155  
156 Returns the MAC encoded as a lowercase hexadecimal string and finalizes the
157 object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>,
158 later calls to C<add>, C<addfile>, or any MAC getter croak.
159  
160 my $result_hex = $d->hexmac();
161  
162 =head2 b64mac
163  
164 Returns the MAC encoded as a Base64 string with trailing C<=> padding and
165 finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or
166 C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak.
167  
168 my $result_b64 = $d->b64mac();
169  
170 =head2 b64umac
171  
172 Returns the MAC encoded as a Base64 URL-safe string (no trailing C<=>) and
173 finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or
174 C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak.
175  
176 my $result_b64url = $d->b64umac();
177  
178 =head1 SEE ALSO
179  
180 =over
181  
182 =item * L<CryptX>
183  
184 =item * L<https://eprint.iacr.org/2005/088.pdf>
185  
186 =back
187  
188 =cut
« blib/lib/Crypt/Mac/PMAC.pm ↑ Summary blib/lib/Crypt/Mac/Poly1305.pm »