1Crypt::Salsa20(3) User Contributed Perl Documentation Crypt::Salsa20(3)
2
6 Crypt::Salsa20 - Encrypt data with the Salsa20 cipher
7
9 This document describes version 0.03 of Crypt::Salsa20, released
10 January 25, 2014.
11
13 use Crypt::Salsa20;
14 my $salsa20 = Crypt::Salsa20->new(-key => $key, -iv => $nonce);
16 # 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 # Or use Crypt::CBC-like API:
25 my $ciphertext = $salsa20->encrypt('plaintext');
26 my $plaintext = $salsa20->decrypt($ciphertext);
27
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 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 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 ciphertext1 ^ ciphertext2
44 keystream ^ message1 ^ keystream ^ message2
45 message1 ^ message2 ^ keystream ^ keystream
46 message1 ^ message2 ^ 0
47 message1 ^ message2
48 Crypt::Salsa20 vs. Crypt::CBC
50 The API is similar to that of the Crypt::CBC module, but there are some
51 differences:
52 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 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 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 4. The "finish" method is available, but unnecessary. In
66 Crypt::Salsa20 it does nothing and always returns the empty string.
67
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 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 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 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
96 new
97 $salsa20 = Crypt::Salsa20->new(-key => $key, ...);
98 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 The only required attribute at construction time is the key (but you
105 must supply an IV before encrypting or decrypting).
106 start
108 $salsa20->start;
109 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 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 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 crypt
125 $ciphertext = $salsa20->crypt($plaintext);
126 $plaintext = $salsa20->crypt($ciphertext);
127 Encrypts or decrypts the provided string.
129 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 finish
136 $remaining_ciphertext = $salsa20->finish;
137 This method exists solely for Crypt::CBC compatibility. It always
139 returns the empty string.
140 encrypt
142 $ciphertext = $salsa20->encrypt($plaintext);
143 Equivalent to calling "start" and then "crypt".
145 decrypt
147 $plaintext = $salsa20->decrypt($ciphertext);
148 Equivalent to calling "start" and then "crypt" (the same as "encrypt").
150 cryptor
152 $cryptor = $salsa20->cryptor;
153 $ciphertext = $cryptor->($plaintext); # or if decrypting,
154 $plaintext = $cryptor->($ciphertext);
155 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 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
166 Crypt::Salsa20 requires no configuration files or environment
167 variables.
168
170 None reported.
171
173 No bugs have been reported.
174
176 Christopher J. Madsen "<perl AT cjmweb.net>"
177 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 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 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
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 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.
212perl v5.32.1 2021-01-27 Crypt::Salsa20(3)