File Coverage

blib/lib/Crypt/Stream/Rabbit.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::Rabbit;
2              
3 4     4   115638 use strict;
  4         7  
  4         128  
4 4     4   19 use warnings;
  4         7  
  4         239  
5             our $VERSION = '0.089';
6              
7 4     4   532 use CryptX;
  4         9  
  4         278  
8              
9 1     1   1409 sub CLONE_SKIP { 1 } # prevent cloning
10              
11             1;
12              
13             =pod
14              
15             =head1 NAME
16              
17             Crypt::Stream::Rabbit - Stream cipher Rabbit
18              
19             =head1 SYNOPSIS
20              
21             use Crypt::Stream::Rabbit;
22              
23             # encrypt
24             my $key = "1234567890123456";
25             my $iv = "12345678";
26             my $enc_stream = Crypt::Stream::Rabbit->new($key, $iv);
27             my $ct = $enc_stream->crypt("plain message");
28              
29             # decrypt
30             my $dec_stream = Crypt::Stream::Rabbit->new($key, $iv);
31             my $pt = $dec_stream->crypt($ct);
32              
33             =head1 DESCRIPTION
34              
35             Provides an interface to the Rabbit 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::Rabbit->new($key, $iv);
43              
44             =head2 new
45              
46             my $stream = Crypt::Stream::Rabbit->new($key, $iv);
47             # $key .. [binary string] key length must be at most 16 bytes
48             # $iv .. [binary string] IV length must be at most 8 bytes
49              
50             my $stream = Crypt::Stream::Rabbit->new($key);
51             # note: new($key) skips IV setup entirely, while new($key, "") performs
52             # IV setup with a zero-length IV. These produce different keystreams.
53              
54             =head2 crypt
55              
56             Encrypts or decrypts data. The output has the same length as the input.
57             Returns a binary string (raw bytes).
58              
59             The input is converted using Perl's usual scalar stringification. Passing
60             C is treated as an empty string with the usual warning, and numeric
61             scalars are stringified before processing.
62              
63             my $ciphertext = $stream->crypt($plaintext);
64             #or
65             my $plaintext = $stream->crypt($ciphertext);
66              
67             =head2 keystream
68              
69             Returns C<$length> bytes of raw keystream as a binary string.
70              
71             The length is taken using Perl's usual numeric coercion. Values that coerce to
72             an oversized unsigned length are rejected as too large.
73              
74             my $random_key = $stream->keystream($length);
75              
76             =head2 clone
77              
78             Returns a copy of the stream cipher object in its current state.
79              
80             my $stream2 = $stream->clone();
81              
82             =head1 SEE ALSO
83              
84             =over
85              
86             =item * L, L, L, L
87              
88             =item * L
89              
90             =item * L
91              
92             =back
93              
94             =cut