Ubuntu Manpage: Crypt::Eksblowfish::Subkeyed - Blowfish/Eksblowfish with access to subkeys

Provided by: libcrypt-eksblowfish-perl_0.009-3build5_amd64

NAME

       Crypt::Eksblowfish::Subkeyed - Blowfish/Eksblowfish with access to subkeys

SYNOPSIS

               use Crypt::Eksblowfish::Subkeyed;

               $block_size = Crypt::Eksblowfish::Subkeyed->blocksize;

               $cipher = Crypt::Eksblowfish::Subkeyed
                               ->new_from_subkeys(\@p_array, \@s_boxes);
               $cipher = Crypt::Eksblowfish::Subkeyed->new_initial;

               $block_size = $cipher->blocksize;
               $ciphertext = $cipher->encrypt($plaintext);
               $plaintext = $cipher->decrypt($ciphertext);

               $p_array = $cipher->p_array;
               $s_boxes = $cipher->s_boxes;
               if($cipher->is_weak) { ...

DESCRIPTION

       An object of this class encapsulates a keyed instance of the Blowfish or Eksblowfish block cipher, ready
       to encrypt and decrypt.  Normally this class will not be used directly, but through subclasses such as
       Crypt::Eksblowfish.

       Eksblowfish is a variant of the Blowfish cipher with a modified key setup algorithm.  This class doesn't
       implement either form of key setup, but only provides the actual encryption and decryption parts of the
       ciphers.  This part is shared between Blowfish and Eksblowfish, and also any other cipher that uses the
       core of Blowfish but supplies its own key setup.  This class has "Eksblowfish" in its name rather than
       "Blowfish" merely due to the historical accident that it is derived from the encryption engine that was
       used to implement Eksblowfish.

       The key setup phase of a block cipher, also known as the "key schedule", produces a set of "subkeys",
       which are somewhat like ordinary cryptographic keys (which are the input to the key setup algorithm) but
       are much larger.  In some block ciphers the subkeys also have special interrelationships.  In Blowfish
       the subkeys consist of a "P-array" of 18 32-bit entries (one per encryption round plus two more) and four
       "S-boxes" ("S" is for "substitution") each of which consists of 256 32-bit entries.  There is no special
       relationship between the values of the subkeys.

       Methods in this class allow a cipher object to be constructed from a full set of subkeys, and for the
       subkeys to be extracted from a cipher object.  Normal users don't need to do either of these things.
       It's mainly useful when devising a new key schedule to stick onto the Blowfish core, or when performing
       cryptanalysis of the cipher algorithm.

       Generating subkeys directly by a strong random process, rather than by expansion of a smaller random key,
       is an expensive and slightly bizarre way to get greater cryptographic strength from a cipher algorithm.
       It eliminates attacks on the key schedule, and yields the full strength of the core algorithm.  However,
       this is always a lot less strength than the amount of subkey material, whereas a normal key schedule is
       designed to yield strength equal to the length of the (much shorter) key.  Also, any non-randomness in
       the source of the subkey material is likely to lead to a cryptographic weakness, whereas a key schedule
       conceals any non-randomness in the choice of the key.

CLASS METHODS

       Crypt::Eksblowfish::Subkeyed->blocksize
           Returns  8,  indicating  the Eksblowfish block size of 8 octets.  This method may be called on either
           the class or an instance.

CONSTRUCTOR

       Crypt::Eksblowfish::Subkeyed->new_from_subkeys(ROUND_KEYS, SBOXES)
           Creates a new Blowfish cipher object encapsulating  the  supplied  subkeys.   ROUND_KEYS  must  be  a
           reference  to  an  array  of  18  32-bit  integers.   SBOXES  must be a reference to an array of four
           references to 256-element arrays of 32-bit integers.  These subkeys are used in  the  standard  order
           for Blowfish.

       Crypt::Eksblowfish::Subkeyed->new_initial
           The  standard  Blowfish  key  schedule  is  an  iterative process, which uses the cipher algorithm to
           progressively replace subkeys, thus mutating the cipher for subsequent  iterations  of  keying.   The
           Eksblowfish  key  schedule  works  similarly, but with a lot more iterations.  In both cases, the key
           setup algorithm begins with a standard set  of  subkeys,  consisting  of  the  initial  bits  of  the
           fractional part of pi.  This constructor creates and returns a Blowfish block cipher object with that
           standard initial set of subkeys.  This is probably useful only to designers of novel key schedules.

METHODS

$cipher->blocksize
Returns 8, indicating the Eksblowfish block size of 8 octets. This method may be called on either
the class or an instance.

$cipher->encrypt(PLAINTEXT)
PLAINTEXT must be exactly eight octets. The block is encrypted, and the ciphertext is returned.

$cipher->decrypt(CIPHERTEXT)
CIPHERTEXT must be exactly eight octets. The block is decrypted, and the plaintext is returned.

$cipher->p_array
Returns a reference to an 18-element array containing the 32-bit round keys used in this cipher
object.

$cipher->s_boxes
Returns a reference to a 4-element array containing the S-boxes used in this cipher object. Each
S-box is a 256-element array of 32-bit entries.

$cipher->is_weak
Returns a truth value indicating whether this is a weak key. A key is considered weak if any S-box
contains a pair of identical entries (in any positions). When Blowfish is used with such an S-box,
certain cryptographic attacks are possible that are not possible against most keys. The current (as
of 2007) cryptanalytic results on Blowfish do not include an actual break of the algorithm when weak
keys are used, but if a break is ever developed then it is likely to be achieved for weak keys before
it is achieved for the general case.

About one key in every 2^15 is weak (if the keys are randomly selected). Because of the complicated
key schedule in standard Blowfish it is not possible to predict which keys will be weak without first
performing the full key setup, which is why this is a method on the keyed cipher object. In some
uses of Blowfish it may be desired to avoid weak keys; if so, check using this method and generate a
new random key when a weak key is detected. Bruce Schneier, the designer of Blowfish, says it is
probably not worth avoiding weak keys.

AUTHOR

       Eksblowfish guts originally by Solar Designer (solar at openwall.com).

       Modifications and Perl interface by Andrew Main (Zefram) <zefram@fysh.org>.

COPYRIGHT

       Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>

       The original Eksblowfish code (in the form of crypt()) from which this module is derived is in the public
       domain.  It may be found at <http://www.openwall.com/crypt/>.

LICENSE

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

perl v5.40.0                                       2024-10-20                  Crypt::Eksblowfish::Subkeyed(3pm)