File Coverage

blib/lib/Crypt/AuthEnc/CCM.pm
Criterion Covered Total %
statement 12 13 92.3
branch n/a
condition n/a
subroutine 4 5 80.0
pod n/a
total 16 18 88.8


line stmt bran cond sub pod time code
1             package Crypt::AuthEnc::CCM;
2              
3 3     3   203715 use strict;
  3         19  
  3         95  
4 3     3   28 use warnings;
  3         12  
  3         420  
5             our $VERSION = '0.080_001';
6              
7             require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8             our %EXPORT_TAGS = ( all => [qw( ccm_encrypt_authenticate ccm_decrypt_verify )] );
9             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10             our @EXPORT = qw();
11              
12 3     3   21 use Carp;
  3         5  
  3         244  
13             $Carp::Internal{(__PACKAGE__)}++;
14 3     3   1484 use CryptX;
  3         8  
  3         337  
15              
16 0     0     sub CLONE_SKIP { 1 } # prevent cloning
17              
18             1;
19              
20             =pod
21              
22             =head1 NAME
23              
24             Crypt::AuthEnc::CCM - Authenticated encryption in CCM mode
25              
26             =head1 SYNOPSIS
27              
28             ### OO interface
29             use Crypt::AuthEnc::CCM;
30              
31             # encrypt and authenticate
32             my $ae = Crypt::AuthEnc::CCM->new("AES", $key, $iv, $adata, $tag_len, $pt_len);
33             my $ct = $ae->encrypt_add('data1');
34             $ct .= $ae->encrypt_add('data2');
35             $ct .= $ae->encrypt_add('data3');
36             my $tag = $ae->encrypt_done();
37              
38             # decrypt and verify
39             my $ae = Crypt::AuthEnc::CCM->new("AES", $key, $iv, $adata, $tag_len, $pt_len);
40             my $pt = $ae->decrypt_add('ciphertext1');
41             $pt .= $ae->decrypt_add('ciphertext2');
42             $pt .= $ae->decrypt_add('ciphertext3');
43             my $tag = $ae->decrypt_done();
44             die "decrypt failed" unless $tag eq $expected_tag;
45              
46             #or
47             my $result = $ae->decrypt_done($expected_tag); # 0 or 1
48              
49             ### functional interface
50             use Crypt::AuthEnc::CCM qw(ccm_encrypt_authenticate ccm_decrypt_verify);
51              
52             ($ciphertext, $tag) = ccm_encrypt_authenticate('AES', $key, $nonce, $adata, $tag_len, $plaintext);
53             $plaintext = ccm_decrypt_verify('AES', $key, $nonce, $adata, $ciphertext, $tag);
54              
55             =head1 DESCRIPTION
56              
57             CCM is a encrypt+authenticate mode that is centered around using AES (or any 16-byte cipher) as a primitive.
58             Unlike EAX and OCB mode, it is only meant for packet mode where the length of the input is known in advance.
59              
60             =head1 EXPORT
61              
62             Nothing is exported by default.
63              
64             You can export selected functions:
65              
66             use Crypt::AuthEnc::CCM qw(ccm_encrypt_authenticate ccm_decrypt_verify);
67              
68             =head1 FUNCTIONS
69              
70             =head2 ccm_encrypt_authenticate
71              
72             my ($ciphertext, $tag) = ccm_encrypt_authenticate($cipher, $key, $nonce, $adata, $tag_len, $plaintext);
73              
74             # $cipher .. 'AES' or name of any other cipher with 16-byte block len
75             # $key ..... key of proper length (e.g. 128/192/256bits for AES)
76             # $nonce ... unique nonce/salt (no need to keep it secret)
77             # $adata ... additional authenticated data
78             # $tag_len . required length of output tag
79              
80             CCM parameters should follow L
81              
82             # tag length: 4, 6, 8, 10, 12, 14, 16 (reasonable minimum is 8)
83             # nonce length: 7, 8, 9, 10, 11, 12, 13 (if you are not sure, use 11)
84             # BEWARE nonce length determines max. enc/dec data size: max_data_size = 2^(8*(15-nonce_len))
85              
86             =head2 ccm_decrypt_verify
87              
88             my $plaintext = ccm_decrypt_verify($cipher, $key, $nonce, $adata, $ciphertext, $tag);
89             # on error returns undef
90              
91             =head1 METHODS
92              
93             =head2 new
94              
95             my $ae = Crypt::AuthEnc::CCM->new($cipher, $key, $nonce, $adata, $tag_len, $pt_len);
96              
97             # $cipher .. 'AES' or name of any other cipher with 16-byte block len
98             # $key ..... key of proper length (e.g. 128/192/256bits for AES)
99             # $nonce ... unique nonce/salt (no need to keep it secret)
100             # $adata ... additional authenticated data
101             # $tag_len . required length of output tag
102             # $pt_len .. expected length of plaintext/ciphertext to encrypt/decrypt
103              
104             =head2 encrypt_add
105              
106             $ciphertext = $ae->encrypt_add($data); # can be called multiple times
107              
108             =head2 encrypt_done
109              
110             my $tag = $ae->encrypt_done; # returns $tag value
111              
112             =head2 decrypt_add
113              
114             $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
115              
116             =head2 decrypt_done
117              
118             my $tag = $ae->decrypt_done; # returns $tag value
119             #or
120             my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
121              
122             =head2 clone
123              
124             my $ae_new = $ae->clone;
125              
126             =head1 SEE ALSO
127              
128             =over
129              
130             =item * L, L, L, L
131              
132             =item * L
133              
134             =back
135              
136             =cut