File Coverage

blib/lib/Crypt/Cipher.pm
Criterion Covered Total %
statement 13 14 92.8
branch n/a
condition n/a
subroutine 5 6 83.3
pod 1 1 100.0
total 19 21 90.4


line stmt bran cond sub pod time code
1             package Crypt::Cipher;
2              
3 56     56   1808800 use strict;
  56         338  
  56         1650  
4 56     56   284 use warnings;
  56         112  
  56         2351  
5             our $VERSION = '0.079_007';
6              
7 56     56   319 use Carp;
  56         141  
  56         4022  
8             $Carp::Internal{(__PACKAGE__)}++;
9 56     56   16203 use CryptX;
  56         149  
  56         5696  
10              
11             ### the following methods/functions are implemented in XS:
12             # - new
13             # - DESTROY
14             # - blocksize
15             # - decrypt
16             # - default_rounds
17             # - encrypt
18             # - max_keysize
19             # - min_keysize
20              
21 161     161 1 20862 sub keysize { goto \&max_keysize; } # for Crypt::CBC compatibility
22              
23 0     0     sub CLONE_SKIP { 1 } # prevent cloning
24              
25             1;
26              
27             =pod
28              
29             =head1 NAME
30              
31             Crypt::Cipher - Generic interface to cipher functions
32              
33             =head1 SYNOPSIS
34              
35             #### example 1 (encrypting single block)
36             use Crypt::Cipher;
37              
38             my $key = '...'; # length has to be valid key size for this cipher
39             my $c = Crypt::Cipher->new('AES', $key);
40             my $blocksize = $c->blocksize;
41             my $ciphertext = $c->encrypt('plain text block'); #encrypt 1 block
42             my $plaintext = $c->decrypt($ciphertext); #decrypt 1 block
43              
44             ### example 2 (using CBC mode)
45             use Crypt::Mode::CBC;
46              
47             my $key = '...'; # length has to be valid key size for this cipher
48             my $iv = '...'; # 16 bytes
49             my $cbc = Crypt::Mode::CBC->new('AES');
50             my $ciphertext = $cbc->encrypt("secret data", $key, $iv);
51              
52             #### example 3 (compatibility with Crypt::CBC)
53             use Crypt::CBC;
54             use Crypt::Cipher;
55              
56             my $key = '...'; # length has to be valid key size for this cipher
57             my $iv = '...'; # 16 bytes
58             my $cipher = Crypt::Cipher('AES', $key);
59             my $cbc = Crypt::CBC->new( -cipher=>$cipher, -iv=>$iv );
60             my $ciphertext = $cbc->encrypt("secret data");
61              
62             =head1 DESCRIPTION
63              
64             Provides an interface to various symmetric cipher algorithms.
65              
66             B This module implements just elementary "one-block-(en|de)cryption" operation - if you want to
67             encrypt/decrypt generic data you have to use some of the cipher block modes - check for example
68             L, L or L (which will be slower).
69              
70             =head1 METHODS
71              
72             =head2 new
73              
74             Constructor, returns a reference to the cipher object.
75              
76             ## basic scenario
77             $d = Crypt::Cipher->new($name, $key);
78             # $name = one of 'AES', 'Anubis', 'Blowfish', 'CAST5', 'Camellia', 'DES', 'DES_EDE',
79             # 'KASUMI', 'Khazad', 'MULTI2', 'Noekeon', 'RC2', 'RC5', 'RC6',
80             # 'SAFERP', 'SAFER_K128', 'SAFER_K64', 'SAFER_SK128', 'SAFER_SK64',
81             # 'SEED', 'Skipjack', 'Twofish', 'XTEA', 'IDEA', 'Serpent'
82             # simply any for which there exists Crypt::Cipher::
83             # $key = binary key (keysize should comply with selected cipher requirements)
84              
85             ## some of the ciphers (e.g. MULTI2, RC5, SAFER) allow one to set number of rounds
86             $d = Crypt::Cipher->new('MULTI2', $key, $rounds);
87             # $rounds = positive integer (should comply with selected cipher requirements)
88              
89             =head2 encrypt
90              
91             Encrypts $plaintext and returns the $ciphertext where $plaintext and $ciphertext should be of B bytes.
92              
93             $ciphertext = $d->encrypt($plaintext);
94              
95             =head2 decrypt
96              
97             Decrypts $ciphertext and returns the $plaintext where $plaintext and $ciphertext should be of B bytes.
98              
99             $plaintext = $d->decrypt($ciphertext);
100              
101             =head2 keysize
102              
103             Just an alias for B (needed for L compatibility).
104              
105             =head2 max_keysize
106              
107             Returns the maximal allowed key size (in bytes) for given cipher.
108              
109             $d->max_keysize;
110             #or
111             Crypt::Cipher->max_keysize('AES');
112             #or
113             Crypt::Cipher::max_keysize('AES');
114              
115             =head2 min_keysize
116              
117             Returns the minimal allowed key size (in bytes) for given cipher.
118              
119             $d->min_keysize;
120             #or
121             Crypt::Cipher->min_keysize('AES');
122             #or
123             Crypt::Cipher::min_keysize('AES');
124              
125             =head2 blocksize
126              
127             Returns block size (in bytes) for given cipher.
128              
129             $d->blocksize;
130             #or
131             Crypt::Cipher->blocksize('AES');
132             #or
133             Crypt::Cipher::blocksize('AES');
134              
135             =head2 default_rounds
136              
137             Returns default number of rounds for given cipher. NOTE: only some ciphers (e.g. MULTI2, RC5, SAFER) allow one to set number of rounds via new().
138              
139             $d->default_rounds;
140             #or
141             Crypt::Cipher->default_rounds('AES');
142             #or
143             Crypt::Cipher::default_rounds('AES');
144              
145             =head1 SEE ALSO
146              
147             =over
148              
149             =item * L
150              
151             =item * Check subclasses like L, L, ...
152              
153             =back
154              
155             =cut