blib/lib/Crypt/Digest/KangarooTwelve.pm

filter: Statementstmt 44.1% 15 / 34 Branchbran 0.0% 0 / 12 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 66.6% 4 / 6 Podpod 100% 1 / 1 totaltotal 31.7% 20 / 63 CC 9 SCAR 40.7
CC
9
Cov
29%
addfile
90.0
CLONE_SKIP
2.0
BEGIN
1.0
CRAP 58.3
« blib/lib/Crypt/PK/ECC.pm ↑ Summary blib/lib/Crypt/Digest/TurboSHAKE.pm »
1 package Crypt::Digest::KangarooTwelve;
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 our $VERSION = '0.091';
6  
7 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 $Carp::Internal{(__PACKAGE__)}++;
9 2 ▶use CryptX;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 0 ▶sub addfile {
Subroutine addfile: not called CC=9 SCAR=45.0
Pod documented
12 0 my ($self, $file) = @_;
13  
14 0 my ($handle, $close_handle);
15 0 ▶ if (ref($file) && eval { defined fileno($file) }) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $file and eval { do { defined fileno $file } }) { } 0 0 0
elsif (defined $file and not ref $file) { } 0 0 0
Condition0%0/3
ref $file and eval { do { defined fileno $file } }
!ll&&!rl&&r
000
MC/DC0%0/2
ref $file and eval { do { defined fileno $file } }
ref $file eval { do { defined fileno $file } }
Truth table0%0/3
A and B
A= ref $fileB= eval { do { defined fileno $file } }
ABresult
0X0
100
111
16 0 $handle = $file;
17 }
18 ▶ elsif (defined($file) && !ref($file)) {
Condition0%0/3
defined $file and not ref $file
!ll&&!rl&&r
000
MC/DC0%0/2
defined $file and not ref $file
defined $file not ref $file
Truth table0%0/3
A and not(B)
A= defined $fileB= not ref $file
ABresult
0X0
100
111
19 0 ▶ open($handle, "<", $file) || croak "FATAL: cannot open '$file': $!";
Branch: 1 branch
BranchTrueFalseTotal
open $handle, "<", $file or croak("FATAL: cannot open '${file}': $!") 0 0 0
20 0 binmode($handle);
21 0 $close_handle = 1;
22 }
23 else {
24 0 croak "FATAL: invalid handle";
25 }
26  
27 0 my $n;
28 0 my $buf = "";
29 {
30 0 local $SIG{__DIE__} = \&CryptX::_croak;
31 0 ▶ while (($n = read($handle, $buf, 32*1024))) {
Branch: 1 branch
BranchTrueFalseTotal
if ($n = read($handle, $buf, 32768)) 0 0 0
32 0 $self->add($buf)
33 }
34 0 ▶ croak "FATAL: read failed: $!" unless defined $n;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $n 0 0 0
35 }
36 0 ▶ close($handle) if $close_handle;
Branch: 1 branch
BranchTrueFalseTotal
if $close_handle 0 0 0
37  
38 0 return $self;
39 }
40  
41 0 ▶sub CLONE_SKIP { 1 } # prevent cloning
Subroutine CLONE_SKIP: not called CC=1 SCAR=6.9
42  
43 2 1;
44  
45 =pod
46  
47 =head1 NAME
48  
49 Crypt::Digest::KangarooTwelve - XOF (extendable output) hash function KangarooTwelve
50  
51 =head1 SYNOPSIS
52  
53 use Crypt::Digest::KangarooTwelve;
54  
55 my $d = Crypt::Digest::KangarooTwelve->new(128); # 128-bit security
56 $d->add('any data');
57 $d->customization('optional context string');
58 my $result = $d->done(32); # 32 bytes of output
59  
60 # or absorb input from a file instead
61 my $file_d = Crypt::Digest::KangarooTwelve->new(128);
62 $file_d->addfile('filename.dat');
63 $file_d->customization('optional context string');
64 my $file_result = $file_d->done(32);
65  
66 =head1 DESCRIPTION
67  
68 I<Since: CryptX-0.089>
69  
70 Provides an interface to KangarooTwelve (K12) as defined in
71 L<RFC 9861|https://www.rfc-editor.org/rfc/rfc9861>.
72  
73 KangarooTwelve is a fast cryptographic hash and XOF based on a reduced-round
74 (12-round) Keccak-p permutation. It supports an optional B<customization string>
75 that binds the output to a specific context. C<done()> can be called multiple
76 times to stream arbitrary amounts of output.
77  
78 B<Order of operations>: C<add()> must be called before C<customization()>;
79 C<customization()> must be called before C<done()>.
80 After the first C<done()>, treat the object as being in output mode:
81 do not call C<add()> or C<customization()> again on that state. Use C<reset()>
82 or a new object to start hashing a new message.
83  
84 =head1 METHODS
85  
86 Unless noted otherwise, assume C<$d> is an existing KangarooTwelve object
87 created via C<new>, for example:
88  
89 my $d = Crypt::Digest::KangarooTwelve->new(128);
90  
91 =head2 new
92  
93 my $d = Crypt::Digest::KangarooTwelve->new($num);
94 # $num ... [integer] 128 or 256 (security level in bits)
95  
96 =head2 clone
97  
98 my $d2 = $d->clone;
99  
100 =head2 reset
101  
102 $d->reset;
103  
104 =head2 add
105  
106 Appends data to the message. Returns the object itself (for chaining).
107  
108 Each argument is converted to bytes using Perl's usual scalar stringification.
109 Defined scalars, including numbers and string-overloaded objects, are
110 accepted. C<undef> is treated as an empty string and may emit Perl's usual
111 "uninitialized value" warning.
112  
113 $d->add('any data');
114 #or
115 $d->add('chunk1', 'chunk2', ...);
116  
117 =head2 addfile
118  
119 Reads the file content and appends it to the message. Returns the object itself (for chaining).
120  
121 $d->addfile('filename.dat');
122 #or
123 my $filehandle = ...; # existing binary-mode filehandle
124 $d->addfile($filehandle);
125  
126 =head2 customization
127  
128 $d->customization('context string'); # optional; call after add(), before done()
129  
130 Each argument is converted to bytes using Perl's usual scalar stringification.
131 Defined scalars, including numbers and string-overloaded objects, are
132 accepted. C<undef> is treated as an empty string and may emit Perl's usual
133 "uninitialized value" warning.
134  
135 =head2 done
136  
137 Returns C<$len> bytes of output as a binary string. Can be called repeatedly
138 to stream an unlimited amount of output from the same absorbed input. The
139 C<$len> argument is required and must be a positive integer. Single
140 C<done()> calls are limited to 1,000,000,000 bytes, but the recommended way
141 to read large output is to call C<done()> repeatedly in 10 MB chunks.
142  
143 After the first C<done()> call the object is in output mode. Calling
144 C<add()> or C<customization()> in this state croaks; use
145 C<reset()> or create a new object to hash a different message.
146  
147 my $result_raw = $d->done($len);
148 # can be called multiple times; $len is the number of output bytes to read
149 # after the first done(), add() / customization() croak until you call reset()
150  
151 =head1 SEE ALSO
152  
153 =over
154  
155 =item * L<CryptX>, L<Crypt::Digest::SHAKE>, L<Crypt::Digest::TurboSHAKE>
156  
157 =item * L<RFC 9861|https://www.rfc-editor.org/rfc/rfc9861>
158  
159 =back
160  
161 =cut
« blib/lib/Crypt/PK/ECC.pm ↑ Summary blib/lib/Crypt/Digest/TurboSHAKE.pm »