xref: /openbmc/qemu/include/crypto/cipher.h (revision b5a1b443)
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 
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__ */
234