File Coverage

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