1Crypt::Salsa20(3)     User Contributed Perl Documentation    Crypt::Salsa20(3)
2
3
4

NAME

6       Crypt::Salsa20 - Encrypt data with the Salsa20 cipher
7

VERSION

9       This document describes version 0.03 of Crypt::Salsa20, released
10       January 25, 2014.
11

SYNOPSIS

13         use Crypt::Salsa20;
14
15         my $salsa20 = Crypt::Salsa20->new(-key => $key, -iv => $nonce);
16
17         # Use cryptor for the best performance:
18         my $cryptor = $salsa20->cryptor;
19         my $ciphertext = $cryptor->('plaintext');
20         # encryption & decryption are the same operation:
21         $salsa20->start;   # reset the block counter (keeping key & iv)
22         my $plaintext  = $cryptor->($ciphertext);
23
24         # Or use Crypt::CBC-like API:
25         my $ciphertext = $salsa20->encrypt('plaintext');
26         my $plaintext  = $salsa20->decrypt($ciphertext);
27

DESCRIPTION

29       Crypt::Salsa20 implements D. J. Bernstein's Salsa20 stream cipher
30       (a.k.a. Snuffle 2005) in Perl.  For more information on Salsa20, see
31       his page at <http://cr.yp.to/snuffle.html>.
32
33       Salsa20 takes a 256 bit (or 128 bit) key and a 64 bit nonce (a.k.a. an
34       IV or message number) and uses them to generate a stream of up to 2**70
35       bytes of pseudo-random data.  That stream is XORed with your message.
36       Because of that, encryption and decryption are the same operation.
37
38       It is critical that you never use the same nonce and key to encrypt two
39       different messages.  Because the keystream is completely determined by
40       the key and nonce, reusing them means that you can cancel out the
41       keystream by XORing the two ciphertexts together:
42
43         ciphertext1          ^ ciphertext2
44         keystream ^ message1 ^ keystream ^ message2
45         message1  ^ message2 ^ keystream ^ keystream
46         message1  ^ message2 ^           0
47         message1  ^ message2
48
49   Crypt::Salsa20 vs. Crypt::CBC
50       The API is similar to that of the Crypt::CBC module, but there are some
51       differences:
52
53       1.  There is no "-literal_key" option.  The key is always interpreted
54           as raw bytes (and must be either 16 or 32 bytes long).  If you want
55           to use a pasword hashing function, you have to supply your own.
56
57       2.  Crypt::Salsa20 doesn't use any sort of header, trailer, padding, or
58           any other metadata.  If you need to transmit the nonce as part of
59           your message, you'll need to do it manually.
60
61       3.  Since encryption and decryption are the same operation with
62           Salsa20, the "start" method does not require a parameter, and it is
63           not necessary to call it at all.
64
65       4.  The "finish" method is available, but unnecessary.  In
66           Crypt::Salsa20 it does nothing and always returns the empty string.
67

ATTRIBUTES

69       Each attribute has a method of the same name.  Calling the method with
70       no parameter returns the current value of the attribute.  Calling it
71       with a parameter sets the attribute to that value (and returns the new
72       value).
73
74   key
75       The encryption key is a 16 or 32 byte string (128 or 256 bits), with 32
76       bytes being the recommended size.  It's always interpreted as raw
77       bytes; if you want to use a pasword hashing function, you have to
78       supply your own.  Setting the key does not change the IV or reset the
79       block counter.
80
81   iv
82       The nonce (IV) is an 8 byte string (64 bits).  The nonce does not need
83       to be kept secret, but you must never encrypt two different messages
84       with the same key and nonce, or you have catastrophically weakened the
85       security of the cipher.  You must supply an IV before encrypting or
86       decrypting, but you can omit it from the constructor and call the "iv"
87       method instead.  Setting the IV does not change the key, but it does
88       reset the block counter.
89
90   rounds
91       The number of cipher rounds to use.  The default is 20, which is the
92       standard Salsa20 cipher.  The standard variants are 8 or 12 rounds
93       (Salsa20/8 or Salsa20/12), but any even integer will work.
94

METHODS

96   new
97         $salsa20 = Crypt::Salsa20->new(-key => $key, ...);
98
99       This constructs a new Crypt::Salsa20 object, with attributes supplied
100       as "key => value" pairs.  For compatibility with Crypt::CBC, attribute
101       names may have a leading hyphen (but unlike Crypt::CBC the hyphen is
102       not required).
103
104       The only required attribute at construction time is the key (but you
105       must supply an IV before encrypting or decrypting).
106
107   start
108         $salsa20->start;
109
110       Resets the internal block counter, starting the keystream over at the
111       beginning.  You should also change the IV, because using the same key
112       and IV is a security breach.
113
114       For compatibility with the Crypt::CBC method of the same name, you can
115       pass a parameter (e.g. 'decrypting' or 'encrypting'), but it is
116       ignored.  With Salsa20, encryption and decryption are the same
117       operation, so there's no need to indicate which one you want.
118
119       This method is primarily for Crypt::CBC compatibility.  Since with
120       Salsa20 you don't need to specify whether you're encrypting or
121       decrypting, and the "iv" method also does everything "start" does, you
122       don't really need to call this method.
123
124   crypt
125         $ciphertext = $salsa20->crypt($plaintext);
126         $plaintext  = $salsa20->crypt($ciphertext);
127
128       Encrypts or decrypts the provided string.
129
130       Because encryption & decryption are the same operation, it is not
131       necessary to call "start" before calling "crypt", but you do need to
132       have set the IV, either by passing it to the constructor or calling the
133       "iv" method.
134
135   finish
136         $remaining_ciphertext = $salsa20->finish;
137
138       This method exists solely for Crypt::CBC compatibility.  It always
139       returns the empty string.
140
141   encrypt
142         $ciphertext = $salsa20->encrypt($plaintext);
143
144       Equivalent to calling "start" and then "crypt".
145
146   decrypt
147         $plaintext = $salsa20->decrypt($ciphertext);
148
149       Equivalent to calling "start" and then "crypt" (the same as "encrypt").
150
151   cryptor
152         $cryptor = $salsa20->cryptor;
153         $ciphertext = $cryptor->($plaintext); # or if decrypting,
154         $plaintext  = $cryptor->($ciphertext);
155
156       This method is the most efficient way to use Crypt::Salsa20 if you are
157       encrypting multiple chunks.  It returns a coderef that encrypts or
158       decrypts the text you pass it.  "$cryptor->($text)" is equivalent to
159       "$salsa20->crypt($text)", just faster.
160
161       The cryptor remains tied to the original object.  Changing the key or
162       IV affects it.  But it is not necessary to save a reference to the
163       original object if you don't plan to call any other methods.
164

CONFIGURATION AND ENVIRONMENT

166       Crypt::Salsa20 requires no configuration files or environment
167       variables.
168

INCOMPATIBILITIES

170       None reported.
171

BUGS AND LIMITATIONS

173       No bugs have been reported.
174

AUTHOR

176       Christopher J. Madsen  "<perl AT cjmweb.net>"
177
178       Please report any bugs or feature requests to
179       "<bug-Crypt-Salsa20 AT rt.cpan.org>" or through the web interface at
180       <http://rt.cpan.org/Public/Bug/Report.html?Queue=Crypt-Salsa20>.
181
182       You can follow or contribute to Crypt-Salsa20's development at
183       <https://github.com/madsen/crypt-salsa20>.
184
186       This software is copyright (c) 2014 by Christopher J. Madsen.
187
188       This is free software; you can redistribute it and/or modify it under
189       the same terms as the Perl 5 programming language system itself.
190

DISCLAIMER OF WARRANTY

192       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
193       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
194       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
195       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
196       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
197       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
198       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
199       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
200       NECESSARY SERVICING, REPAIR, OR CORRECTION.
201
202       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
203       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
204       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE
205       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
206       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
207       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
208       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
209       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
210       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
211       DAMAGES.
212
213
214
215perl v5.36.0                      2022-07-22                 Crypt::Salsa20(3)
Impressum