File Coverage

blib/lib/Crypt/AuthEnc/GCM.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::GCM;
2              
3 3     3   143320 use strict;
  3         24  
  3         104  
4 3     3   16 use warnings;
  3         6  
  3         360  
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( gcm_encrypt_authenticate gcm_decrypt_verify )] );
9             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10             our @EXPORT = qw();
11              
12 3     3   21 use Carp;
  3         6  
  3         224  
13             $Carp::Internal{(__PACKAGE__)}++;
14 3     3   797 use CryptX;
  3         7  
  3         235  
15              
16 0     0     sub CLONE_SKIP { 1 } # prevent cloning
17              
18             1;
19              
20             =pod
21              
22             =head1 NAME
23              
24             Crypt::AuthEnc::GCM - Authenticated encryption in GCM mode
25              
26             =head1 SYNOPSIS
27              
28             ### OO interface
29             use Crypt::AuthEnc::GCM;
30              
31             # encrypt and authenticate
32             my $ae = Crypt::AuthEnc::GCM->new("AES", $key, $iv);
33             $ae->adata_add('additional_authenticated_data1');
34             $ae->adata_add('additional_authenticated_data2');
35             my $ct = $ae->encrypt_add('data1');
36             $ct .= $ae->encrypt_add('data2');
37             $ct .= $ae->encrypt_add('data3');
38             my $tag = $ae->encrypt_done();
39              
40             # decrypt and verify
41             my $ae = Crypt::AuthEnc::GCM->new("AES", $key, $iv);
42             $ae->adata_add('additional_authenticated_data1');
43             $ae->adata_add('additional_authenticated_data2');
44             my $pt = $ae->decrypt_add('ciphertext1');
45             $pt .= $ae->decrypt_add('ciphertext2');
46             $pt .= $ae->decrypt_add('ciphertext3');
47             my $tag = $ae->decrypt_done();
48             die "decrypt failed" unless $tag eq $expected_tag;
49              
50             #or
51             my $result = $ae->decrypt_done($expected_tag); # 0 or 1
52              
53             ### functional interface
54             use Crypt::AuthEnc::GCM qw(gcm_encrypt_authenticate gcm_decrypt_verify);
55              
56             my ($ciphertext, $tag) = gcm_encrypt_authenticate('AES', $key, $iv, $adata, $plaintext);
57             my $plaintext = gcm_decrypt_verify('AES', $key, $iv, $adata, $ciphertext, $tag);
58              
59             =head1 DESCRIPTION
60              
61             Galois/Counter Mode (GCM) - provides encryption and authentication.
62              
63             =head1 EXPORT
64              
65             Nothing is exported by default.
66              
67             You can export selected functions:
68              
69             use Crypt::AuthEnc::GCM qw(gcm_encrypt_authenticate gcm_decrypt_verify);
70              
71             =head1 FUNCTIONS
72              
73             =head2 gcm_encrypt_authenticate
74              
75             my ($ciphertext, $tag) = gcm_encrypt_authenticate($cipher, $key, $iv, $adata, $plaintext);
76              
77             # $cipher .. 'AES' or name of any other cipher with 16-byte block len
78             # $key ..... AES key of proper length (128/192/256bits)
79             # $iv ...... initialization vector
80             # $adata ... additional authenticated data
81              
82             =head2 gcm_decrypt_verify
83              
84             my $plaintext = gcm_decrypt_verify($cipher, $key, $iv, $adata, $ciphertext, $tag);
85             # on error returns undef
86              
87             =head1 METHODS
88              
89             =head2 new
90              
91             my $ae = Crypt::AuthEnc::GCM->new($cipher, $key);
92             #or
93             my $ae = Crypt::AuthEnc::GCM->new($cipher, $key, $iv);
94              
95             # $cipher .. 'AES' or name of any other cipher
96             # $key ..... encryption key of proper length
97             # $iv ...... initialization vector (optional, you can set it later via iv_add method)
98              
99             =head2 iv_add
100              
101             Set initialization vector (IV).
102              
103             $ae->iv_add($iv_data); #can be called multiple times
104              
105             =head2 adata_add
106              
107             Add B.
108             Can be called B all C calls but before the first C or C.
109              
110             $ae->adata_add($aad_data); # can be called multiple times
111              
112             =head2 encrypt_add
113              
114             $ciphertext = $ae->encrypt_add($data); # can be called multiple times
115              
116             =head2 encrypt_done
117              
118             $tag = $ae->encrypt_done(); # returns $tag value
119              
120             =head2 decrypt_add
121              
122             $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
123              
124             =head2 decrypt_done
125              
126             my $tag = $ae->decrypt_done; # returns $tag value
127             #or
128             my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
129              
130             =head2 reset
131              
132             $ae->reset;
133              
134             =head2 clone
135              
136             my $ae_new = $ae->clone;
137              
138             =head1 SEE ALSO
139              
140             =over
141              
142             =item * L, L, L, L
143              
144             =item * L
145              
146             =back
147              
148             =cut