File Coverage

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