view release on metacpan or  search on metacpan

lib/Crypt/Salsa20.pm  view on Meta::CPAN

  Carp::croak("key is a required attribute")
        unless defined $input1;

  $self;
} # end new
#---------------------------------------------------------------------


sub key
{
  my $self = shift;

  if (@_) {
    $self->{set_key}->( $self->{key} = shift );
  }

  $self->{key};
} # end key
#---------------------------------------------------------------------


sub iv
{
  my $self = shift;

  if (@_) {
    $self->{set_iv}->( $self->{iv} = shift );
  }

  $self->{iv};
} # end iv


sub rounds { &{ shift->{cipher_rounds} } }

#---------------------------------------------------------------------


sub start { &{ shift->{reset_counter} } }

#---------------------------------------------------------------------


sub crypt { &{ shift->{crypt} } } # pass our @_ along


sub encrypt
{
  my $self = shift;

  &{ $self->{reset_counter} };
  &{ $self->{crypt} };
}

*decrypt = \&encrypt; # In Salsa20, encryption & decryption are the same

#---------------------------------------------------------------------


sub finish { '' }               # for Crypt::CBC compatibility

#---------------------------------------------------------------------


sub cryptor { shift->{crypt} }

#=====================================================================
# Package Return Value:

1;

__END__

=head1 NAME

Crypt::Salsa20 - Encrypt data with the Salsa20 cipher

=head1 VERSION

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

=head1 SYNOPSIS

  use Crypt::Salsa20;

  my $salsa20 = Crypt::Salsa20->new(-key => $key, -iv => $nonce);

  # Use cryptor for the best performance:
  my $cryptor = $salsa20->cryptor;
  my $ciphertext = $cryptor->('plaintext');
  # encryption & decryption are the same operation:
  $salsa20->start;   # reset the block counter (keeping key & iv)
  my $plaintext  = $cryptor->($ciphertext);

  # Or use Crypt::CBC-like API:
  my $ciphertext = $salsa20->encrypt('plaintext');
  my $plaintext  = $salsa20->decrypt($ciphertext);

=head1 DESCRIPTION

Crypt::Salsa20 implements D. J. Bernstein's Salsa20 stream cipher
(a.k.a. Snuffle 2005) in Perl.  For more information on Salsa20,
see his page at L<http://cr.yp.to/snuffle.html>.

Salsa20 takes a 256 bit (or 128 bit) key and a 64 bit nonce (a.k.a. an
IV or message number) and uses them to generate a stream of up to
2**70 bytes of pseudo-random data.  That stream is XORed with your
message.  Because of that, encryption and decryption are the same
operation.

It is critical that you never use the same nonce and key to encrypt
two different messages.  Because the keystream is completely
determined by the key and nonce, reusing them means that you can
cancel out the keystream by XORing the two ciphertexts together:

  ciphertext1          ^ ciphertext2
  keystream ^ message1 ^ keystream ^ message2
  message1  ^ message2 ^ keystream ^ keystream
  message1  ^ message2 ^           0
  message1  ^ message2


=head2 Crypt::Salsa20 vs. Crypt::CBC

The API is similar to that of the L<Crypt::CBC> module, but there are
some differences:

=over

=item 1.

There is no C<-literal_key> option.  The key is I<always> interpreted
as raw bytes (and must be either 16 or 32 bytes long).  If you want to
use a pasword hashing function, you have to supply your own.

=item 2.

Crypt::Salsa20 doesn't use any sort of header, trailer, padding, or
any other metadata.  If you need to transmit the nonce as part of your
message, you'll need to do it manually.

=item 3.

Since encryption and decryption are the same operation with Salsa20,
the C<start> method does not require a parameter, and it is not
necessary to call it at all.

=item 4.

The C<finish> method is available, but unnecessary.  In Crypt::Salsa20
it does nothing and always returns the empty string.

=back

=for Pod::Coverage
BLOCKSIZE
IS32BIT
LIMIT

=head1 ATTRIBUTES

Each attribute has a method of the same name.  Calling the method with
no parameter returns the current value of the attribute.  Calling it
with a parameter sets the attribute to that value (and returns the new
value).



=head2 key

The encryption key is a 16 or 32 byte string (128 or 256 bits), with
32 bytes being the recommended size.  It's always interpreted as raw
bytes; if you want to use a pasword hashing function, you have to
supply your own.  Setting the key does not change the IV or reset the
block counter.


=head2 iv

The nonce (IV) is an 8 byte string (64 bits).  The nonce does not need
to be kept secret, but you must never encrypt two different messages
with the same key and nonce, or you have catastrophically weakened the
security of the cipher.  You must supply an IV before encrypting or
decrypting, but you can omit it from the constructor and call the
C<iv> method instead.  Setting the IV does not change the key, but it
does reset the block counter.


=head2 rounds

The number of cipher rounds to use.  The default is 20, which is the
standard Salsa20 cipher.  The standard variants are 8 or 12 rounds
(Salsa20/8 or Salsa20/12), but any even integer will work.

=head1 METHODS

=head2 new

  $salsa20 = Crypt::Salsa20->new(-key => $key, ...);

This constructs a new Crypt::Salsa20 object, with attributes supplied
as S<C<< key => value >>> pairs.  For compatibility with Crypt::CBC,
attribute names may have a leading hyphen (but unlike Crypt::CBC the
hyphen is not required).

The only required attribute at construction time is the key (but you
must supply an IV before encrypting or decrypting).


=head2 start

  $salsa20->start;

Resets the internal block counter, starting the keystream over at the
beginning.  You should also change the IV, because using the same key
and IV is a security breach.

For compatibility with the Crypt::CBC method of the same name, you can
pass a parameter (e.g. C<'decrypting'> or C<'encrypting'>), but it is
ignored.  With Salsa20, encryption and decryption are the same operation,
so there's no need to indicate which one you want.

This method is primarily for Crypt::CBC compatibility.  Since with
Salsa20 you don't need to specify whether you're encrypting or
decrypting, and the C<iv> method also does everything C<start> does,
you don't really need to call this method.


=head2 crypt

  $ciphertext = $salsa20->crypt($plaintext);
  $plaintext  = $salsa20->crypt($ciphertext);

Encrypts or decrypts the provided string.

Because encryption & decryption are the same operation, it is not
necessary to call C<start> before calling C<crypt>, but you do need to
have set the IV, either by passing it to the constructor or calling
the C<iv> method.


=head2 finish

  $remaining_ciphertext = $salsa20->finish;

This method exists solely for Crypt::CBC compatibility.  It always
returns the empty string.


=head2 encrypt

  $ciphertext = $salsa20->encrypt($plaintext);

Equivalent to calling C<start> and then C<crypt>.


=head2 decrypt

  $plaintext = $salsa20->decrypt($ciphertext);

Equivalent to calling C<start> and then C<crypt> (the same as C<encrypt>).


=head2 cryptor

  $cryptor = $salsa20->cryptor;
  $ciphertext = $cryptor->($plaintext); # or if decrypting,
  $plaintext  = $cryptor->($ciphertext);

This method is the most efficient way to use Crypt::Salsa20 if you are
encrypting multiple chunks.  It returns a coderef that encrypts or
decrypts the text you pass it.  C<< $cryptor->($text) >> is equivalent
to C<< $salsa20->crypt($text) >>, just faster.

The cryptor remains tied to the original object.  Changing the key or
IV affects it.  But it is not necessary to save a reference to the
original object if you don't plan to call any other methods.

=head1 CONFIGURATION AND ENVIRONMENT

Crypt::Salsa20 requires no configuration files or environment variables.

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

=head1 AUTHOR

Christopher J. Madsen  S<C<< <perl AT cjmweb.net> >>>

Please report any bugs or feature requests
to S<C<< <bug-Crypt-Salsa20 AT rt.cpan.org> >>>
or through the web interface at
L<< http://rt.cpan.org/Public/Bug/Report.html?Queue=Crypt-Salsa20 >>.

You can follow or contribute to Crypt-Salsa20's development at
L<< https://github.com/madsen/crypt-salsa20 >>.

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Christopher J. Madsen.