phpman > perldoc > Convert::PEM::CBC(3pm)

NAME
    Convert::PEM::CBC - Cipher Block Chaining Mode implementation

SYNOPSIS
        use Convert::PEM::CBC;
        my $cbc = Convert::PEM::CBC->new(
                             Cipher     => 'Crypt::DES_EDE3',
                             Passphrase => 'foo'
               );

        my $plaintext = 'foo bar baz';
        $cbc->encrypt($plaintext);

DESCRIPTION
    *Convert::PEM::CBC* implements the CBC (Cipher Block Chaining) mode for encryption/decryption
    ciphers; the CBC is designed for compatability with OpenSSL and may not be compatible with other
    implementations (such as SSH).

USAGE
  $cbc = Convert::PEM::CBC->new(%args)
    Creates a new *Convert::PEM::CBC* object and initializes it. Returns the new object.

    *%args* can contain:

    *   Cipher

        Either the name of an encryption cipher class (eg. *Crypt::DES*), or an object already
        blessed into such a class. The class must support the *keysize*, *blocksize*, *encrypt*, and
        *decrypt* methods. If the value is a blessed object, it is assumed that the object has
        already been initialized with a key.

        This argument is mandatory.

    *   Passphrase

        A passphrase to encrypt/decrypt the content. This is different in implementation from a key
        (*Key*), because it is assumed that a passphrase comes directly from a user, and must be
        munged into the correct form for a key. This "munging" is done by repeatedly computing an
        MD5 hash of the passphrase, the IV, and the existing hash, until the generated key is longer
        than the keysize for the cipher (*Cipher*).

        Because of this "munging", this argument can be any length (even an empty string).

        If you give the *Cipher* argument an object, this argument is ignored. If the *Cipher*
        argument is a cipher class, either this argument or *Key* must be provided.

    *   Key

        A raw key, to be passed directly to the new cipher object. Because this is passed directly
        to the cipher itself, the length of the key must be equal to or greater than the keysize for
        the *Cipher*.

        As with the *Passphrase* argument, if you give the *Cipher* argument an already-constructed
        cipher object, this argument is ignored. If the *Cipher* argument is a cipher class, either
        this argument or *Passphrase* must be provided.

    *   IV

        The initialization vector for CBC mode.

        This argument is optional; if not provided, a random IV will be generated. Obviously, if
        you're decrypting data, you should provide this argument, because your IV should match the
        IV used to encrypt the data.

  $cbc->encrypt($plaintext)
    Encrypts the plaintext *$plaintext* using the underlying cipher implementation in CBC mode, and
    returns the ciphertext.

    If any errors occur, returns *undef*, and you should check the *errstr* method to find out what
    went wrong.

  $cbc->decrypt($ciphertext)
    Decrypts the ciphertext *$ciphertext* using the underlying cipher implementation in CBC mode,
    and returns the plaintext.

    If any errors occur, returns *undef*, and you should check the *errstr* method to find out what
    went wrong.

  $cbc->iv
    Returns the current initialization vector. One use for this might be to grab the initial value
    of the IV if it's created randomly (ie. you haven't provided an *IV* argument to *new*):

        my $cbc = Convert::PEM::CBC->new( Cipher => $cipher );
        my $iv = $cbc->iv;   ## Generated randomly in 'new'.

    *Convert::PEM* uses this to write the IV to the PEM file when encrypting, so that it can be
    known when trying to decrypt the file.

  $cbc->errstr
    Returns the value of the last error that occurred. This should only be considered meaningful
    when you've received *undef* from one of the functions above; in all other cases its relevance
    is undefined.

AUTHOR & COPYRIGHTS
    Please see the Convert::PEM manpage for author, copyright, and license information.