File Coverage

blib/lib/Crypt/Stream/XChaCha.pm
Criterion Covered Total %
statement 10 10 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 14 14 100.0


line stmt bran cond sub pod time code
1             package Crypt::Stream::XChaCha;
2              
3 2     2   1220 use strict;
  2         3  
  2         76  
4 2     2   9 use warnings;
  2         3  
  2         122  
5             our $VERSION = '0.089';
6              
7 2     2   9 use CryptX;
  2         19  
  2         159  
8              
9 1     1   162809 sub CLONE_SKIP { 1 } # prevent cloning
10              
11             1;
12              
13             =pod
14              
15             =head1 NAME
16              
17             Crypt::Stream::XChaCha - Stream cipher XChaCha20
18              
19             =head1 SYNOPSIS
20              
21             use Crypt::Stream::XChaCha;
22              
23             # encrypt
24             my $key = "12345678901234567890123456789012"; # 32 bytes
25             my $nonce = "123456789012345678901234"; # 24 bytes
26             my $enc_stream = Crypt::Stream::XChaCha->new($key, $nonce);
27             my $ct = $enc_stream->crypt("plain message");
28              
29             # decrypt
30             my $dec_stream = Crypt::Stream::XChaCha->new($key, $nonce);
31             my $pt = $dec_stream->crypt($ct);
32              
33             =head1 DESCRIPTION
34              
35             I
36              
37             Provides an interface to the XChaCha20 stream cipher, an extended-nonce
38             variant of ChaCha20 using a 192-bit (24-byte) nonce.
39              
40             =head1 METHODS
41              
42             Unless noted otherwise, assume C<$stream> is an existing stream object created
43             via C, for example:
44              
45             my $stream = Crypt::Stream::XChaCha->new($key, $nonce);
46              
47             =head2 new
48              
49             my $stream = Crypt::Stream::XChaCha->new($key, $nonce);
50             #or
51             my $stream = Crypt::Stream::XChaCha->new($key, $nonce, $rounds);
52              
53             # $key .. [binary string] 32 bytes
54             # $nonce .. [binary string] 24 bytes
55             # $rounds .. [integer] optional, rounds (DEFAULT: 20)
56              
57             =head2 crypt
58              
59             Encrypts or decrypts data. The output has the same length as the input.
60             Returns a binary string (raw bytes).
61              
62             The input is converted using Perl's usual scalar stringification. Passing
63             C is treated as an empty string with the usual warning, and numeric
64             scalars are stringified before processing.
65              
66             my $ciphertext = $stream->crypt($plaintext);
67             #or
68             my $plaintext = $stream->crypt($ciphertext);
69              
70             =head2 keystream
71              
72             Returns C<$length> bytes of raw keystream as a binary string.
73              
74             The length is taken using Perl's usual numeric coercion. Values that coerce to
75             an oversized unsigned length are rejected as too large.
76              
77             my $random_bytes = $stream->keystream($length);
78              
79             =head2 clone
80              
81             Returns a copy of the stream cipher object in its current state.
82              
83             my $stream2 = $stream->clone;
84              
85             =head1 SEE ALSO
86              
87             =over
88              
89             =item * L, L
90              
91             =item * L
92              
93             =back
94              
95             =cut