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