File Coverage

blib/lib/Crypt/AuthEnc/OCB.pm
Criterion Covered Total %
statement 12 15 80.0
branch n/a
condition n/a
subroutine 4 7 57.1
pod 0 2 0.0
total 16 24 66.6


line stmt bran cond sub pod time code
1             package Crypt::AuthEnc::OCB;
2              
3 3     3   141625 use strict;
  3         20  
  3         84  
4 3     3   14 use warnings;
  3         6  
  3         374  
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( ocb_encrypt_authenticate ocb_decrypt_verify )] );
9             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10             our @EXPORT = qw();
11              
12 3     3   21 use Carp;
  3         4  
  3         253  
13             $Carp::Internal{(__PACKAGE__)}++;
14 3     3   873 use CryptX;
  3         8  
  3         348  
15              
16             # obsolete, only for backwards compatibility
17 0     0 0   sub aad_add { goto &adata_add }
18 0     0 0   sub blocksize { return 16 }
19              
20 0     0     sub CLONE_SKIP { 1 } # prevent cloning
21              
22             1;
23              
24             =pod
25              
26             =head1 NAME
27              
28             Crypt::AuthEnc::OCB - Authenticated encryption in OCBv3 mode
29              
30             =head1 SYNOPSIS
31              
32             ### OO interface
33             use Crypt::AuthEnc::OCB;
34              
35             # encrypt and authenticate
36             my $ae = Crypt::AuthEnc::OCB->new("AES", $key, $nonce, $tag_len);
37             $ae->adata_add('additional_authenticated_data1');
38             $ae->adata_add('additional_authenticated_data2');
39             my $ct = $ae->encrypt_add('data1');
40             $ct .= $ae->encrypt_add('data2');
41             $ct .= $ae->encrypt_add('data3');
42             $ct .= $ae->encrypt_last('rest of data');
43             my $tag = $ae->encrypt_done();
44              
45             # decrypt and verify
46             my $ae = Crypt::AuthEnc::OCB->new("AES", $key, $nonce, $tag_len);
47             $ae->adata_add('additional_authenticated_data1');
48             $ae->adata_add('additional_authenticated_data2');
49             my $pt = $ae->decrypt_add('ciphertext1');
50             $pt .= $ae->decrypt_add('ciphertext2');
51             $pt .= $ae->decrypt_add('ciphertext3');
52             $pt .= $ae->decrypt_last('rest of data');
53             my $tag = $ae->decrypt_done();
54             die "decrypt failed" unless $tag eq $expected_tag;
55              
56             #or
57             my $result = $ae->decrypt_done($expected_tag); # 0 or 1
58              
59             ### functional interface
60             use Crypt::AuthEnc::OCB qw(ocb_encrypt_authenticate ocb_decrypt_verify);
61              
62             my ($ciphertext, $tag) = ocb_encrypt_authenticate('AES', $key, $nonce, $adata, $tag_len, $plaintext);
63             my $plaintext = ocb_decrypt_verify('AES', $key, $nonce, $adata, $ciphertext, $tag);
64              
65             =head1 DESCRIPTION
66              
67             This module implements OCB v3 according to L
68              
69             =head1 EXPORT
70              
71             Nothing is exported by default.
72              
73             You can export selected functions:
74              
75             use Crypt::AuthEnc::OCB qw(ocb_encrypt_authenticate ocb_decrypt_verify);
76              
77             =head1 FUNCTIONS
78              
79             =head2 ocb_encrypt_authenticate
80              
81             my ($ciphertext, $tag) = ocb_encrypt_authenticate($cipher, $key, $nonce, $adata, $tag_len, $plaintext);
82              
83             # $cipher .. 'AES' or name of any other cipher with 16-byte block len
84             # $key ..... AES key of proper length (128/192/256bits)
85             # $nonce ... unique nonce/salt (no need to keep it secret)
86             # $adata ... additional authenticated data
87             # $tag_len . required length of output tag
88              
89             =head2 ocb_decrypt_verify
90              
91             my $plaintext = ocb_decrypt_verify($cipher, $key, $nonce, $adata, $ciphertext, $tag);
92             # on error returns undef
93              
94             =head1 METHODS
95              
96             =head2 new
97              
98             my $ae = Crypt::AuthEnc::OCB->new($cipher, $key, $nonce, $tag_len);
99              
100             # $cipher .. 'AES' or name of any other cipher with 16-byte block len
101             # $key ..... AES key of proper length (128/192/256bits)
102             # $nonce ... unique nonce/salt (no need to keep it secret)
103             # $tag_len . required length of output tag
104              
105             =head2 adata_add
106              
107             $ae->adata_add($adata); #can be called multiple times
108              
109             =head2 encrypt_add
110              
111             $ciphertext = $ae->encrypt_add($data); # can be called multiple times
112              
113             #BEWARE: size of $data has to be multiple of blocklen (16 for AES)
114              
115             =head2 encrypt_last
116              
117             $ciphertext = $ae->encrypt_last($data);
118              
119             =head2 encrypt_done
120              
121             $tag = $ae->encrypt_done(); # returns $tag value
122              
123             =head2 decrypt_add
124              
125             $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
126              
127             #BEWARE: size of $ciphertext has to be multiple of blocklen (16 for AES)
128              
129             =head2 decrypt_last
130              
131             $plaintext = $ae->decrypt_last($data);
132              
133             =head2 decrypt_done
134              
135             my $tag = $ae->decrypt_done; # returns $tag value
136             #or
137             my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
138              
139             =head2 clone
140              
141             my $ae_new = $ae->clone;
142              
143             =head1 SEE ALSO
144              
145             =over
146              
147             =item * L, L, L, L
148              
149             =item * L
150              
151             =item * L
152              
153             =back
154              
155             =cut