blowfish-encrypt

Arguments: value &key key end context pad in-place (external-format :utf-8) (mode :ecb) iv

Blowfish is an old cipher, designed in 1993. We recommend it not be used, because it is susceptible to various attacks and is no longer considered secure. We maintain support to allow for encrypted material to be decrypted.

This function encrypts value using the specified key or context and returns two values: an (unsigned-byte 8) array holding the encryption and an integer specifying the index into that array just after the end of the encrypted result (equivalently, the length of the encrypted result). The second value will also be the length of the array returned as the first value if the in-place is nil (which is its default). If in-place is true, the second returned value will be less than or equal to the length of the first returned value.

The arguments are:

• value (the single required argument): an (unsigned-byte 8) array or string to be encrypted.
• key: a string or (unsigned-byte 8) array which serves as the encryption key. Do not specify a value for this argument and for context.
• end: an integer or nil. If an integer, the length of the portion of value to be encrypted. If nil, then the whole of value is encrypted. (The in-place argument to both this function and to blowfish-decrypt allows using an existing (unsigned-byte 8) array, which may be larger than necessary to hold the encrypted value. This argument allows you to specify the portion of interest and ignore the remainder of the array.)
• context: an object (again, an (unsigned-byte 8) array) returned by blowfish-init when passed the key to be used to encrypt value. This argument is typically used when a number of things need to be encrypted or decrypted using the same key. (The first step in encryption and decryption is to convert the key into a context object. Using the context object directly avoids repeating this step for each encryption/decryption.) Do not specify a value for this argument and for key.
• pad (default is t): if pad is true then the value to be encrypted will be padded out to have an octet length that is a multiple of 8. The pad is constructed such that it contains information specifying how much padding was added so that when the result is decrypted, the padding can be removed. Thus if pad is true then at least one and as many as eight more octets will be added to the returned value. If pad is :pkcs5, then standard PKCS#5 padding will be used. If pad is :zero, then null padding will be used. Note that null padding is only suitable if the value to be encrypted contains no null octets. If pad is nil then an error is signaled if the value to be encrypted doesn't have a length that is a multiple of 8.
• in-place: if specified true, the value of value will be modified to hold the encrypted value (if possible), thus avoiding the creation of a new array. If it is not possible to encrypt in place then this argument will be ignored and a new (unsigned-byte 8) array will be created. (This would happen when value is a string rather than an (unsigned-byte 8) array or when value is not large enough to hold the result.) If value is used, the second returned value (the number of bytes in the decryption) may be less than the length of the first returned value.
• external-format: this argument specifies the external format to be used when interpreting the string to be encrypted. The same external format should be used when decrypting. The default is :utf-8 and that is in general a good choice. When :default is specified, the value returned by (find-external-format :default) is used (see find-external-format). That value is not recommended because the value of the default external format (which depends on the value of *locale*) may change between encryption and decryption.
• mode: this argument allows specifying ECB (Electronic Code Book) encryption or CBC (Cipher Block Chaining) encryption. The default is :ecb, meaning use ECB. Specify :cbc for CBC. The text must be decrypted in the same mode. If CBC encryption mode is requested, the initialization vector (IV) must be provided by using keyword argument iv. The IV must be a usb8 array of at least 8 elements. The IV will be modified so that it may be used for subsequent encrypt/decrypt calls. CBC encryption is generally considered superior to ECB encryption and should be used unless there is a reason not to.
• iv: ignored unless mode is specified :cbc. When mode is :cbc, the value, called the initialization vector or IV, must be an (unsigned-byte 8) array of at least 8 elements. The IV will be modified so that it may be used for subsequent encrypt/decrypt calls.

See also the new auxilliary functions hex-string-to-usb8-array and usb8-array-to-hex-string.

See also blowfish-decrypt and blowfish-init.

See Support for Blowfish encryption in miscellaneous.htm for information on Blowfish encryption and Blowfish encryption support in Allegro CL. There are examples of blowfish encryption and decryption in that section. Support for encryption in the same document discusses encryption support in Allegro CL in general.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.