NAME

GCrypt - Perl interface to the GNU Crypto library

SYNOPSIS

use GCrypt;

$cipher = new GCrypt::Cipher('aes', 'cbc');

$cipher->setkey('a secret');

$cipher->setiv('init vector');

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

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

ABSTRACT

GCrypt is the Perl interface to the same-named LGPL'd library of cryptographic functions. Currently only symmetric encryption/decryption is supported by this interface.

DESCRIPTION

Note that if you are still confused by the crypto terminology, head over to "BACKGROUND" first.

Symmetric encryption/decryption is done by first obtaining a Cipher object:

$cipher = new GCrypt::Cipher(ALGORITHM[, MODE[, FLAGS]]);

ALGORITHM is a string naming the algorithm. At the time of writing, the following choices are available:

3des Triple DES, 112 bit key

aes The Advanced Encryption Standard, a.k.a. Rijndael, 128 bit key

aes192 AES with 192 bit key

aes256 AES with 256 bit key

blowfish

cast5

des Date Encryption Standard, 56 bit key, too short to thwart brute-forcing

twofish Successor of Blowfish, 256 bit key

arcfour stream cipher

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

stream only possible mode for stream ciphers

ecb don't use an IV, encrypt each block on it's own

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

Between calls the "last block" is stored in the IV.

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

FLAGS is a string containing zero or more flags seperated by a pipe (|). The possible flags are:

secure all data associated with this cipher will be put into non-swappable storage, if possible.

enable_sync enable the CFB sync operation.

$cipher->setkey(KEY)

Encryption and decryption operations will use KEY until a different one is set. If 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.

$cipher->setiv([IV])

Set the initialisation vector to IV 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.

$cipher->encrypt(PLAINTEXT)

This method encrypts PLAINTEXT with $cipher, returning the corresponding ciphertext. Null byte padding is automatically appended if PLAINTEXT's length is not evenly divisible by $cipher's block size.

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

$cipher->keylen()

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

$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 support feeding less than a byte into the cipher.

$cipher->sync()

Apply the CFB sync operation.

EXPORT

None, as the interface is object-oriented.

BACKGROUND

Symmetric ciphers are basically black boxes that you prime with a key. Then you can feed them plaintext, which they will munch into the encrypted result called ciphertext. They work into the other direction as well (hence the "symmetric"), taking ciphertext as input and reconstructing it into plaintext.

There are two kind of symmetric ciphers: block ciphers like AES take their input in chunks of a fixed size (e.g. 256 bit), producing a corresponding block of output (usually of the same size) for each such chunk. If the plaintext length is not evenly divisible by the block size, padding (normally a suitable number of null bytes) is appended to the end. This has to be removed again after decryption.

stream ciphers take input one bit at a time (you can think of them as special block ciphers with the smallest possible block size), and produce a corresponding output bit. Their advantage is that each bit of plaintext can be immediately encrypted as soon as it is available (think: encryption of an audio stream).

SEE ALSO

The gcrypt manual should be available via info gcrypt from the shell or C-h i g (gcrypt) from inside emacs.

AUTHOR

Robert Bihlmeyer, <robbe@orcus.priv.at>

COPYRIGHT AND LICENSE

Copyright 2002 by Robert Bihlmeyer

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm GCrypt

perl -MCPAN -e shell
install GCrypt