1.\" $OpenBSD: AES_encrypt.3,v 1.1 2019/08/28 10:37:42 schwarze Exp $ 2.\" 3.\" Copyright (c) 2019 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: August 28 2019 $ 18.Dt AES_ENCRYPT 3 19.Os 20.Sh NAME 21.Nm AES_set_encrypt_key , 22.Nm AES_set_decrypt_key , 23.Nm AES_encrypt , 24.Nm AES_decrypt , 25.Nm AES_cbc_encrypt 26.Nd low-level interface to the AES symmetric cipher 27.Sh SYNOPSIS 28.In openssl/aes.h 29.Ft int 30.Fo AES_set_encrypt_key 31.Fa "const unsigned char *userKey" 32.Fa "const int bits" 33.Fa "AES_KEY *key" 34.Fc 35.Ft int 36.Fo AES_set_decrypt_key 37.Fa "const unsigned char *userKey" 38.Fa "const int bits" 39.Fa "AES_KEY *key" 40.Fc 41.Ft void 42.Fo AES_encrypt 43.Fa "const unsigned char *in" 44.Fa "unsigned char *out" 45.Fa "const AES_KEY *key" 46.Fc 47.Ft void 48.Fo AES_decrypt 49.Fa "const unsigned char *in" 50.Fa "unsigned char *out" 51.Fa "const AES_KEY *key" 52.Fc 53.Ft void 54.Fo AES_cbc_encrypt 55.Fa "const unsigned char *in" 56.Fa "unsigned char *out" 57.Fa "size_t length" 58.Fa "const AES_KEY *key" 59.Fa "unsigned char *ivec" 60.Fa "const int enc" 61.Fc 62.Sh DESCRIPTION 63These function provide a low-level interface to the AES symmetric 64cipher algorithm, also called Rijndael. 65For reasons of flexibility, it is recommended that application 66programs use the high-level interface described in 67.Xr EVP_EncryptInit 3 68and 69.Xr EVP_aes_128_cbc 3 70instead whenever possible. 71.Pp 72.Vt AES_KEY 73is a structure that can hold up to 60 74.Vt int 75values and a number of rounds. 76.Pp 77.Fn AES_set_encrypt_key 78expands the 79.Fa userKey , 80which is 81.Fa bits 82long, into the 83.Fa key 84structure to prepare for encryption. 85The number of bits and bytes read from 86.Fa userKey , 87the number of 88.Vt int 89values stored into 90.Fa key , 91and the number of rounds are as follows: 92.Pp 93.Bl -column bits bytes ints rounds -offset indent -compact 94.It bits Ta bytes Ta ints Ta rounds 95.It 128 Ta 16 Ta 44 Ta 10 96.It 192 Ta 24 Ta 52 Ta 12 97.It 256 Ta 32 Ta 60 Ta 14 98.El 99.Pp 100.Fn AES_set_decrypt_key 101does the same, but in preparation for decryption. 102.Pp 103.Fn AES_encrypt 104reads a single 16 byte block from 105.Pf * Fa in , 106encrypts it with the 107.Fa key , 108and writes the 16 resulting bytes to 109.Pf * Fa out . 110The 16 byte buffers starting at 111.Fa in 112and 113.Fa out 114can overlap, and 115.Fa in 116and 117.Fa out 118can even point to the same memory location. 119.Pp 120.Fn AES_decrypt 121decrypts a single block and is otherwise identical to 122.Fn AES_encrypt . 123.Pp 124If 125.Fa enc 126is non-zero, 127.Fn AES_cbc_encrypt 128encrypts 129.Fa len 130bytes at 131.Fa in 132to 133.Fa out 134using the 128 bit 135.Fa key 136and the 128 bit 137initialization vector 138.Fa ivec 139in CBC mode. 140If 141.Fa enc 142is 0, 143.Fn AES_cbc_encrypt 144performs the corresponding decryption. 145.Sh RETURN VALUES 146.Fn AES_set_encrypt_key 147and 148.Fn AES_set_decrypt_key 149return 0 for success, -1 if 150.Fa userKey 151or 152.Fa key 153is 154.Dv NULL , 155or -2 if the number of 156.Fa bits 157is unsupported. 158.Sh SEE ALSO 159.Xr crypto 3 , 160.Xr EVP_aes_128_cbc 3 , 161.Xr EVP_EncryptInit 3 162.Sh STANDARDS 163ISO/IEC 18033-3:2010 164Information technology \(em Security techniques \(em 165Encryption algorithms \(em Part 3: Block ciphers 166.Sh HISTORY 167These functions first appeared in OpenSSL 0.9.7 168and have been available since 169.Ox 3.2 . 170.Sh AUTHORS 171.An Vincent Rijmen 172.An Antoon Bosselaers 173.An Paulo Barreto 174