include/crypto/cipher.h

   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.1 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/qapi-types-crypto.h"
  25
  26 typedef struct QCryptoCipher QCryptoCipher;
  27 typedef struct QCryptoCipherDriver QCryptoCipherDriver;
  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     const QCryptoCipherDriver *driver;
  85 };
  86
  87 /**
  88  * qcrypto_cipher_supports:
  89  * @alg: the cipher algorithm
  90  * @mode: the cipher mode
  91  *
  92  * Determine if @alg cipher algorithm in @mode is supported by the
  93  * current configured build
  94  *
  95  * Returns: true if the algorithm is supported, false otherwise
  96  */
  97 bool qcrypto_cipher_supports(QCryptoCipherAlgorithm alg,
  98                              QCryptoCipherMode mode);
  99
 100 /**
 101  * qcrypto_cipher_get_block_len:
 102  * @alg: the cipher algorithm
 103  *
 104  * Get the required data block size in bytes. When
 105  * encrypting data, it must be a multiple of the
 106  * block size.
 107  *
 108  * Returns: the block size in bytes
 109  */
 110 size_t qcrypto_cipher_get_block_len(QCryptoCipherAlgorithm alg);
 111
 112
 113 /**
 114  * qcrypto_cipher_get_key_len:
 115  * @alg: the cipher algorithm
 116  *
 117  * Get the required key size in bytes.
 118  *
 119  * Returns: the key size in bytes
 120  */
 121 size_t qcrypto_cipher_get_key_len(QCryptoCipherAlgorithm alg);
 122
 123
 124 /**
 125  * qcrypto_cipher_get_iv_len:
 126  * @alg: the cipher algorithm
 127  * @mode: the cipher mode
 128  *
 129  * Get the required initialization vector size
 130  * in bytes, if one is required.
 131  *
 132  * Returns: the IV size in bytes, or 0 if no IV is permitted
 133  */
 134 size_t qcrypto_cipher_get_iv_len(QCryptoCipherAlgorithm alg,
 135                                  QCryptoCipherMode mode);
 136
 137
 138 /**
 139  * qcrypto_cipher_new:
 140  * @alg: the cipher algorithm
 141  * @mode: the cipher usage mode
 142  * @key: the private key bytes
 143  * @nkey: the length of @key
 144  * @errp: pointer to a NULL-initialized error object
 145  *
 146  * Creates a new cipher object for encrypting/decrypting
 147  * data with the algorithm @alg in the usage mode @mode.
 148  *
 149  * The @key parameter provides the bytes representing
 150  * the encryption/decryption key to use. The @nkey parameter
 151  * specifies the length of @key in bytes. Each algorithm has
 152  * one or more valid key lengths, and it is an error to provide
 153  * a key of the incorrect length.
 154  *
 155  * The returned cipher object must be released with
 156  * qcrypto_cipher_free() when no longer required
 157  *
 158  * Returns: a new cipher object, or NULL on error
 159  */
 160 QCryptoCipher *qcrypto_cipher_new(QCryptoCipherAlgorithm alg,
 161                                   QCryptoCipherMode mode,
 162                                   const uint8_t *key, size_t nkey,
 163                                   Error **errp);
 164
 165 /**
 166  * qcrypto_cipher_free:
 167  * @cipher: the cipher object
 168  *
 169  * Release the memory associated with @cipher that
 170  * was previously allocated by qcrypto_cipher_new()
 171  */
 172 void qcrypto_cipher_free(QCryptoCipher *cipher);
 173
 174 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoCipher, qcrypto_cipher_free)
 175
 176 /**
 177  * qcrypto_cipher_encrypt:
 178  * @cipher: the cipher object
 179  * @in: buffer holding the plain text input data
 180  * @out: buffer to fill with the cipher text output data
 181  * @len: the length of @in and @out buffers
 182  * @errp: pointer to a NULL-initialized error object
 183  *
 184  * Encrypts the plain text stored in @in, filling
 185  * @out with the resulting ciphered text. Both the
 186  * @in and @out buffers must have the same size,
 187  * given by @len.
 188  *
 189  * Returns: 0 on success, or -1 on error
 190  */
 191 int qcrypto_cipher_encrypt(QCryptoCipher *cipher,
 192                            const void *in,
 193                            void *out,
 194                            size_t len,
 195                            Error **errp);
 196
 197
 198 /**
 199  * qcrypto_cipher_decrypt:
 200  * @cipher: the cipher object
 201  * @in: buffer holding the cipher text input data
 202  * @out: buffer to fill with the plain text output data
 203  * @len: the length of @in and @out buffers
 204  * @errp: pointer to a NULL-initialized error object
 205  *
 206  * Decrypts the cipher text stored in @in, filling
 207  * @out with the resulting plain text. Both the
 208  * @in and @out buffers must have the same size,
 209  * given by @len.
 210  *
 211  * Returns: 0 on success, or -1 on error
 212  */
 213 int qcrypto_cipher_decrypt(QCryptoCipher *cipher,
 214                            const void *in,
 215                            void *out,
 216                            size_t len,
 217                            Error **errp);
 218
 219 /**
 220  * qcrypto_cipher_setiv:
 221  * @cipher: the cipher object
 222  * @iv: the initialization vector or counter (CTR mode) bytes
 223  * @niv: the length of @iv
 224  * @errpr: pointer to a NULL-initialized error object
 225  *
 226  * If the @cipher object is setup to use a mode that requires
 227  * initialization vectors or counter, this sets the @niv
 228  * bytes. The @iv data should have the same length as the
 229  * cipher key used when originally constructing the cipher
 230  * object. It is an error to set an initialization vector
 231  * or counter if the cipher mode does not require one.
 232  *
 233  * Returns: 0 on success, -1 on error
 234  */
 235 int qcrypto_cipher_setiv(QCryptoCipher *cipher,
 236                          const uint8_t *iv, size_t niv,
 237                          Error **errp);
 238
 239 #endif /* QCRYPTO_CIPHER_H */