1.\" $OpenBSD: BF_set_key.3,v 1.12 2023/08/05 18:27:55 jmc Exp $ 2.\" OpenSSL 99d63d46 Jul 19 09:27:53 2016 -0400 3.\" 4.\" This file was written by Richard Levitte <levitte@openssl.org>. 5.\" Copyright (c) 2000, 2002, 2005, 2014, 2016 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: August 5 2023 $ 53.Dt BF_SET_KEY 3 54.Os 55.Sh NAME 56.Nm BF_set_key , 57.Nm BF_encrypt , 58.Nm BF_decrypt , 59.Nm BF_ecb_encrypt , 60.Nm BF_cbc_encrypt , 61.Nm BF_cfb64_encrypt , 62.Nm BF_ofb64_encrypt 63.Nd Blowfish encryption 64.Sh SYNOPSIS 65.In openssl/blowfish.h 66.Ft void 67.Fo BF_set_key 68.Fa "BF_KEY *key" 69.Fa "int len" 70.Fa "const unsigned char *data" 71.Fc 72.Ft void 73.Fo BF_encrypt 74.Fa "BF_LONG *data" 75.Fa "const BF_KEY *key" 76.Fc 77.Ft void 78.Fo BF_decrypt 79.Fa "BF_LONG *data" 80.Fa "const BF_KEY *key" 81.Fc 82.Ft void 83.Fo BF_ecb_encrypt 84.Fa "const unsigned char *in" 85.Fa "unsigned char *out" 86.Fa "BF_KEY *key" 87.Fa "int enc" 88.Fc 89.Ft void 90.Fo BF_cbc_encrypt 91.Fa "const unsigned char *in" 92.Fa "unsigned char *out" 93.Fa "long length" 94.Fa "BF_KEY *schedule" 95.Fa "unsigned char *ivec" 96.Fa "int enc" 97.Fc 98.Ft void 99.Fo BF_cfb64_encrypt 100.Fa "const unsigned char *in" 101.Fa "unsigned char *out" 102.Fa "long length" 103.Fa "BF_KEY *schedule" 104.Fa "unsigned char *ivec" 105.Fa "int *num" 106.Fa "int enc" 107.Fc 108.Ft void 109.Fo BF_ofb64_encrypt 110.Fa "const unsigned char *in" 111.Fa "unsigned char *out" 112.Fa "long length" 113.Fa "BF_KEY *schedule" 114.Fa "unsigned char *ivec" 115.Fa "int *num" 116.Fc 117.Sh DESCRIPTION 118This library implements the Blowfish cipher, 119which was invented and defined by 120.An Counterpane . 121Note that applications should use higher level functions such as 122.Xr EVP_EncryptInit 3 123instead of calling the Blowfish functions directly. 124.Pp 125Blowfish is a block cipher that operates on 64-bit (8 byte) blocks of data. 126It uses a variable size key, but typically, 128-bit (16 byte) keys 127are considered good for strong encryption. 128Blowfish can be used in the same modes as DES 129and is currently one of the faster block ciphers. 130It is quite a bit faster than DES, and much faster than IDEA or RC2. 131.Pp 132Blowfish consists of a key setup phase 133and the actual encryption or decryption phase. 134.Pp 135.Fn BF_set_key 136sets up the 137.Vt BF_KEY 138.Fa key 139using the 140.Fa len 141bytes long key at 142.Fa data . 143.Pp 144.Fn BF_ecb_encrypt 145is the basic Blowfish encryption and decryption function. 146It encrypts or decrypts the first 64 bits of 147.Fa in 148using the key 149.Fa key , 150putting the result in 151.Fa out . 152.Fa enc 153decides if encryption 154.Pq Dv BF_ENCRYPT 155or decryption 156.Pq Dv BF_DECRYPT 157shall be performed. 158The vector pointed at by 159.Fa in 160and 161.Fa out 162must be 64 bits in length, no less. 163If they are larger, everything after the first 64 bits is ignored. 164.Pp 165The mode functions 166.Fn BF_cbc_encrypt , 167.Fn BF_cfb64_encrypt , 168and 169.Fn BF_ofb64_encrypt 170all operate on variable length data. 171They all take an initialization vector 172.Fa ivec 173which needs to be passed along into the next call of the same function 174for the same message. 175.Fa ivec 176may be initialized with anything, but the recipient needs to know what 177it was initialized with, or it won't be able to decrypt. 178Some programs and protocols simplify this, like SSH, where 179.Fa ivec 180is simply initialized to zero. 181.Fn BF_cbc_encrypt 182operates on data that is a multiple of 8 bytes long, while 183.Fn BF_cfb64_encrypt 184and 185.Fn BF_ofb64_encrypt 186are used to encrypt a variable number of bytes (the amount 187does not have to be an exact multiple of 8). 188The purpose of the latter two is to simulate stream ciphers and, 189therefore, they need the parameter 190.Fa num , 191which is a pointer to an integer where the current offset in 192.Fa ivec 193is stored between calls. 194This integer must be initialized to zero when 195.Fa ivec 196is initialized. 197.Pp 198.Fn BF_cbc_encrypt 199is the Cipher Block Chaining function for Blowfish. 200It encrypts or decrypts the 64-bit chunks of 201.Fa in 202using the key 203.Fa schedule , 204putting the result in 205.Fa out . 206.Fa enc 207decides if encryption 208.Pq Dv BF_ENCRYPT 209or decryption 210.Pq Dv BF_DECRYPT 211shall be performed. 212.Fa ivec 213must point at an 8-byte long initialization vector. 214.Pp 215.Fn BF_cfb64_encrypt 216is the CFB mode for Blowfish with 64-bit feedback. 217It encrypts or decrypts the bytes in 218.Fa in 219using the key 220.Fa schedule , 221putting the result in 222.Fa out . 223.Fa enc 224decides if encryption 225.Pq Dv BF_ENCRYPT 226or decryption 227.Pq Dv BF_DECRYPT 228shall be performed. 229.Fa ivec 230must point at an 2318-byte long initialization vector. 232.Fa num 233must point at an integer which must be initially zero. 234.Pp 235.Fn BF_ofb64_encrypt 236is the OFB mode for Blowfish with 64-bit feedback. 237It uses the same parameters as 238.Fn BF_cfb64_encrypt , 239which must be initialized the same way. 240.Pp 241.Fn BF_encrypt 242and 243.Fn BF_decrypt 244are the lowest level functions for Blowfish encryption. 245They encrypt/decrypt the first 64 bits of the vector pointed by 246.Fa data , 247using the key 248.Fa key . 249These functions should not be used unless implementing `modes' of Blowfish. 250The alternative is to use 251.Fn BF_ecb_encrypt . 252Be aware that these functions take each 32-bit chunk in host-byte order, 253which is little-endian on little-endian platforms 254and big-endian on big-endian ones. 255.Sh SEE ALSO 256.Xr EVP_EncryptInit 3 257.Sh HISTORY 258.Fn BF_set_key , 259.Fn BF_encrypt , 260.Fn BF_ecb_encrypt , 261.Fn BF_cbc_encrypt , 262.Fn BF_cfb64_encrypt , 263and 264.Fn BF_ofb64_encrypt 265first appeared in SSLeay 0.6.6. 266.Fn BF_decrypt 267first appeared in SSLeay 0.9.0. 268All these functions have been available since 269.Ox 2.4 . 270