Apache Portable Runtime
apr_crypto.h
Go to the documentation of this file.
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_H
18 #define APR_CRYPTO_H
19 
20 #include "apu.h"
21 #include "apr_pools.h"
22 #include "apr_tables.h"
23 #include "apr_hash.h"
24 #include "apu_errno.h"
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /**
31  * @file apr_crypto.h
32  * @brief APR-UTIL Crypto library
33  */
34 /**
35  * @defgroup APR_Util_Crypto Crypto routines
36  * @ingroup APR
37  * @{
38  */
39 
40 #if APU_HAVE_CRYPTO
41 
42 #ifndef APU_CRYPTO_RECOMMENDED_DRIVER
43 #if APU_HAVE_COMMONCRYPTO
44 #define APU_CRYPTO_RECOMMENDED_DRIVER "commoncrypto"
45 #else
46 #if APU_HAVE_OPENSSL
47 #define APU_CRYPTO_RECOMMENDED_DRIVER "openssl"
48 #else
49 #if APU_HAVE_NSS
50 #define APU_CRYPTO_RECOMMENDED_DRIVER "nss"
51 #else
52 #if APU_HAVE_MSCNG
53 #define APU_CRYPTO_RECOMMENDED_DRIVER "mscng"
54 #else
55 #if APU_HAVE_MSCAPI
56 #define APU_CRYPTO_RECOMMENDED_DRIVER "mscapi"
57 #else
58 #endif
59 #endif
60 #endif
61 #endif
62 #endif
63 #endif
64 
65 /**
66  * Symmetric Key types understood by the library.
67  *
68  * NOTE: It is expected that this list will grow over time.
69  *
70  * Interoperability Matrix:
71  *
72  * The matrix is based on the testcrypto.c unit test, which attempts to
73  * test whether a simple encrypt/decrypt will succeed, as well as testing
74  * whether an encrypted string by one library can be decrypted by the
75  * others.
76  *
77  * Some libraries will successfully encrypt and decrypt their own data,
78  * but won't decrypt data from another library. It is hoped that over
79  * time these anomalies will be found and fixed, but until then it is
80  * recommended that ciphers are chosen that interoperate across platform.
81  *
82  * An X below means the test passes, it does not necessarily mean that
83  * encryption performed is correct or secure. Applications should stick
84  * to ciphers that pass the interoperablity tests on the right hand side
85  * of the table.
86  *
87  * Aligned data is data whose length is a multiple of the block size for
88  * the chosen cipher. Padded data is data that is not aligned by block
89  * size and must be padded by the crypto library.
90  *
91  * OpenSSL CommonCrypto NSS Interop
92  * Align Pad Align Pad Align Pad Align Pad
93  * 3DES_192/CBC X X X X X X X X
94  * 3DES_192/ECB X X X X
95  * AES_256/CBC X X X X X X X X
96  * AES_256/ECB X X X X X X
97  * AES_192/CBC X X X X X X
98  * AES_192/ECB X X X X X
99  * AES_128/CBC X X X X X X
100  * AES_128/ECB X X X X X
101  *
102  * Conclusion: for padded data, use 3DES_192/CBC or AES_256/CBC. For
103  * aligned data, use 3DES_192/CBC, AES_256/CBC or AES_256/ECB.
104  */
105 
106 typedef enum
107 {
108  APR_KEY_NONE, APR_KEY_3DES_192, /** 192 bit (3-Key) 3DES */
109  APR_KEY_AES_128, /** 128 bit AES */
110  APR_KEY_AES_192, /** 192 bit AES */
111  APR_KEY_AES_256
112 /** 256 bit AES */
113 } apr_crypto_block_key_type_e;
114 
115 typedef enum
116 {
117  APR_MODE_NONE, /** An error condition */
118  APR_MODE_ECB, /** Electronic Code Book */
119  APR_MODE_CBC
120 /** Cipher Block Chaining */
121 } apr_crypto_block_key_mode_e;
122 
123 /* These are opaque structs. Instantiation is up to each backend */
124 typedef struct apr_crypto_driver_t apr_crypto_driver_t;
125 typedef struct apr_crypto_t apr_crypto_t;
126 typedef struct apr_crypto_config_t apr_crypto_config_t;
127 typedef struct apr_crypto_key_t apr_crypto_key_t;
128 typedef struct apr_crypto_block_t apr_crypto_block_t;
129 
130 /**
131  * @brief Perform once-only initialisation. Call once only.
132  *
133  * @param pool - pool to register any shutdown cleanups, etc
134  * @return APR_NOTIMPL in case of no crypto support.
135  */
136 APR_DECLARE(apr_status_t) apr_crypto_init(apr_pool_t *pool);
137 
138 /**
139  * @brief Register a cleanup to zero out the buffer provided
140  * when the pool is cleaned up.
141  *
142  * @param pool - pool to register the cleanup
143  * @param buffer - buffer to zero out
144  * @param size - size of the buffer to zero out
145  */
146 APR_DECLARE(apr_status_t) apr_crypto_clear(apr_pool_t *pool, void *buffer,
147  apr_size_t size);
148 
149 /**
150  * @brief Get the driver struct for a name
151  *
152  * @param driver - pointer to driver struct.
153  * @param name - driver name
154  * @param params - array of initialisation parameters
155  * @param result - result and error message on failure
156  * @param pool - (process) pool to register cleanup
157  * @return APR_SUCCESS for success
158  * @return APR_ENOTIMPL for no driver (when DSO not enabled)
159  * @return APR_EDSOOPEN if DSO driver file can't be opened
160  * @return APR_ESYMNOTFOUND if the driver file doesn't contain a driver
161  * @remarks NSS: the params can have "dir", "key3", "cert7" and "secmod"
162  * keys, each followed by an equal sign and a value. Such key/value pairs can
163  * be delimited by space or tab. If the value contains a space, surround the
164  * whole key value pair in quotes: "dir=My Directory".
165  * @remarks OpenSSL: currently no params are supported.
166  */
167 APR_DECLARE(apr_status_t) apr_crypto_get_driver(
168  const apr_crypto_driver_t **driver, const char *name,
169  const char *params, const apu_err_t **result, apr_pool_t *pool);
170 
171 /**
172  * @brief Return the name of the driver.
173  *
174  * @param driver - The driver in use.
175  * @return The name of the driver.
176  */
177 APR_DECLARE(const char *) apr_crypto_driver_name(
178  const apr_crypto_driver_t *driver);
179 
180 /**
181  * @brief Get the result of the last operation on a context. If the result
182  * is NULL, the operation was successful.
183  * @param result - the result structure
184  * @param f - context pointer
185  * @return APR_SUCCESS for success
186  */
187 APR_DECLARE(apr_status_t) apr_crypto_error(const apu_err_t **result,
188  const apr_crypto_t *f);
189 
190 /**
191  * @brief Create a context for supporting encryption. Keys, certificates,
192  * algorithms and other parameters will be set per context. More than
193  * one context can be created at one time. A cleanup will be automatically
194  * registered with the given pool to guarantee a graceful shutdown.
195  * @param f - context pointer will be written here
196  * @param driver - driver to use
197  * @param params - array of key parameters
198  * @param pool - process pool
199  * @return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE
200  * if the engine cannot be initialised.
201  * @remarks NSS: currently no params are supported.
202  * @remarks OpenSSL: the params can have "engine" as a key, followed by an equal
203  * sign and a value.
204  */
206  apr_crypto_make(apr_crypto_t **f, const apr_crypto_driver_t *driver,
207  const char *params, apr_pool_t *pool);
208 
209 /**
210  * @brief Get a hash table of key types, keyed by the name of the type against
211  * an integer pointer constant.
212  *
213  * @param types - hashtable of key types keyed to constants.
214  * @param f - encryption context
215  * @return APR_SUCCESS for success
216  */
217 APR_DECLARE(apr_status_t) apr_crypto_get_block_key_types(apr_hash_t **types,
218  const apr_crypto_t *f);
219 
220 /**
221  * @brief Get a hash table of key modes, keyed by the name of the mode against
222  * an integer pointer constant.
223  *
224  * @param modes - hashtable of key modes keyed to constants.
225  * @param f - encryption context
226  * @return APR_SUCCESS for success
227  */
228 APR_DECLARE(apr_status_t) apr_crypto_get_block_key_modes(apr_hash_t **modes,
229  const apr_crypto_t *f);
230 
231 /**
232  * @brief Create a key from the given passphrase. By default, the PBKDF2
233  * algorithm is used to generate the key from the passphrase. It is expected
234  * that the same pass phrase will generate the same key, regardless of the
235  * backend crypto platform used. The key is cleaned up when the context
236  * is cleaned, and may be reused with multiple encryption or decryption
237  * operations.
238  * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
239  * *key is not NULL, *key must point at a previously created structure.
240  * @param key The key returned, see note.
241  * @param ivSize The size of the initialisation vector will be returned, based
242  * on whether an IV is relevant for this type of crypto.
243  * @param pass The passphrase to use.
244  * @param passLen The passphrase length in bytes
245  * @param salt The salt to use.
246  * @param saltLen The salt length in bytes
247  * @param type 3DES_192, AES_128, AES_192, AES_256.
248  * @param mode Electronic Code Book / Cipher Block Chaining.
249  * @param doPad Pad if necessary.
250  * @param iterations Number of iterations to use in algorithm
251  * @param f The context to use.
252  * @param p The pool to use.
253  * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
254  * error occurred while generating the key. APR_ENOCIPHER if the type or mode
255  * is not supported by the particular backend. APR_EKEYTYPE if the key type is
256  * not known. APR_EPADDING if padding was requested but is not supported.
257  * APR_ENOTIMPL if not implemented.
258  */
259 APR_DECLARE(apr_status_t) apr_crypto_passphrase(apr_crypto_key_t **key,
260  apr_size_t *ivSize, const char *pass, apr_size_t passLen,
261  const unsigned char * salt, apr_size_t saltLen,
262  const apr_crypto_block_key_type_e type,
263  const apr_crypto_block_key_mode_e mode, const int doPad,
264  const int iterations, const apr_crypto_t *f, apr_pool_t *p);
265 
266 /**
267  * @brief Initialise a context for encrypting arbitrary data using the given key.
268  * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
269  * *ctx is not NULL, *ctx must point at a previously created structure.
270  * @param ctx The block context returned, see note.
271  * @param iv Optional initialisation vector. If the buffer pointed to is NULL,
272  * an IV will be created at random, in space allocated from the pool.
273  * If the buffer pointed to is not NULL, the IV in the buffer will be
274  * used.
275  * @param key The key structure to use.
276  * @param blockSize The block size of the cipher.
277  * @param p The pool to use.
278  * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
279  * Returns APR_EINIT if the backend failed to initialise the context. Returns
280  * APR_ENOTIMPL if not implemented.
281  */
282 APR_DECLARE(apr_status_t) apr_crypto_block_encrypt_init(
283  apr_crypto_block_t **ctx, const unsigned char **iv,
284  const apr_crypto_key_t *key, apr_size_t *blockSize, apr_pool_t *p);
285 
286 /**
287  * @brief Encrypt data provided by in, write it to out.
288  * @note The number of bytes written will be written to outlen. If
289  * out is NULL, outlen will contain the maximum size of the
290  * buffer needed to hold the data, including any data
291  * generated by apr_crypto_block_encrypt_finish below. If *out points
292  * to NULL, a buffer sufficiently large will be created from
293  * the pool provided. If *out points to a not-NULL value, this
294  * value will be used as a buffer instead.
295  * @param out Address of a buffer to which data will be written,
296  * see note.
297  * @param outlen Length of the output will be written here.
298  * @param in Address of the buffer to read.
299  * @param inlen Length of the buffer to read.
300  * @param ctx The block context to use.
301  * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
302  * not implemented.
303  */
304 APR_DECLARE(apr_status_t) apr_crypto_block_encrypt(unsigned char **out,
305  apr_size_t *outlen, const unsigned char *in, apr_size_t inlen,
306  apr_crypto_block_t *ctx);
307 
308 /**
309  * @brief Encrypt final data block, write it to out.
310  * @note If necessary the final block will be written out after being
311  * padded. Typically the final block will be written to the
312  * same buffer used by apr_crypto_block_encrypt, offset by the
313  * number of bytes returned as actually written by the
314  * apr_crypto_block_encrypt() call. After this call, the context
315  * is cleaned and can be reused by apr_crypto_block_encrypt_init().
316  * @param out Address of a buffer to which data will be written. This
317  * buffer must already exist, and is usually the same
318  * buffer used by apr_evp_crypt(). See note.
319  * @param outlen Length of the output will be written here.
320  * @param ctx The block context to use.
321  * @return APR_ECRYPT if an error occurred.
322  * @return APR_EPADDING if padding was enabled and the block was incorrectly
323  * formatted.
324  * @return APR_ENOTIMPL if not implemented.
325  */
326 APR_DECLARE(apr_status_t) apr_crypto_block_encrypt_finish(unsigned char *out,
327  apr_size_t *outlen, apr_crypto_block_t *ctx);
328 
329 /**
330  * @brief Initialise a context for decrypting arbitrary data using the given key.
331  * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
332  * *ctx is not NULL, *ctx must point at a previously created structure.
333  * @param ctx The block context returned, see note.
334  * @param blockSize The block size of the cipher.
335  * @param iv Optional initialisation vector.
336  * @param key The key structure to use.
337  * @param p The pool to use.
338  * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
339  * Returns APR_EINIT if the backend failed to initialise the context. Returns
340  * APR_ENOTIMPL if not implemented.
341  */
342 APR_DECLARE(apr_status_t) apr_crypto_block_decrypt_init(
343  apr_crypto_block_t **ctx, apr_size_t *blockSize,
344  const unsigned char *iv, const apr_crypto_key_t *key, apr_pool_t *p);
345 
346 /**
347  * @brief Decrypt data provided by in, write it to out.
348  * @note The number of bytes written will be written to outlen. If
349  * out is NULL, outlen will contain the maximum size of the
350  * buffer needed to hold the data, including any data
351  * generated by apr_crypto_block_decrypt_finish below. If *out points
352  * to NULL, a buffer sufficiently large will be created from
353  * the pool provided. If *out points to a not-NULL value, this
354  * value will be used as a buffer instead.
355  * @param out Address of a buffer to which data will be written,
356  * see note.
357  * @param outlen Length of the output will be written here.
358  * @param in Address of the buffer to read.
359  * @param inlen Length of the buffer to read.
360  * @param ctx The block context to use.
361  * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
362  * not implemented.
363  */
364 APR_DECLARE(apr_status_t) apr_crypto_block_decrypt(unsigned char **out,
365  apr_size_t *outlen, const unsigned char *in, apr_size_t inlen,
366  apr_crypto_block_t *ctx);
367 
368 /**
369  * @brief Decrypt final data block, write it to out.
370  * @note If necessary the final block will be written out after being
371  * padded. Typically the final block will be written to the
372  * same buffer used by apr_crypto_block_decrypt, offset by the
373  * number of bytes returned as actually written by the
374  * apr_crypto_block_decrypt() call. After this call, the context
375  * is cleaned and can be reused by apr_crypto_block_decrypt_init().
376  * @param out Address of a buffer to which data will be written. This
377  * buffer must already exist, and is usually the same
378  * buffer used by apr_evp_crypt(). See note.
379  * @param outlen Length of the output will be written here.
380  * @param ctx The block context to use.
381  * @return APR_ECRYPT if an error occurred.
382  * @return APR_EPADDING if padding was enabled and the block was incorrectly
383  * formatted.
384  * @return APR_ENOTIMPL if not implemented.
385  */
386 APR_DECLARE(apr_status_t) apr_crypto_block_decrypt_finish(unsigned char *out,
387  apr_size_t *outlen, apr_crypto_block_t *ctx);
388 
389 /**
390  * @brief Clean encryption / decryption context.
391  * @note After cleanup, a context is free to be reused if necessary.
392  * @param ctx The block context to use.
393  * @return Returns APR_ENOTIMPL if not supported.
394  */
395 APR_DECLARE(apr_status_t) apr_crypto_block_cleanup(apr_crypto_block_t *ctx);
396 
397 /**
398  * @brief Clean encryption / decryption context.
399  * @note After cleanup, a context is free to be reused if necessary.
400  * @param f The context to use.
401  * @return Returns APR_ENOTIMPL if not supported.
402  */
403 APR_DECLARE(apr_status_t) apr_crypto_cleanup(apr_crypto_t *f);
404 
405 /**
406  * @brief Shutdown the crypto library.
407  * @note After shutdown, it is expected that the init function can be called again.
408  * @param driver - driver to use
409  * @return Returns APR_ENOTIMPL if not supported.
410  */
412  apr_crypto_shutdown(const apr_crypto_driver_t *driver);
413 
414 #endif /* APU_HAVE_CRYPTO */
415 
416 /** @} */
417 
418 #ifdef __cplusplus
419 }
420 #endif
421 
422 #endif
APR Hash Tables.
APR-Util Error Codes.
APR memory allocation.
APR Table library.
#define APR_DECLARE(type)
Definition: apr.h:500
struct apr_hash_t apr_hash_t
Definition: apr_hash.h:52
Definition: apu_errno.h:161
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
int apr_status_t
Definition: apr_errno.h:44