1 /* 2 * QEMU Crypto cipher algorithms 3 * 4 * Copyright (c) 2015 Red Hat, Inc. 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, see <http://www.gnu.org/licenses/>. 18 * 19 */ 20 21 #ifndef QCRYPTO_CIPHER_H 22 #define QCRYPTO_CIPHER_H 23 24 #include "qapi-types.h" 25 26 typedef struct QCryptoCipher QCryptoCipher; 27 28 /* See also "QCryptoCipherAlgorithm" and "QCryptoCipherMode" 29 * enums defined in qapi/crypto.json */ 30 31 /** 32 * QCryptoCipher: 33 * 34 * The QCryptoCipher object provides a way to perform encryption 35 * and decryption of data, with a standard API, regardless of the 36 * algorithm used. It further isolates the calling code from the 37 * details of the specific underlying implementation, whether 38 * built-in, libgcrypt or nettle. 39 * 40 * Each QCryptoCipher object is capable of performing both 41 * encryption and decryption, and can operate in a number 42 * or modes including ECB, CBC. 43 * 44 * <example> 45 * <title>Encrypting data with AES-128 in CBC mode</title> 46 * <programlisting> 47 * QCryptoCipher *cipher; 48 * uint8_t key = ....; 49 * size_t keylen = 16; 50 * uint8_t iv = ....; 51 * 52 * if (!qcrypto_cipher_supports(QCRYPTO_CIPHER_ALG_AES_128)) { 53 * error_report(errp, "Feature <blah> requires AES cipher support"); 54 * return -1; 55 * } 56 * 57 * cipher = qcrypto_cipher_new(QCRYPTO_CIPHER_ALG_AES_128, 58 * QCRYPTO_CIPHER_MODE_CBC, 59 * key, keylen, 60 * errp); 61 * if (!cipher) { 62 * return -1; 63 * } 64 * 65 * if (qcrypto_cipher_set_iv(cipher, iv, keylen, errp) < 0) { 66 * return -1; 67 * } 68 * 69 * if (qcrypto_cipher_encrypt(cipher, rawdata, encdata, datalen, errp) < 0) { 70 * return -1; 71 * } 72 * 73 * qcrypto_cipher_free(cipher); 74 * </programlisting> 75 * </example> 76 * 77 */ 78 79 struct QCryptoCipher { 80 QCryptoCipherAlgorithm alg; 81 QCryptoCipherMode mode; 82 void *opaque; 83 }; 84 85 /** 86 * qcrypto_cipher_supports: 87 * @alg: the cipher algorithm 88 * @mode: the cipher mode 89 * 90 * Determine if @alg cipher algorithm in @mode is supported by the 91 * current configured build 92 * 93 * Returns: true if the algorithm is supported, false otherwise 94 */ 95 bool qcrypto_cipher_supports(QCryptoCipherAlgorithm alg, 96 QCryptoCipherMode mode); 97 98 /** 99 * qcrypto_cipher_get_block_len: 100 * @alg: the cipher algorithm 101 * 102 * Get the required data block size in bytes. When 103 * encrypting data, it must be a multiple of the 104 * block size. 105 * 106 * Returns: the block size in bytes 107 */ 108 size_t qcrypto_cipher_get_block_len(QCryptoCipherAlgorithm alg); 109 110 111 /** 112 * qcrypto_cipher_get_key_len: 113 * @alg: the cipher algorithm 114 * 115 * Get the required key size in bytes. 116 * 117 * Returns: the key size in bytes 118 */ 119 size_t qcrypto_cipher_get_key_len(QCryptoCipherAlgorithm alg); 120 121 122 /** 123 * qcrypto_cipher_get_iv_len: 124 * @alg: the cipher algorithm 125 * @mode: the cipher mode 126 * 127 * Get the required initialization vector size 128 * in bytes, if one is required. 129 * 130 * Returns: the IV size in bytes, or 0 if no IV is permitted 131 */ 132 size_t qcrypto_cipher_get_iv_len(QCryptoCipherAlgorithm alg, 133 QCryptoCipherMode mode); 134 135 136 /** 137 * qcrypto_cipher_new: 138 * @alg: the cipher algorithm 139 * @mode: the cipher usage mode 140 * @key: the private key bytes 141 * @nkey: the length of @key 142 * @errp: pointer to a NULL-initialized error object 143 * 144 * Creates a new cipher object for encrypting/decrypting 145 * data with the algorithm @alg in the usage mode @mode. 146 * 147 * The @key parameter provides the bytes representing 148 * the encryption/decryption key to use. The @nkey parameter 149 * specifies the length of @key in bytes. Each algorithm has 150 * one or more valid key lengths, and it is an error to provide 151 * a key of the incorrect length. 152 * 153 * The returned cipher object must be released with 154 * qcrypto_cipher_free() when no longer required 155 * 156 * Returns: a new cipher object, or NULL on error 157 */ 158 QCryptoCipher *qcrypto_cipher_new(QCryptoCipherAlgorithm alg, 159 QCryptoCipherMode mode, 160 const uint8_t *key, size_t nkey, 161 Error **errp); 162 163 /** 164 * qcrypto_cipher_free: 165 * @cipher: the cipher object 166 * 167 * Release the memory associated with @cipher that 168 * was previously allocated by qcrypto_cipher_new() 169 */ 170 void qcrypto_cipher_free(QCryptoCipher *cipher); 171 172 /** 173 * qcrypto_cipher_encrypt: 174 * @cipher: the cipher object 175 * @in: buffer holding the plain text input data 176 * @out: buffer to fill with the cipher text output data 177 * @len: the length of @in and @out buffers 178 * @errp: pointer to a NULL-initialized error object 179 * 180 * Encrypts the plain text stored in @in, filling 181 * @out with the resulting ciphered text. Both the 182 * @in and @out buffers must have the same size, 183 * given by @len. 184 * 185 * Returns: 0 on success, or -1 on error 186 */ 187 int qcrypto_cipher_encrypt(QCryptoCipher *cipher, 188 const void *in, 189 void *out, 190 size_t len, 191 Error **errp); 192 193 194 /** 195 * qcrypto_cipher_decrypt: 196 * @cipher: the cipher object 197 * @in: buffer holding the cipher text input data 198 * @out: buffer to fill with the plain text output data 199 * @len: the length of @in and @out buffers 200 * @errp: pointer to a NULL-initialized error object 201 * 202 * Decrypts the cipher text stored in @in, filling 203 * @out with the resulting plain text. Both the 204 * @in and @out buffers must have the same size, 205 * given by @len. 206 * 207 * Returns: 0 on success, or -1 on error 208 */ 209 int qcrypto_cipher_decrypt(QCryptoCipher *cipher, 210 const void *in, 211 void *out, 212 size_t len, 213 Error **errp); 214 215 /** 216 * qcrypto_cipher_setiv: 217 * @cipher: the cipher object 218 * @iv: the initialization vector or counter (CTR mode) bytes 219 * @niv: the length of @iv 220 * @errpr: pointer to a NULL-initialized error object 221 * 222 * If the @cipher object is setup to use a mode that requires 223 * initialization vectors or counter, this sets the @niv 224 * bytes. The @iv data should have the same length as the 225 * cipher key used when originally constructing the cipher 226 * object. It is an error to set an initialization vector 227 * or counter if the cipher mode does not require one. 228 * 229 * Returns: 0 on success, -1 on error 230 */ 231 int qcrypto_cipher_setiv(QCryptoCipher *cipher, 232 const uint8_t *iv, size_t niv, 233 Error **errp); 234 235 #endif /* QCRYPTO_CIPHER_H */ 236