Apache Portable Runtime
|
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_CRYPTO_H 00018 #define APR_CRYPTO_H 00019 00020 #include "apu.h" 00021 #include "apr_pools.h" 00022 #include "apr_tables.h" 00023 #include "apr_hash.h" 00024 #include "apu_errno.h" 00025 00026 #ifdef __cplusplus 00027 extern "C" { 00028 #endif 00029 00030 /** 00031 * @file apr_crypto.h 00032 * @brief APR-UTIL Crypto library 00033 */ 00034 /** 00035 * @defgroup APR_Util_Crypto Crypto routines 00036 * @ingroup APR_Util 00037 * @{ 00038 */ 00039 00040 #if APU_HAVE_CRYPTO 00041 00042 #ifndef APU_CRYPTO_RECOMMENDED_DRIVER 00043 #if APU_HAVE_OPENSSL 00044 #define APU_CRYPTO_RECOMMENDED_DRIVER "openssl" 00045 #else 00046 #if APU_HAVE_NSS 00047 #define APU_CRYPTO_RECOMMENDED_DRIVER "nss" 00048 #else 00049 #if APU_HAVE_MSCNG 00050 #define APU_CRYPTO_RECOMMENDED_DRIVER "mscng" 00051 #else 00052 #if APU_HAVE_MSCAPI 00053 #define APU_CRYPTO_RECOMMENDED_DRIVER "mscapi" 00054 #else 00055 #endif 00056 #endif 00057 #endif 00058 #endif 00059 #endif 00060 00061 /** 00062 * Symmetric Key types understood by the library. 00063 * 00064 * NOTE: It is expected that this list will grow over time. 00065 * 00066 * Interoperability Matrix: 00067 * 00068 * The matrix is based on the testcrypto.c unit test, which attempts to 00069 * test whether a simple encrypt/decrypt will succeed, as well as testing 00070 * whether an encrypted string by one library can be decrypted by the 00071 * others. 00072 * 00073 * Some libraries will successfully encrypt and decrypt their own data, 00074 * but won't decrypt data from another library. It is hoped that over 00075 * time these anomalies will be found and fixed, but until then it is 00076 * recommended that ciphers are chosen that interoperate across platform. 00077 * 00078 * An X below means the test passes, it does not necessarily mean that 00079 * encryption performed is correct or secure. Applications should stick 00080 * to ciphers that pass the interoperablity tests on the right hand side 00081 * of the table. 00082 * 00083 * Aligned data is data whose length is a multiple of the block size for 00084 * the chosen cipher. Padded data is data that is not aligned by block 00085 * size and must be padded by the crypto library. 00086 * 00087 * OpenSSL NSS Interop 00088 * Align Pad Align Pad Align Pad 00089 * 3DES_192/CBC X X X X X X 00090 * 3DES_192/ECB X X 00091 * AES_256/CBC X X X X X X 00092 * AES_256/ECB X X X X 00093 * AES_192/CBC X X X X 00094 * AES_192/ECB X X X 00095 * AES_128/CBC X X X X 00096 * AES_128/ECB X X X 00097 * 00098 * Conclusion: for padded data, use 3DES_192/CBC or AES_256/CBC. For 00099 * aligned data, use 3DES_192/CBC, AES_256/CBC or AES_256/ECB. 00100 */ 00101 00102 typedef enum 00103 { 00104 APR_KEY_NONE, APR_KEY_3DES_192, /** 192 bit (3-Key) 3DES */ 00105 APR_KEY_AES_128, /** 128 bit AES */ 00106 APR_KEY_AES_192, /** 192 bit AES */ 00107 APR_KEY_AES_256 00108 /** 256 bit AES */ 00109 } apr_crypto_block_key_type_e; 00110 00111 typedef enum 00112 { 00113 APR_MODE_NONE, /** An error condition */ 00114 APR_MODE_ECB, /** Electronic Code Book */ 00115 APR_MODE_CBC 00116 /** Cipher Block Chaining */ 00117 } apr_crypto_block_key_mode_e; 00118 00119 /* These are opaque structs. Instantiation is up to each backend */ 00120 typedef struct apr_crypto_driver_t apr_crypto_driver_t; 00121 typedef struct apr_crypto_t apr_crypto_t; 00122 typedef struct apr_crypto_config_t apr_crypto_config_t; 00123 typedef struct apr_crypto_key_t apr_crypto_key_t; 00124 typedef struct apr_crypto_block_t apr_crypto_block_t; 00125 00126 /** 00127 * @brief Perform once-only initialisation. Call once only. 00128 * 00129 * @param pool - pool to register any shutdown cleanups, etc 00130 * @return APR_NOTIMPL in case of no crypto support. 00131 */ 00132 APU_DECLARE(apr_status_t) apr_crypto_init(apr_pool_t *pool); 00133 00134 /** 00135 * @brief Register a cleanup to zero out the buffer provided 00136 * when the pool is cleaned up. 00137 * 00138 * @param pool - pool to register the cleanup 00139 * @param buffer - buffer to zero out 00140 * @param size - size of the buffer to zero out 00141 */ 00142 APU_DECLARE(apr_status_t) apr_crypto_clear(apr_pool_t *pool, void *buffer, 00143 apr_size_t size); 00144 00145 /** 00146 * @brief Get the driver struct for a name 00147 * 00148 * @param driver - pointer to driver struct. 00149 * @param name - driver name 00150 * @param params - array of initialisation parameters 00151 * @param result - result and error message on failure 00152 * @param pool - (process) pool to register cleanup 00153 * @return APR_SUCCESS for success 00154 * @return APR_ENOTIMPL for no driver (when DSO not enabled) 00155 * @return APR_EDSOOPEN if DSO driver file can't be opened 00156 * @return APR_ESYMNOTFOUND if the driver file doesn't contain a driver 00157 * @remarks NSS: the params can have "dir", "key3", "cert7" and "secmod" 00158 * keys, each followed by an equal sign and a value. Such key/value pairs can 00159 * be delimited by space or tab. If the value contains a space, surround the 00160 * whole key value pair in quotes: "dir=My Directory". 00161 * @remarks OpenSSL: currently no params are supported. 00162 */ 00163 APU_DECLARE(apr_status_t) apr_crypto_get_driver( 00164 const apr_crypto_driver_t **driver, 00165 const char *name, const char *params, const apu_err_t **result, 00166 apr_pool_t *pool); 00167 00168 /** 00169 * @brief Return the name of the driver. 00170 * 00171 * @param driver - The driver in use. 00172 * @return The name of the driver. 00173 */ 00174 APU_DECLARE(const char *) apr_crypto_driver_name( 00175 const apr_crypto_driver_t *driver); 00176 00177 /** 00178 * @brief Get the result of the last operation on a context. If the result 00179 * is NULL, the operation was successful. 00180 * @param result - the result structure 00181 * @param f - context pointer 00182 * @return APR_SUCCESS for success 00183 */ 00184 APU_DECLARE(apr_status_t) apr_crypto_error(const apu_err_t **result, 00185 const apr_crypto_t *f); 00186 00187 /** 00188 * @brief Create a context for supporting encryption. Keys, certificates, 00189 * algorithms and other parameters will be set per context. More than 00190 * one context can be created at one time. A cleanup will be automatically 00191 * registered with the given pool to guarantee a graceful shutdown. 00192 * @param f - context pointer will be written here 00193 * @param driver - driver to use 00194 * @param params - array of key parameters 00195 * @param pool - process pool 00196 * @return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE 00197 * if the engine cannot be initialised. 00198 * @remarks NSS: currently no params are supported. 00199 * @remarks OpenSSL: the params can have "engine" as a key, followed by an equal 00200 * sign and a value. 00201 */ 00202 APU_DECLARE(apr_status_t) apr_crypto_make(apr_crypto_t **f, 00203 const apr_crypto_driver_t *driver, const char *params, 00204 apr_pool_t *pool); 00205 00206 /** 00207 * @brief Get a hash table of key types, keyed by the name of the type against 00208 * an integer pointer constant. 00209 * 00210 * @param types - hashtable of key types keyed to constants. 00211 * @param f - encryption context 00212 * @return APR_SUCCESS for success 00213 */ 00214 APU_DECLARE(apr_status_t) apr_crypto_get_block_key_types(apr_hash_t **types, 00215 const apr_crypto_t *f); 00216 00217 /** 00218 * @brief Get a hash table of key modes, keyed by the name of the mode against 00219 * an integer pointer constant. 00220 * 00221 * @param modes - hashtable of key modes keyed to constants. 00222 * @param f - encryption context 00223 * @return APR_SUCCESS for success 00224 */ 00225 APU_DECLARE(apr_status_t) apr_crypto_get_block_key_modes(apr_hash_t **modes, 00226 const apr_crypto_t *f); 00227 00228 /** 00229 * @brief Create a key from the given passphrase. By default, the PBKDF2 00230 * algorithm is used to generate the key from the passphrase. It is expected 00231 * that the same pass phrase will generate the same key, regardless of the 00232 * backend crypto platform used. The key is cleaned up when the context 00233 * is cleaned, and may be reused with multiple encryption or decryption 00234 * operations. 00235 * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If 00236 * *key is not NULL, *key must point at a previously created structure. 00237 * @param key The key returned, see note. 00238 * @param ivSize The size of the initialisation vector will be returned, based 00239 * on whether an IV is relevant for this type of crypto. 00240 * @param pass The passphrase to use. 00241 * @param passLen The passphrase length in bytes 00242 * @param salt The salt to use. 00243 * @param saltLen The salt length in bytes 00244 * @param type 3DES_192, AES_128, AES_192, AES_256. 00245 * @param mode Electronic Code Book / Cipher Block Chaining. 00246 * @param doPad Pad if necessary. 00247 * @param iterations Number of iterations to use in algorithm 00248 * @param f The context to use. 00249 * @param p The pool to use. 00250 * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend 00251 * error occurred while generating the key. APR_ENOCIPHER if the type or mode 00252 * is not supported by the particular backend. APR_EKEYTYPE if the key type is 00253 * not known. APR_EPADDING if padding was requested but is not supported. 00254 * APR_ENOTIMPL if not implemented. 00255 */ 00256 APU_DECLARE(apr_status_t) apr_crypto_passphrase(apr_crypto_key_t **key, 00257 apr_size_t *ivSize, const char *pass, apr_size_t passLen, 00258 const unsigned char * salt, apr_size_t saltLen, 00259 const apr_crypto_block_key_type_e type, 00260 const apr_crypto_block_key_mode_e mode, const int doPad, 00261 const int iterations, const apr_crypto_t *f, apr_pool_t *p); 00262 00263 /** 00264 * @brief Initialise a context for encrypting arbitrary data using the given key. 00265 * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If 00266 * *ctx is not NULL, *ctx must point at a previously created structure. 00267 * @param ctx The block context returned, see note. 00268 * @param iv Optional initialisation vector. If the buffer pointed to is NULL, 00269 * an IV will be created at random, in space allocated from the pool. 00270 * If the buffer pointed to is not NULL, the IV in the buffer will be 00271 * used. 00272 * @param key The key structure to use. 00273 * @param blockSize The block size of the cipher. 00274 * @param p The pool to use. 00275 * @return Returns APR_ENOIV if an initialisation vector is required but not specified. 00276 * Returns APR_EINIT if the backend failed to initialise the context. Returns 00277 * APR_ENOTIMPL if not implemented. 00278 */ 00279 APU_DECLARE(apr_status_t) apr_crypto_block_encrypt_init( 00280 apr_crypto_block_t **ctx, const unsigned char **iv, 00281 const apr_crypto_key_t *key, apr_size_t *blockSize, apr_pool_t *p); 00282 00283 /** 00284 * @brief Encrypt data provided by in, write it to out. 00285 * @note The number of bytes written will be written to outlen. If 00286 * out is NULL, outlen will contain the maximum size of the 00287 * buffer needed to hold the data, including any data 00288 * generated by apr_crypto_block_encrypt_finish below. If *out points 00289 * to NULL, a buffer sufficiently large will be created from 00290 * the pool provided. If *out points to a not-NULL value, this 00291 * value will be used as a buffer instead. 00292 * @param out Address of a buffer to which data will be written, 00293 * see note. 00294 * @param outlen Length of the output will be written here. 00295 * @param in Address of the buffer to read. 00296 * @param inlen Length of the buffer to read. 00297 * @param ctx The block context to use. 00298 * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if 00299 * not implemented. 00300 */ 00301 APU_DECLARE(apr_status_t) apr_crypto_block_encrypt(unsigned char **out, 00302 apr_size_t *outlen, const unsigned char *in, apr_size_t inlen, 00303 apr_crypto_block_t *ctx); 00304 00305 /** 00306 * @brief Encrypt final data block, write it to out. 00307 * @note If necessary the final block will be written out after being 00308 * padded. Typically the final block will be written to the 00309 * same buffer used by apr_crypto_block_encrypt, offset by the 00310 * number of bytes returned as actually written by the 00311 * apr_crypto_block_encrypt() call. After this call, the context 00312 * is cleaned and can be reused by apr_crypto_block_encrypt_init(). 00313 * @param out Address of a buffer to which data will be written. This 00314 * buffer must already exist, and is usually the same 00315 * buffer used by apr_evp_crypt(). See note. 00316 * @param outlen Length of the output will be written here. 00317 * @param ctx The block context to use. 00318 * @return APR_ECRYPT if an error occurred. 00319 * @return APR_EPADDING if padding was enabled and the block was incorrectly 00320 * formatted. 00321 * @return APR_ENOTIMPL if not implemented. 00322 */ 00323 APU_DECLARE(apr_status_t) apr_crypto_block_encrypt_finish(unsigned char *out, 00324 apr_size_t *outlen, apr_crypto_block_t *ctx); 00325 00326 /** 00327 * @brief Initialise a context for decrypting arbitrary data using the given key. 00328 * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If 00329 * *ctx is not NULL, *ctx must point at a previously created structure. 00330 * @param ctx The block context returned, see note. 00331 * @param blockSize The block size of the cipher. 00332 * @param iv Optional initialisation vector. 00333 * @param key The key structure to use. 00334 * @param p The pool to use. 00335 * @return Returns APR_ENOIV if an initialisation vector is required but not specified. 00336 * Returns APR_EINIT if the backend failed to initialise the context. Returns 00337 * APR_ENOTIMPL if not implemented. 00338 */ 00339 APU_DECLARE(apr_status_t) apr_crypto_block_decrypt_init( 00340 apr_crypto_block_t **ctx, apr_size_t *blockSize, 00341 const unsigned char *iv, const apr_crypto_key_t *key, apr_pool_t *p); 00342 00343 /** 00344 * @brief Decrypt data provided by in, write it to out. 00345 * @note The number of bytes written will be written to outlen. If 00346 * out is NULL, outlen will contain the maximum size of the 00347 * buffer needed to hold the data, including any data 00348 * generated by apr_crypto_block_decrypt_finish below. If *out points 00349 * to NULL, a buffer sufficiently large will be created from 00350 * the pool provided. If *out points to a not-NULL value, this 00351 * value will be used as a buffer instead. 00352 * @param out Address of a buffer to which data will be written, 00353 * see note. 00354 * @param outlen Length of the output will be written here. 00355 * @param in Address of the buffer to read. 00356 * @param inlen Length of the buffer to read. 00357 * @param ctx The block context to use. 00358 * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if 00359 * not implemented. 00360 */ 00361 APU_DECLARE(apr_status_t) apr_crypto_block_decrypt(unsigned char **out, 00362 apr_size_t *outlen, const unsigned char *in, apr_size_t inlen, 00363 apr_crypto_block_t *ctx); 00364 00365 /** 00366 * @brief Decrypt final data block, write it to out. 00367 * @note If necessary the final block will be written out after being 00368 * padded. Typically the final block will be written to the 00369 * same buffer used by apr_crypto_block_decrypt, offset by the 00370 * number of bytes returned as actually written by the 00371 * apr_crypto_block_decrypt() call. After this call, the context 00372 * is cleaned and can be reused by apr_crypto_block_decrypt_init(). 00373 * @param out Address of a buffer to which data will be written. This 00374 * buffer must already exist, and is usually the same 00375 * buffer used by apr_evp_crypt(). See note. 00376 * @param outlen Length of the output will be written here. 00377 * @param ctx The block context to use. 00378 * @return APR_ECRYPT if an error occurred. 00379 * @return APR_EPADDING if padding was enabled and the block was incorrectly 00380 * formatted. 00381 * @return APR_ENOTIMPL if not implemented. 00382 */ 00383 APU_DECLARE(apr_status_t) apr_crypto_block_decrypt_finish(unsigned char *out, 00384 apr_size_t *outlen, apr_crypto_block_t *ctx); 00385 00386 /** 00387 * @brief Clean encryption / decryption context. 00388 * @note After cleanup, a context is free to be reused if necessary. 00389 * @param ctx The block context to use. 00390 * @return Returns APR_ENOTIMPL if not supported. 00391 */ 00392 APU_DECLARE(apr_status_t) apr_crypto_block_cleanup(apr_crypto_block_t *ctx); 00393 00394 /** 00395 * @brief Clean encryption / decryption context. 00396 * @note After cleanup, a context is free to be reused if necessary. 00397 * @param f The context to use. 00398 * @return Returns APR_ENOTIMPL if not supported. 00399 */ 00400 APU_DECLARE(apr_status_t) apr_crypto_cleanup(apr_crypto_t *f); 00401 00402 /** 00403 * @brief Shutdown the crypto library. 00404 * @note After shutdown, it is expected that the init function can be called again. 00405 * @param driver - driver to use 00406 * @return Returns APR_ENOTIMPL if not supported. 00407 */ 00408 APU_DECLARE(apr_status_t) apr_crypto_shutdown( 00409 const apr_crypto_driver_t *driver); 00410 00411 #endif /* APU_HAVE_CRYPTO */ 00412 00413 /** @} */ 00414 00415 #ifdef __cplusplus 00416 } 00417 #endif 00418 00419 #endif