Provided by: libcrypt-gcrypt-perl_1.26-5build2_amd64 bug

NAME

       Crypt::GCrypt - Perl interface to the GNU Cryptographic library

SYNOPSIS

         use Crypt::GCrypt;

         my $cipher = Crypt::GCrypt->new(
           type => 'cipher',
           algorithm => 'aes',
           mode => 'cbc'
         );
         $cipher->start('encrypting');

         $cipher->setkey('my secret key');
         $cipher->setiv('my init vector');

         my $ciphertext  = $cipher->encrypt('plaintext');
         $ciphertext .= $cipher->finish;

         my $plaintext  = $cipher->decrypt($ciphertext);
         $plaintext .= $cipher->finish;

ABSTRACT

       Crypt::GCrypt provides an object interface to the C libgcrypt library. It currently
       supports symmetric encryption/decryption and message digests, while asymmetric
       cryptography is being worked on.

BINDING INFO

   gcrypt_version()
       Returns a string indicating the running version of gcrypt.

   built_against_version()
       Returns a string indicating the version of gcrypt that this module was built against.
       This is likely only to be useful in a debugging situation.

SYMMETRIC CRYPTOGRAPHY

   cipher_algo_available()
       Determines whether a given cipher algorithm is available in the local gcrypt installation:

         if (Crypt::GCrypt::cipher_algo_available('aes')) {
           # do stuff with aes
         }

   new()
       In order to encrypt/decrypt your data using a symmetric cipher you first have to build a
       Crypt::GCrypt object:

         my $cipher = Crypt::GCrypt->new(
           type => 'cipher',
           algorithm => 'aes',
           mode => 'cbc'
         );

       The type argument must be "cipher" and algorithm is required too. See below for a
       description of available algorithms and other initialization parameters:

       algorithm
           This may be one of the following:

           3des    Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but you
                   have to pass 192 bits because the most significant bits of each byte are
                   ignored.

           aes     AES (Rijndael) with a 128 bit key.

           aes192  AES (Rijndael) with a 192 bit key.

           aes256  AES (Rijndael) with a 256 bit key.

           blowfish
                   The blowfish algorithm. The current implementation allows only for a key size
                   of 128 bits (and thus is not compatible with Crypt::Blowfish).

           cast5   CAST128-5 block cipher algorithm.  The key size is 128 bits.

           des     Standard DES with a 56 bit key. You need to pass 64 bit but the high bits of
                   each byte are ignored.  Note, that this is a weak algorithm which can be
                   broken in reasonable time using a brute force approach.

           twofish The Twofish algorithm with a 256 bit key.

           twofish128
                   The Twofish algorithm with a 128 bit key.

           arcfour An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.  Note
                   that this is a stream cipher and must be used very carefully to avoid a couple
                   of weaknesses.

       mode
           This is a string specifying one of the following encryption/decryption modes:

           stream  only available for stream ciphers

           ecb     doesn't use an IV, encrypts each block independently

           cbc     the current ciphertext block is encryption of current plaintext block xor-ed
                   with last ciphertext block

           cfb     the current ciphertext block is the current plaintext block xor-ed with the
                   current keystream block, which is the encryption of the last ciphertext block

           ofb     the current ciphertext block is the current plaintext block xor-ed with the
                   current keystream block, which is the encryption of the last keystream block

           If no mode is specified then cbc is selected for block ciphers, and stream for stream
           ciphers.

       padding
           When the last block of plaintext is shorter than the block size, it must be padded
           before encryption. Padding should permit a safe unpadding after decryption.
           Crypt::GCrypt currently supports two methods:

           standard
                   This is also known as PKCS#5 padding, as it's binary safe. The string is
                   padded with the number of bytes that should be truncated. It's compatible with
                   Crypt::CBC.

           null    Only for text strings. The block will be padded with null bytes (00). If the
                   last block is a full block and blocksize is 8, a block of "0000000000000000"
                   will be appended.

           none    By setting the padding method to "none", Crypt::GCrypt will only accept a
                   multiple of blklen as input for "encrypt()".

       secure
           If this option is set to a true value, all data associated with this cipher will be
           put into non-swappable storage, if possible.

       enable_sync
           Enable the CFB sync operation.

       Once you've got your cipher object the following methods are available:

   start()
          $cipher->start('encrypting');
          $cipher->start('decrypting');

       This method must be called before any call to setkey() or setiv(). It prepares the cipher
       for encryption or decryption, resetting the internal state.

   setkey()
          $cipher->setkey('my secret key');

       Encryption and decryption operations will use this key until a different one is set. If
       your key is shorter than the cipher's keylen (see the "keylen" method) it will be zero-
       padded, if it is longer it will be truncated.

   setiv()
          $cipher->setiv('my iv');

       Set the initialisation vector for the next encrypt/decrypt operation.  If IV is missing a
       "standard" IV of all zero is used. The same IV is set in newly created cipher objects.

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

       This method encrypts $plaintext with $cipher, returning the corresponding ciphertext. The
       output is buffered; this means that you'll only get multiples of $cipher's block size and
       that at the end you'll have to call "finish()".

   finish()
           $ciphertext .= $cipher->finish;

           $plaintext .= $cipher->finish;

       The CBC algorithm must buffer data blocks internally until there are even multiples of the
       encryption algorithm's blocksize (typically 8 or 16 bytes).  After the last call to
       encrypt() or decrypt() you should call finish() to flush the internal buffer and return
       any leftover data. This method will also take care of padding/unpadding of data (see the
       "padding" option above).

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

       The counterpart to encrypt, decrypt takes a $ciphertext and produces the original
       plaintext (given that the right key was used, of course).  The output is buffered; this
       means that you'll only get multiples of $cipher's block size and that at the end you'll
       have to call "finish()".

   keylen()
          print "Key length is " . $cipher->keylen();

       Returns the number of bytes of keying material this cipher needs.

   blklen()
          print "Block size is " . $cipher->blklen();

       As their name implies, block ciphers operate on blocks of data. This method returns the
       size of this blocks in bytes for this particular cipher. For stream ciphers 1 is returned,
       since this implementation does not feed less than a byte into the cipher.

   sync()
          $cipher->sync();

       Apply the CFB sync operation.

MESSAGE DIGESTS

   digest_algo_available()
       Determines whether a given digest algorithm is available in the local gcrypt installation:

          if (Crypt::GCrypt::digest_algo_available('sha256')) {
             # do stuff with sha256
          }

   new()
       In order to create a message digest, you first have to build a Crypt::GCrypt object:

         my $digest = Crypt::GCrypt->new(
           type => 'digest',
           algorithm => 'sha256',
         );

       The type argument must be "digest" and algorithm is required too. See below for a
       description of available algorithms and other initialization parameters:

       algorithm
           Depending on your available version of gcrypt, this can be one of the following hash
           algorithms.  Note that some gcrypt installations do not implement certain algorithms
           (see digest_algo_available()).

           md4
           md5
           ripemd160
           sha1
           sha224
           sha256
           sha384
           sha512
           tiger192
           whirlpool
       secure
           If this option is set to a true value, all data associated with this digest will be
           put into non-swappable storage, if possible.

       hmac
           If the digest is expected to be used as a keyed-Hash Message Authentication Code
           (HMAC), supply the key with this argument.  It is good practice to ensure that the key
           is at least as long as the digest used.

       Once you've got your digest object the following methods are available:

   digest_length()
           my $len = $digest->digest_length();

       Returns the length in bytes of the digest produced by this algorithm.

   write()
           $digest->write($data);

       Feeds data into the hash context.  Once you have called read(), this method can't be
       called anymore.

   reset()
       Re-initializes the digest with the same parameters it was initially created with.  This
       allows write()ing again, after a call to read().

   clone()
       Creates a new digest object with the exact same internal state.  This is useful if you
       want to retrieve intermediate digests (i.e.  read() from the copy and continue write()ing
       to the original).

   read()
           my $md = $digest->read();

       Completes the digest and return the resultant string.  You can call this multiple times,
       and it will return the same information.  Once a digest object has been read(), it may not
       be written to.

THREAD SAFETY

       libgcrypt is initialized with support for Pthread, so this module should be thread safe.

SEE ALSO

       Crypt::GCrypt::MPI supports Multi-precision integers (bignum math) using libgcrypt as the
       backend implementation.

BUGS AND FEEDBACK

       There are no known bugs. You are very welcome to write mail to the author (aar@cpan.org)
       with your contributions, comments, suggestions, bug reports or complaints.

AUTHORS AND CONTRIBUTORS

       Alessandro Ranellucci <aar@cpan.org>

       Daniel Kahn Gillmor (message digests) <dkg@fifthhorseman.net>

COPYRIGHT AND LICENSE

       Copyright (c) Alessandro Ranellucci.  Crypt::GCrypt is free software, you may redistribute
       it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

       This module was initially inspired by the GCrypt.pm bindings made by Robert Bihlmeyer in
       2002. Thanks to users who give feedback and submit patches (see Changelog).

DISCLAIMER

       This software is provided by the copyright holders and contributors ``as is'' and any
       express or implied warranties, including, but not limited to, the implied warranties of
       merchantability and fitness for a particular purpose are disclaimed. In no event shall the
       regents or contributors be liable for any direct, indirect, incidental, special,
       exemplary, or consequential damages (including, but not limited to, procurement of
       substitute goods or services; loss of use, data, or profits; or business interruption)
       however caused and on any theory of liability, whether in contract, strict liability, or
       tort (including negligence or otherwise) arising in any way out of the use of this
       software, even if advised of the possibility of such damage.