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 "qemu-common.h" 25 #include "qapi/error.h" 26 27 typedef struct QCryptoCipher QCryptoCipher; 28 29 /* See also "QCryptoCipherAlgorithm" and "QCryptoCipherMode" 30 * enums defined in qapi/crypto.json */ 31 32 /** 33 * QCryptoCipher: 34 * 35 * The QCryptoCipher object provides a way to perform encryption 36 * and decryption of data, with a standard API, regardless of the 37 * algorithm used. It further isolates the calling code from the 38 * details of the specific underlying implementation, whether 39 * built-in, libgcrypt or nettle. 40 * 41 * Each QCryptoCipher object is capable of performing both 42 * encryption and decryption, and can operate in a number 43 * or modes including ECB, CBC. 44 * 45 * <example> 46 * <title>Encrypting data with AES-128 in CBC mode</title> 47 * <programlisting> 48 * QCryptoCipher *cipher; 49 * uint8_t key = ....; 50 * size_t keylen = 16; 51 * uint8_t iv = ....; 52 * 53 * if (!qcrypto_cipher_supports(QCRYPTO_CIPHER_ALG_AES_128)) { 54 * error_report(errp, "Feature <blah> requires AES cipher support"); 55 * return -1; 56 * } 57 * 58 * cipher = qcrypto_cipher_new(QCRYPTO_CIPHER_ALG_AES_128, 59 * QCRYPTO_CIPHER_MODE_CBC, 60 * key, keylen, 61 * errp); 62 * if (!cipher) { 63 * return -1; 64 * } 65 * 66 * if (qcrypto_cipher_set_iv(cipher, iv, keylen, errp) < 0) { 67 * return -1; 68 * } 69 * 70 * if (qcrypto_cipher_encrypt(cipher, rawdata, encdata, datalen, errp) < 0) { 71 * return -1; 72 * } 73 * 74 * qcrypto_cipher_free(cipher); 75 * </programlisting> 76 * </example> 77 * 78 */ 79 80 struct QCryptoCipher { 81 QCryptoCipherAlgorithm alg; 82 QCryptoCipherMode mode; 83 void *opaque; 84 }; 85 86 /** 87 * qcrypto_cipher_supports: 88 * @alg: the cipher algorithm 89 * 90 * Determine if @alg cipher algorithm 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 97 /** 98 * qcrypto_cipher_get_block_len: 99 * @alg: the cipher algorithm 100 * 101 * Get the required data block size in bytes. When 102 * encrypting data, it must be a multiple of the 103 * block size. 104 * 105 * Returns: the block size in bytes 106 */ 107 size_t qcrypto_cipher_get_block_len(QCryptoCipherAlgorithm alg); 108 109 110 /** 111 * qcrypto_cipher_get_key_len: 112 * @alg: the cipher algorithm 113 * 114 * Get the required key size in bytes. 115 * 116 * Returns: the key size in bytes 117 */ 118 size_t qcrypto_cipher_get_key_len(QCryptoCipherAlgorithm alg); 119 120 121 /** 122 * qcrypto_cipher_get_iv_len: 123 * @alg: the cipher algorithm 124 * @mode: the cipher mode 125 * 126 * Get the required initialization vector size 127 * in bytes, if one is required. 128 * 129 * Returns: the IV size in bytes, or 0 if no IV is permitted 130 */ 131 size_t qcrypto_cipher_get_iv_len(QCryptoCipherAlgorithm alg, 132 QCryptoCipherMode mode); 133 134 135 /** 136 * qcrypto_cipher_new: 137 * @alg: the cipher algorithm 138 * @mode: the cipher usage mode 139 * @key: the private key bytes 140 * @nkey: the length of @key 141 * @errp: pointer to a NULL-initialized error object 142 * 143 * Creates a new cipher object for encrypting/decrypting 144 * data with the algorithm @alg in the usage mode @mode. 145 * 146 * The @key parameter provides the bytes representing 147 * the encryption/decryption key to use. The @nkey parameter 148 * specifies the length of @key in bytes. Each algorithm has 149 * one or more valid key lengths, and it is an error to provide 150 * a key of the incorrect length. 151 * 152 * The returned cipher object must be released with 153 * qcrypto_cipher_free() when no longer required 154 * 155 * Returns: a new cipher object, or NULL on error 156 */ 157 QCryptoCipher *qcrypto_cipher_new(QCryptoCipherAlgorithm alg, 158 QCryptoCipherMode mode, 159 const uint8_t *key, size_t nkey, 160 Error **errp); 161 162 /** 163 * qcrypto_cipher_free: 164 * @cipher: the cipher object 165 * 166 * Release the memory associated with @cipher that 167 * was previously allocated by qcrypto_cipher_new() 168 */ 169 void qcrypto_cipher_free(QCryptoCipher *cipher); 170 171 /** 172 * qcrypto_cipher_encrypt: 173 * @cipher: the cipher object 174 * @in: buffer holding the plain text input data 175 * @out: buffer to fill with the cipher text output data 176 * @len: the length of @in and @out buffers 177 * @errp: pointer to a NULL-initialized error object 178 * 179 * Encrypts the plain text stored in @in, filling 180 * @out with the resulting ciphered text. Both the 181 * @in and @out buffers must have the same size, 182 * given by @len. 183 * 184 * Returns: 0 on success, or -1 on error 185 */ 186 int qcrypto_cipher_encrypt(QCryptoCipher *cipher, 187 const void *in, 188 void *out, 189 size_t len, 190 Error **errp); 191 192 193 /** 194 * qcrypto_cipher_decrypt: 195 * @cipher: the cipher object 196 * @in: buffer holding the cipher text input data 197 * @out: buffer to fill with the plain text output data 198 * @len: the length of @in and @out buffers 199 * @errp: pointer to a NULL-initialized error object 200 * 201 * Decrypts the cipher text stored in @in, filling 202 * @out with the resulting plain text. Both the 203 * @in and @out buffers must have the same size, 204 * given by @len. 205 * 206 * Returns: 0 on success, or -1 on error 207 */ 208 int qcrypto_cipher_decrypt(QCryptoCipher *cipher, 209 const void *in, 210 void *out, 211 size_t len, 212 Error **errp); 213 214 /** 215 * qcrypto_cipher_setiv: 216 * @cipher: the cipher object 217 * @iv: the initialization vector bytes 218 * @niv: the length of @iv 219 * @errpr: pointer to a NULL-initialized error object 220 * 221 * If the @cipher object is setup to use a mode that requires 222 * initialization vectors, this sets the initialization vector 223 * bytes. The @iv data should have the same length as the 224 * cipher key used when originally constructing the cipher 225 * object. It is an error to set an initialization vector 226 * if the cipher mode does not require one. 227 * 228 * Returns: 0 on success, -1 on error 229 */ 230 int qcrypto_cipher_setiv(QCryptoCipher *cipher, 231 const uint8_t *iv, size_t niv, 232 Error **errp); 233 234 #endif /* QCRYPTO_CIPHER_H__ */ 235