Add ENET device to i.MX6 SOC.
[qemu.git] / 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__ */