info bigloo

15.1 Symmetric Block Ciphers

Bigloo supports some common block ciphers. Block ciphers work on blocks of fixed size. A mode of operation defines the way bigger input is handled. For instance in ECB (Electronic Codebook mode) the blocks are all encrypted separately, whereas CBC (Cipher-Block Chaining) chains all blocks.

All modes that chain the blocks need an IV (Initial Vector) to “bootstrap” the chaining.

Block ciphers by themselves can only work on full blocks. Some modes are constructed in a way that even incomplete blocks can be safely processed. For the remaining blocks a padding function needs to be given.

Most block ciphers only work with keys of specific length. The following functions take passwords (strings of arbitrary length) as input, and preprocess the given password by a :string->key function. The result must then be of correct length.

Bigloo Cryptography procedure: encrypt::bstring cipher plain password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]

Bigloo Cryptography procedure: encrypt-string::bstring cipher plaintext::bstring password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]

Bigloo Cryptography procedure: encrypt-mmap::bstring cipher plaintext::mmap password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]

Bigloo Cryptography procedure: encrypt-port::bstring cipher plaintext::input-port password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]

Bigloo Cryptography procedure: encrypt-file::bstring cipher filename::bstring password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]

Bigloo Cryptography procedure: encrypt-sendchars cipher in::input-port out::output-port password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]

The procedure encrypt encrypts its input using the chosen cipher. The result is returned as string. encrypt dispatches depending on the type of plain. Strings are processed by encrypt-string (and not encrypt-file).

The function encrypt-sendchars reads from an input-port in and encrypts its output directly into an output-port out.

The symbol cipher can be one of:

des: Data Encryption Standard (DES). DES works on blocks of 64 bits. DES requires keys of length 64 (bits), but only 56 of these bits are actually used. Bigloo’s implementation therefore accepts both. DES is considered to be insecure and its usage is discouraged.
des3: Triple DES, Triple Data Encryption Algorithm (DES3, TDEA). DES3 works on blocks of 64 bits. DES3 requires keys of length 128 or 192 (bits), but only 112/168 of these bits are actually used. Bigloo’s implementation therefore accepts the smaller keys too.
Bigloo’s DES3 implementation has been changed with release 3.4b. Earlier versions did not use the full key for en/decryption.
des-np: Same as des, but the initial and final permutations are not performed.
des3-np: Same as des3, but the initial and final permutations are not performed.
aes: Advanced Encryption Standard (AES). AES works on blocks of 128 bits. AES requires keys of length 128, 192 or 256 bits.
cast-128: CAST-128 (CAST5). CAST-128 works on blocks of 64 bits. CAST-128 requires a key-length of 40-128 bits.
idea: International Data Encryption Algorithm (IDEA). IDEA works on blocks of 64 bits. It requires keys of length 128 (in bits). IDEA is patented in many countries (including the USA and most European countries) but it is free for non-commercial use.

The given password must be a string. An optional parameter :string->key should transform this password so that it has the correct length for the cipher. A small list of possible functions are provided in the String to Key section.

By default string->key-hash with SHA-1 will be used. The key-length will depend on the chosen cipher:

des: 56 bits.
des3: 112 bits.
des-np: Same as des.
des3-np: Same as des3.
aes: 192 bits.
cast-128: 128 bits.
idea: 128 bits.

Bigloo supports the following block cipher modes (:mode):

ecb: Electronic codebook.
cbc: Cipher-block chaining.
pcbc: Propagating cipher-block chaining.
cfb: Cipher feedback.
ofb: Output feedback.
ctr: Counter.

By default cfb is chosen.

Electronic codebook mode en/decodes each block independently and is hence the closest to the block cipher. It is however inherently unsafe as blocks with the same content are encrypted to the same output.

With the exception of ecb all other modes can be initialized with an IV (Initialization vector). If :IV is false, then a random one will be generated. During encryption this randomly generated IV will be prefixed to the result. When calling the decryption routine without any IV the procedure will use the first block of the input as IV.

In ctr (counter) mode the IV parameter serves as nonce. Two additional key-parameters :nonce-init and :nonce-update are then used to initialize and update the block-sized nonce string. Before encrypting the first block nonce-init will be invoked with an empty block-sized string and the initial nonce (IV). It must initialize the string with the nonce. For each block nonce-update will be called with the string, the nonce, and the number of already encrypted blocks (hence 0 at the very beginning). By default nonce-init takes the IV-string and blits it into the given string. nonce-update simply increments the string (treating the given string as one big number).

Note that the initial nonce (passed using IV) may be of any type. As long as nonce-init and nonce-update correctly initialize and update the passed string.

The input’s length of modes ecb, cbc and pcbc must be a multiple of the block-size. Should this not be the case a padding algorithm must be specified (:pad). Currently are implemented (examples for hexadecimal string “DD” and cipher block size 4):

none: No padding. Raises an error should the input not be a multiple.
bit: Bit padding. Add a ’1’ bit and then ’0’ bits. Example: “DD 80 00 00”.
ansi-x.923: Byte padding. Fill with #x00s followed by the number of added bytes (the counter inclusive). Example: “DD 00 00 03”.
iso-10126: Fill with random characters followed by the number of added bytes (the counter inclusive). Example: “DD 42 31 03”.
pkcs7: Fill with the number of added bytes. Example: “DD 03 03 03”.
zero: Fill with zeros. This is only reversible if the input is guaranteed not to finish with a zero character. Example: “DD 00 00 00”.

Alternatively users can supply their own (un)pad functions (instead of a symbol). The signature of a padding function is (pad::bool str::bstring valid-chars::long). It receives the last block of the input. Should the input be of correct length then the an empty block will be sent to the padding function. valid-chars indicates the number of read characters. It ranges from 0 to blocksize-1. The padding function should fill the block and return #t if this last block should be encoded. By returning #f the last block will be discarded. This makes only sense if valid-chars was equal to 0.

The unpadding procedure has the signature (unpad::long str::bstring). The input string will have the length of the block-size. The unpadding function may modify the string and must return the number of characters that are valid.

Bigloo Cryptography procedure: decrypt::bstring cipher ciphertext password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]
Bigloo Cryptography procedure: decrypt-string::bstring cipher ciphertext::bstring password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]
Bigloo Cryptography procedure: decrypt-mmap::bstring cipher ciphertext::mmap password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]
Bigloo Cryptography procedure: decrypt-port::bstring cipher ciphertext::input-port password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]
Bigloo Cryptography procedure: decrypt-file::bstring cipher filename::bstring password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]
Bigloo Cryptography procedure: decrypt-sendchars cipher in::input-port out::output-port password [:string->key] [:mode 'cfb] [:IV #f] [:pad 'none] [:nonce-init!] [:nonce-update!]: Counterpart to the encryption functions. With the same parameters the decrypt function will decrypt the result of an encrypt call. Without :IV (Initial Vector) the decrypt function will use the first block as IV.

For compatibility the following functions remain in Bigloo. They are in the default library and not inside the crypto library.

bigloo procedure: aes-ctr-encrypt text password [nbits 128]
bigloo procedure: aes-ctr-encrypt-mmap mmap password [nbits 128]
bigloo procedure: aes-ctr-encrypt-string string password [nbits 128]
bigloo procedure: aes-ctr-encrypt-port iport password [nbits 128]
bigloo procedure: aes-ctr-encrypt-file filename password [nbits 128]: These functions are equivalent to a call to aes-encrypt with mode set to ctr and a special :string->key parameter. The optional argument nbits must either be 128, 192, or 256 and determines the size of the key.

bigloo procedure: aes-ctr-decrypt text password [nbits 128]
bigloo procedure: aes-ctr-decrypt-mmap mmap password [nbits 128]
bigloo procedure: aes-ctr-decrypt-string string password [nbits 128]
bigloo procedure: aes-ctr-decrypt-port iport password [nbits 128]
bigloo procedure: aes-ctr-decrypt-file filename password [nbits 128]: Counterpart to aes-ctr-encrypt.

This document was generated on October 23, 2011 using texi2html 5.0.