1.\" $OpenBSD: RC2_encrypt.3,v 1.2 2024/12/18 04:15:48 jsg Exp $ 2.\" 3.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: December 18 2024 $ 18.Dt RC2_ENCRYPT 3 19.Os 20.Sh NAME 21.Nm RC2_set_key , 22.Nm RC2_encrypt , 23.Nm RC2_decrypt , 24.Nm RC2_cbc_encrypt , 25.Nm RC2_ecb_encrypt , 26.Nm RC2_cfb64_encrypt , 27.Nm RC2_ofb64_encrypt 28.Nd low-level functions for Rivest Cipher 2 29.Sh SYNOPSIS 30.In openssl/rc2.h 31.Ft void 32.Fo RC2_set_key 33.Fa "RC2_KEY *expanded_key" 34.Fa "int len" 35.Fa "const unsigned char *user_key" 36.Fa "int effective_bits" 37.Fc 38.Ft void 39.Fo RC2_encrypt 40.Fa "unsigned long *data" 41.Fa "RC2_KEY *expanded_key" 42.Fc 43.Ft void 44.Fo RC2_decrypt 45.Fa "unsigned long *data" 46.Fa "RC2_KEY *expanded_key" 47.Fc 48.Ft void 49.Fo RC2_cbc_encrypt 50.Fa "const unsigned char *in" 51.Fa "unsigned char *out" 52.Fa "long length" 53.Fa "RC2_KEY *expanded_key" 54.Fa "unsigned char *iv" 55.Fa "int encrypt" 56.Fc 57.Ft void 58.Fo RC2_ecb_encrypt 59.Fa "const unsigned char *in" 60.Fa "unsigned char *out" 61.Fa "RC2_KEY *expanded_key" 62.Fa "int encrypt" 63.Fc 64.Ft void 65.Fo RC2_cfb64_encrypt 66.Fa "const unsigned char *in" 67.Fa "unsigned char *out" 68.Fa "long length" 69.Fa "RC2_KEY *expanded_key" 70.Fa "unsigned char *iv" 71.Fa "int *num" 72.Fa "int encrypt" 73.Fc 74.Ft void 75.Fo RC2_ofb64_encrypt 76.Fa "const unsigned char *in" 77.Fa "unsigned char *out" 78.Fa "long length" 79.Fa "RC2_KEY *expanded_key" 80.Fa "unsigned char *iv" 81.Fa "int *num" 82.Fc 83.Sh DESCRIPTION 84RC2 is a block cipher operating on blocks of 85.Dv RC2_BLOCK No = 8 86bytes, equivalent to 64 bits, using a variable key length 87with an additional parameter called 88.Dq effective key bits 89or 90.Dq effective key length . 91The maximum effective key length is 1024 bits. 92.Pp 93If using RC2 cannot be avoided, it is recommended that application 94programs use the 95.Xr EVP_rc2_cbc 3 96family of functions instead of the functions documented in the present 97manual page, to ease later migration to less outdated encryption algorithms. 98.Pp 99.Fn RC2_set_key 100expands the first 101.Fa len 102bytes of 103.Fa user_key 104into the 105.Vt RC2_KEY 106structure 107.Pf * Fa expanded_key . 108The storage for the expanded key has to be provided by the calling code. 109If the 110.Fa len 111argument exceeds 128, only the first 128 bytes are used. 112.Pp 113Optionally, if the 114.Fa effective_bits 115argument is positive and less than 1024, the effective key length of 116.Pf * Fa expanded_key 117is reduced to 118.Fa effective_bits . 119Reducing the effective key length is not cryptographically useful. 120This option was originally designed to conform to US export regulations 121valid at the time, which were designed to allow the US government 122to spy on foreign encrypted communications. 123Unless interoperability requires otherwise, setting 124.Fa effective_bits 125to 1024 is recommended. 126.Pp 127.Fn RC2_encrypt 128and 129.Fn RC2_decrypt 130interpret 131.Fa data 132as an array of two 32 bit integers and encrypt or decrypt 133that single block in place, respectively, using the 134.Fa expanded_key . 135.Pp 136The remaining functions encode or decode 137.Fa length 138bytes starting at 139.Fa in 140to 141.Fa length 142bytes starting at 143.Fa out 144in various modes of operation using the 145.Fa expanded_key . 146Both arrays need to be long enough to hold 147.Fa length 148bytes rounded up to the next multiple of 8. 149The 150.Fa iv 151argument points to an array of 8 bytes used as the initialization vector. 152If the 153.Fa encrypt 154argument is 155.Dv RC2_ENCRYPT 156or another non-zero value, encryption is performed; 157if it is 158.Dv RC2_DECRYPT No = 0 , 159decryption is performed. 160.Pp 161.Fn RC2_cbc_encrypt 162operates in cipher block chaining mode. 163.Pp 164.Fn RC2_ecb_encrypt 165encodes or decodes eight bytes at 166.Fa in 167to 168eight bytes at 169.Fa out 170in electronic codebook mode. 171.Pp 172.Fn RC2_cfb64_encrypt 173and 174.Fn RC2_ofb64_encrypt 175operate in cipher feedback mode and output feedback mode, respectively, 176with 64 bit blocks. 177The number of bytes used from the last 8 byte block is kept track of in 178.Pf * Fa num . 179.Sh SEE ALSO 180.Xr crypto 3 , 181.Xr EVP_EncryptInit 3 , 182.Xr EVP_rc2_cbc 3 183.Sh HISTORY 184.Fn RC2_set_key , 185.Fn RC2_encrypt , 186.Fn RC2_cbc_encrypt , 187.Fn RC2_ecb_encrypt , 188.Fn RC2_cfb64_encrypt , 189and 190.Fn RC2_ofb64_encrypt 191first appeared in SSLeay 0.5.2. 192.Fn RC2_decrypt 193first appeared in SSLeay 0.9.0. 194All these functions have been available since 195.Ox 2.4 . 196