gcrypt_version()

built_against_version()

cipher_algo_available()

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

new()

  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:

mode

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

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:

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.

digest_algo_available()

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

new()

  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()).

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()

clone()

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.