Apache Portable Runtime
apr_crypto_internal.h
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef APR_CRYPTO_INTERNAL_H
18 #define APR_CRYPTO_INTERNAL_H
19 
20 #include <stdarg.h>
21 
22 #include "apr_crypto.h"
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 #if APU_HAVE_CRYPTO
29 
30 /**
31  * Structure representing the streaming context for the CPRNG.
32  */
33 typedef struct cprng_stream_ctx_t cprng_stream_ctx_t;
34 
35 /**
36  * Key size for the CPRNG.
37  */
38 #define CPRNG_KEY_SIZE 32
39 
40 struct apr_crypto_driver_t {
41 
42  /** name */
43  const char *name;
44 
45  /**
46  * @brief: allow driver to perform once-only initialisation.
47  * Called once only.
48  * @param pool The pool to register the cleanup in.
49  * @param params Optional init parameter string.
50  * @param rc Driver-specific additional error code
51  */
52  apr_status_t (*init)(apr_pool_t *pool, const char *params,
53  const apu_err_t **result);
54 
55  /**
56  * @brief Create a context for supporting encryption. Keys, certificates,
57  * algorithms and other parameters will be set per context. More than
58  * one context can be created at one time. A cleanup will be automatically
59  * registered with the given pool to guarantee a graceful shutdown.
60  * @param f - context pointer will be written here
61  * @param provider - provider to use
62  * @param params - array of key parameters
63  * @param pool - process pool
64  * @return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE
65  * if the engine cannot be initialised.
66  */
67  apr_status_t (*make)(apr_crypto_t **f, const apr_crypto_driver_t *provider,
68  const char *params, apr_pool_t *pool);
69 
70  /**
71  * @brief Get a hash table of key digests, keyed by the name of the digest against
72  * a pointer to apr_crypto_block_key_digest_t.
73  *
74  * @param digests - hashtable of key digests keyed to constants.
75  * @param f - encryption context
76  * @return APR_SUCCESS for success
77  */
78  apr_status_t (*get_block_key_digests)(apr_hash_t **types,
79  const apr_crypto_t *f);
80 
81  /**
82  * @brief Get a hash table of key types, keyed by the name of the type against
83  * a pointer to apr_crypto_block_key_type_t.
84  *
85  * @param types - hashtable of key types keyed to constants.
86  * @param f - encryption context
87  * @return APR_SUCCESS for success
88  */
89  apr_status_t (*get_block_key_types)(apr_hash_t **types,
90  const apr_crypto_t *f);
91 
92  /**
93  * @brief Get a hash table of key modes, keyed by the name of the mode against
94  * a pointer to apr_crypto_block_key_mode_t.
95  *
96  * @param modes - hashtable of key modes keyed to constants.
97  * @param f - encryption context
98  * @return APR_SUCCESS for success
99  */
100  apr_status_t (*get_block_key_modes)(apr_hash_t **modes,
101  const apr_crypto_t *f);
102 
103  /**
104  * @brief Create a key from the given passphrase. By default, the PBKDF2
105  * algorithm is used to generate the key from the passphrase. It is expected
106  * that the same pass phrase will generate the same key, regardless of the
107  * backend crypto platform used. The key is cleaned up when the context
108  * is cleaned, and may be reused with multiple encryption or decryption
109  * operations.
110  * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
111  * *key is not NULL, *key must point at a previously created structure.
112  * @param key The key returned, see note.
113  * @param ivSize The size of the initialisation vector will be returned, based
114  * on whether an IV is relevant for this type of crypto.
115  * @param pass The passphrase to use.
116  * @param passLen The passphrase length in bytes
117  * @param salt The salt to use.
118  * @param saltLen The salt length in bytes
119  * @param type 3DES_192, AES_128, AES_192, AES_256.
120  * @param mode Electronic Code Book / Cipher Block Chaining.
121  * @param doPad Pad if necessary.
122  * @param iterations Iteration count
123  * @param f The context to use.
124  * @param p The pool to use.
125  * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
126  * error occurred while generating the key. APR_ENOCIPHER if the type or mode
127  * is not supported by the particular backend. APR_EKEYTYPE if the key type is
128  * not known. APR_EPADDING if padding was requested but is not supported.
129  * APR_ENOTIMPL if not implemented.
130  */
131  apr_status_t (*passphrase)(apr_crypto_key_t **key, apr_size_t *ivSize,
132  const char *pass, apr_size_t passLen, const unsigned char * salt,
133  apr_size_t saltLen, const apr_crypto_block_key_type_e type,
134  const apr_crypto_block_key_mode_e mode, const int doPad,
135  const int iterations, const apr_crypto_t *f, apr_pool_t *p);
136 
137  /**
138  * @brief Initialise a context for encrypting arbitrary data using the given key.
139  * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
140  * *ctx is not NULL, *ctx must point at a previously created structure.
141  * @param ctx The block context returned, see note.
142  * @param iv Optional initialisation vector. If the buffer pointed to is NULL,
143  * an IV will be created at random, in space allocated from the pool.
144  * If the buffer pointed to is not NULL, the IV in the buffer will be
145  * used.
146  * @param key The key structure.
147  * @param blockSize The block size of the cipher.
148  * @param p The pool to use.
149  * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
150  * Returns APR_EINIT if the backend failed to initialise the context. Returns
151  * APR_ENOTIMPL if not implemented.
152  */
153  apr_status_t (*block_encrypt_init)(apr_crypto_block_t **ctx,
154  const unsigned char **iv, const apr_crypto_key_t *key,
155  apr_size_t *blockSize, apr_pool_t *p);
156 
157  /**
158  * @brief Encrypt data provided by in, write it to out.
159  * @note The number of bytes written will be written to outlen. If
160  * out is NULL, outlen will contain the maximum size of the
161  * buffer needed to hold the data, including any data
162  * generated by apr_crypto_block_encrypt_finish below. If *out points
163  * to NULL, a buffer sufficiently large will be created from
164  * the pool provided. If *out points to a not-NULL value, this
165  * value will be used as a buffer instead.
166  * @param out Address of a buffer to which data will be written,
167  * see note.
168  * @param outlen Length of the output will be written here.
169  * @param in Address of the buffer to read.
170  * @param inlen Length of the buffer to read.
171  * @param ctx The block context to use.
172  * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
173  * not implemented.
174  */
175  apr_status_t (*block_encrypt)(unsigned char **out, apr_size_t *outlen,
176  const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx);
177 
178  /**
179  * @brief Encrypt final data block, write it to out.
180  * @note If necessary the final block will be written out after being
181  * padded. Typically the final block will be written to the
182  * same buffer used by apr_crypto_block_encrypt, offset by the
183  * number of bytes returned as actually written by the
184  * apr_crypto_block_encrypt() call. After this call, the context
185  * is cleaned and can be reused by apr_crypto_block_encrypt_init().
186  * @param out Address of a buffer to which data will be written. This
187  * buffer must already exist, and is usually the same
188  * buffer used by apr_evp_crypt(). See note.
189  * @param outlen Length of the output will be written here.
190  * @param ctx The block context to use.
191  * @return APR_ECRYPT if an error occurred.
192  * @return APR_EPADDING if padding was enabled and the block was incorrectly
193  * formatted.
194  * @return APR_ENOTIMPL if not implemented.
195  */
196  apr_status_t (*block_encrypt_finish)(unsigned char *out,
197  apr_size_t *outlen, apr_crypto_block_t *ctx);
198 
199  /**
200  * @brief Initialise a context for decrypting arbitrary data using the given key.
201  * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
202  * *ctx is not NULL, *ctx must point at a previously created structure.
203  * @param ctx The block context returned, see note.
204  * @param blockSize The block size of the cipher.
205  * @param iv Optional initialisation vector. If the buffer pointed to is NULL,
206  * an IV will be created at random, in space allocated from the pool.
207  * If the buffer is not NULL, the IV in the buffer will be used.
208  * @param key The key structure.
209  * @param p The pool to use.
210  * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
211  * Returns APR_EINIT if the backend failed to initialise the context. Returns
212  * APR_ENOTIMPL if not implemented.
213  */
214  apr_status_t (*block_decrypt_init)(apr_crypto_block_t **ctx,
215  apr_size_t *blockSize, const unsigned char *iv,
216  const apr_crypto_key_t *key, apr_pool_t *p);
217 
218  /**
219  * @brief Decrypt data provided by in, write it to out.
220  * @note The number of bytes written will be written to outlen. If
221  * out is NULL, outlen will contain the maximum size of the
222  * buffer needed to hold the data, including any data
223  * generated by apr_crypto_block_decrypt_finish below. If *out points
224  * to NULL, a buffer sufficiently large will be created from
225  * the pool provided. If *out points to a not-NULL value, this
226  * value will be used as a buffer instead.
227  * @param out Address of a buffer to which data will be written,
228  * see note.
229  * @param outlen Length of the output will be written here.
230  * @param in Address of the buffer to read.
231  * @param inlen Length of the buffer to read.
232  * @param ctx The block context to use.
233  * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
234  * not implemented.
235  */
236  apr_status_t (*block_decrypt)(unsigned char **out, apr_size_t *outlen,
237  const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx);
238 
239  /**
240  * @brief Decrypt final data block, write it to out.
241  * @note If necessary the final block will be written out after being
242  * padded. Typically the final block will be written to the
243  * same buffer used by apr_crypto_block_decrypt, offset by the
244  * number of bytes returned as actually written by the
245  * apr_crypto_block_decrypt() call. After this call, the context
246  * is cleaned and can be reused by apr_crypto_block_decrypt_init().
247  * @param out Address of a buffer to which data will be written. This
248  * buffer must already exist, and is usually the same
249  * buffer used by apr_evp_crypt(). See note.
250  * @param outlen Length of the output will be written here.
251  * @param ctx The block context to use.
252  * @return APR_ECRYPT if an error occurred.
253  * @return APR_EPADDING if padding was enabled and the block was incorrectly
254  * formatted.
255  * @return APR_ENOTIMPL if not implemented.
256  */
257  apr_status_t (*block_decrypt_finish)(unsigned char *out,
258  apr_size_t *outlen, apr_crypto_block_t *ctx);
259 
260  /**
261  * @brief Initialise a context for signing or verifying arbitrary data using the
262  * given key.
263  * @note If *d is NULL, a apr_crypto_digest_t will be created from a pool. If
264  * *d is not NULL, *d must point at a previously created structure.
265  * @param d The digest context returned, see note.
266  * @param key The key structure to use.
267  * @param rec The digest record.
268  * @param p The pool to use.
269  * @return APR_ENOIV if an initialisation vector is required but not specified.
270  * @return APR_EINIT if the backend failed to initialise the context.
271  * @return APR_ENOTIMPL if not implemented.
272  * @return APR_ENOKEY if the key type does not support the given operation.
273  */
274  apr_status_t (*digest_init)(apr_crypto_digest_t **d,
276 
277  /**
278  * @brief Update the digest with data provided by in.
279  * @param in Address of the buffer to read.
280  * @param inlen Length of the buffer to read.
281  * @param digest The digest context to use.
282  * @return APR_ECRYPT if an error occurred.
283  * @return APR_ENOTIMPL if not implemented.
284  * @return APR_ENOKEY if the key type does not support the given operation.
285  */
286  apr_status_t (*digest_update)(apr_crypto_digest_t *digest,
287  const unsigned char *in, apr_size_t inlen);
288 
289  /**
290  * @brief Finalise the digest and write the result.
291  * @note After this call, the context is cleaned and can be reused by
292  * apr_crypto_digest_init().
293  * @param digest The digest context to use.
294  * @return APR_ECRYPT if an error occurred.
295  * @return APR_EPADDING if padding was enabled and the block was incorrectly
296  * formatted.
297  * @return APR_ENOTIMPL if not implemented.
298  * @return APR_ENOKEY if the key type does not support the given operation.
299  */
300  apr_status_t (*digest_final)(apr_crypto_digest_t *digest);
301 
302  /**
303  * @brief One shot digest on a single memory buffer.
304  * @param key The key structure to use.
305  * @param rec The digest record.
306  * @param in Address of the buffer to digest.
307  * @param inlen Length of the buffer to digest.
308  * @param p The pool to use.
309  * @return APR_ENOIV if an initialisation vector is required but not specified.
310  * @return APR_EINIT if the backend failed to initialise the context.
311  * @return APR_ENOTIMPL if not implemented.
312  * @return APR_ENOKEY if the key type does not support the given operation.
313  */
314  apr_status_t (*digest)(const apr_crypto_key_t *key,
315  apr_crypto_digest_rec_t *rec, const unsigned char *in,
316  apr_size_t inlen, apr_pool_t *p);
317 
318  /**
319  * @brief Clean encryption / decryption context.
320  * @note After cleanup, a context is free to be reused if necessary.
321  * @param ctx The block context to use.
322  * @return Returns APR_ENOTIMPL if not supported.
323  */
324  apr_status_t (*block_cleanup)(apr_crypto_block_t *ctx);
325 
326  /**
327  * @brief Clean sign / verify context.
328  * @note After cleanup, a context is free to be reused if necessary.
329  * @param ctx The digest context to use.
330  * @return Returns APR_ENOTIMPL if not supported.
331  */
332  apr_status_t (*digest_cleanup)(apr_crypto_digest_t *ctx);
333 
334  /**
335  * @brief Clean encryption / decryption context.
336  * @note After cleanup, a context is free to be reused if necessary.
337  * @param f The context to use.
338  * @return Returns APR_ENOTIMPL if not supported.
339  */
340  apr_status_t (*cleanup)(apr_crypto_t *f);
341 
342  /**
343  * @brief Clean encryption / decryption context.
344  * @note After cleanup, a context is free to be reused if necessary.
345  * @return Returns APR_ENOTIMPL if not supported.
346  */
347  apr_status_t (*shutdown)(void);
348 
349  /**
350  * @brief: fetch the most recent error from this driver.
351  * @param result - the result structure
352  * @param f - context pointer
353  * @return APR_SUCCESS for success.
354  */
355  apr_status_t (*error)(const apu_err_t **result, const apr_crypto_t *f);
356 
357  /**
358  * @brief Create a key from the provided secret or passphrase. The key is cleaned
359  * up when the context is cleaned, and may be reused with multiple encryption
360  * or decryption operations.
361  * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
362  * *key is not NULL, *key must point at a previously created structure.
363  * @param key The key returned, see note.
364  * @param rec The key record, from which the key will be derived.
365  * @param f The context to use.
366  * @param p The pool to use.
367  * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
368  * error occurred while generating the key. APR_ENOCIPHER if the type or mode
369  * is not supported by the particular backend. APR_EKEYTYPE if the key type is
370  * not known. APR_EPADDING if padding was requested but is not supported.
371  * APR_ENOTIMPL if not implemented.
372  */
373  apr_status_t (*key)(apr_crypto_key_t **key, const apr_crypto_key_rec_t *rec,
374  const apr_crypto_t *f, apr_pool_t *p);
375 
376  /**
377  * @brief Create the context for encrypting the CPRNG stream.
378  * @param pctx The pointer where the context will be returned.
379  * @param f The crypto context to use.
380  * @param cipher The cipher to use.
381  * @param pool The pool to use.
382  */
383  apr_status_t (*cprng_stream_ctx_make)(cprng_stream_ctx_t **pctx, apr_crypto_t *f,
384  apr_crypto_cipher_e cipher, apr_pool_t *pool);
385 
386  /**
387  * @brief Free the context for encrypting the CPRNG stream.
388  * @param ctx The context to free.
389  */
390  void (*cprng_stream_ctx_free)(cprng_stream_ctx_t *ctx);
391 
392  /**
393  * @brief Return further encrypted bytes, rekeying as necessary.
394  * @param pctx The context.
395  * @param key The key to use while rekeying.
396  * @param to Encrypted bytes are written here.
397  * @param n Length of encrypted bytes.
398  * @param z The IV to use.
399  */
400  apr_status_t (*cprng_stream_ctx_bytes)(cprng_stream_ctx_t **pctx, unsigned char *key,
401  unsigned char *to, apr_size_t n, const unsigned char *z);
402 
403 };
404 
405 #endif
406 
407 #ifdef __cplusplus
408 }
409 #endif
410 
411 #endif
APR-UTIL Crypto library.
struct apr_crypto_key_t apr_crypto_key_t
Definition: apr_crypto.h:197
struct apr_crypto_t apr_crypto_t
Definition: apr_crypto.h:183
struct apr_crypto_driver_t apr_crypto_driver_t
Definition: apr_crypto.h:176
apr_crypto_block_key_type_e
Definition: apr_crypto.h:116
struct apr_crypto_block_t apr_crypto_block_t
Definition: apr_crypto.h:206
struct apr_crypto_digest_t apr_crypto_digest_t
Definition: apr_crypto.h:213
apr_crypto_block_key_mode_e
Definition: apr_crypto.h:128
apr_crypto_cipher_e
Definition: apr_crypto.h:165
int apr_status_t
Definition: apr_errno.h:44
struct apr_hash_t apr_hash_t
Definition: apr_hash.h:52
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
Definition: apr_crypto.h:497
Definition: apr_crypto.h:442
Definition: apu_errno.h:289