1.\" $OpenBSD: BF_set_key.3,v 1.10 2019/06/06 01:06:58 schwarze 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: June 6 2019 $ 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.Nm BF_options 64.Nd Blowfish encryption 65.Sh SYNOPSIS 66.In openssl/blowfish.h 67.Ft void 68.Fo BF_set_key 69.Fa "BF_KEY *key" 70.Fa "int len" 71.Fa "const unsigned char *data" 72.Fc 73.Ft void 74.Fo BF_encrypt 75.Fa "BF_LONG *data" 76.Fa "const BF_KEY *key" 77.Fc 78.Ft void 79.Fo BF_decrypt 80.Fa "BF_LONG *data" 81.Fa "const BF_KEY *key" 82.Fc 83.Ft void 84.Fo BF_ecb_encrypt 85.Fa "const unsigned char *in" 86.Fa "unsigned char *out" 87.Fa "BF_KEY *key" 88.Fa "int enc" 89.Fc 90.Ft void 91.Fo BF_cbc_encrypt 92.Fa "const unsigned char *in" 93.Fa "unsigned char *out" 94.Fa "long length" 95.Fa "BF_KEY *schedule" 96.Fa "unsigned char *ivec" 97.Fa "int enc" 98.Fc 99.Ft void 100.Fo BF_cfb64_encrypt 101.Fa "const unsigned char *in" 102.Fa "unsigned char *out" 103.Fa "long length" 104.Fa "BF_KEY *schedule" 105.Fa "unsigned char *ivec" 106.Fa "int *num" 107.Fa "int enc" 108.Fc 109.Ft void 110.Fo BF_ofb64_encrypt 111.Fa "const unsigned char *in" 112.Fa "unsigned char *out" 113.Fa "long length" 114.Fa "BF_KEY *schedule" 115.Fa "unsigned char *ivec" 116.Fa "int *num" 117.Fc 118.Ft const char * 119.Fo BF_options 120.Fa void 121.Fc 122.Sh DESCRIPTION 123This library implements the Blowfish cipher, 124which was invented and defined by 125.An Counterpane . 126Note that applications should use higher level functions such as 127.Xr EVP_EncryptInit 3 128instead of calling the Blowfish functions directly. 129.Pp 130Blowfish is a block cipher that operates on 64-bit (8 byte) blocks of data. 131It uses a variable size key, but typically, 128-bit (16 byte) keys 132are considered good for strong encryption. 133Blowfish can be used in the same modes as DES 134and is currently one of the faster block ciphers. 135It is quite a bit faster than DES, and much faster than IDEA or RC2. 136.Pp 137Blowfish consists of a key setup phase 138and the actual encryption or decryption phase. 139.Pp 140.Fn BF_set_key 141sets up the 142.Vt BF_KEY 143.Fa key 144using the 145.Fa len 146bytes long key at 147.Fa data . 148.Pp 149.Fn BF_ecb_encrypt 150is the basic Blowfish encryption and decryption function. 151It encrypts or decrypts the first 64 bits of 152.Fa in 153using the key 154.Fa key , 155putting the result in 156.Fa out . 157.Fa enc 158decides if encryption 159.Pq Dv BF_ENCRYPT 160or decryption 161.Pq Dv BF_DECRYPT 162shall be performed. 163The vector pointed at by 164.Fa in 165and 166.Fa out 167must be 64 bits in length, no less. 168If they are larger, everything after the first 64 bits is ignored. 169.Pp 170The mode functions 171.Fn BF_cbc_encrypt , 172.Fn BF_cfb64_encrypt , 173and 174.Fn BF_ofb64_encrypt 175all operate on variable length data. 176They all take an initialization vector 177.Fa ivec 178which needs to be passed along into the next call of the same function 179for the same message. 180.Fa ivec 181may be initialized with anything, but the recipient needs to know what 182it was initialized with, or it won't be able to decrypt. 183Some programs and protocols simplify this, like SSH, where 184.Fa ivec 185is simply initialized to zero. 186.Fn BF_cbc_encrypt 187operates on data that is a multiple of 8 bytes long, while 188.Fn BF_cfb64_encrypt 189and 190.Fn BF_ofb64_encrypt 191are used to encrypt a variable number of bytes (the amount 192does not have to be an exact multiple of 8). 193The purpose of the latter two is to simulate stream ciphers and, 194therefore, they need the parameter 195.Fa num , 196which is a pointer to an integer where the current offset in 197.Fa ivec 198is stored between calls. 199This integer must be initialized to zero when 200.Fa ivec 201is initialized. 202.Pp 203.Fn BF_cbc_encrypt 204is the Cipher Block Chaining function for Blowfish. 205It encrypts or decrypts the 64-bit chunks of 206.Fa in 207using the key 208.Fa schedule , 209putting the result in 210.Fa out . 211.Fa enc 212decides if encryption 213.Pq Dv BF_ENCRYPT 214or decryption 215.Pq Dv BF_DECRYPT 216shall be performed. 217.Fa ivec 218must point at an 8-byte long initialization vector. 219.Pp 220.Fn BF_cfb64_encrypt 221is the CFB mode for Blowfish with 64-bit feedback. 222It encrypts or decrypts the bytes in 223.Fa in 224using the key 225.Fa schedule , 226putting the result in 227.Fa out . 228.Fa enc 229decides if encryption 230.Pq Dv BF_ENCRYPT 231or decryption 232.Pq Dv BF_DECRYPT 233shall be performed. 234.Fa ivec 235must point at an 2368-byte long initialization vector. 237.Fa num 238must point at an integer which must be initially zero. 239.Pp 240.Fn BF_ofb64_encrypt 241is the OFB mode for Blowfish with 64-bit feedback. 242It uses the same parameters as 243.Fn BF_cfb64_encrypt , 244which must be initialized the same way. 245.Pp 246.Fn BF_encrypt 247and 248.Fn BF_decrypt 249are the lowest level functions for Blowfish encryption. 250They encrypt/decrypt the first 64 bits of the vector pointed by 251.Fa data , 252using the key 253.Fa key . 254These functions should not be used unless implementing `modes' of Blowfish. 255The alternative is to use 256.Fn BF_ecb_encrypt . 257Be aware that these functions take each 32-bit chunk in host-byte order, 258which is little-endian on little-endian platforms 259and big-endian on big-endian ones. 260.Sh SEE ALSO 261.Xr EVP_EncryptInit 3 262.Sh HISTORY 263.Fn BF_set_key , 264.Fn BF_encrypt , 265.Fn BF_ecb_encrypt , 266.Fn BF_cbc_encrypt , 267.Fn BF_cfb64_encrypt , 268.Fn BF_ofb64_encrypt , 269and 270.Fn BF_options 271first appeared in SSLeay 0.6.6. 272.Fn BF_decrypt 273first appeared in SSLeay 0.9.0. 274All these functions have been available since 275.Ox 2.4 . 276