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 25extern "C" { 26#endif 27 28#if APU_HAVE_CRYPTO 29 30struct apr_crypto_driver_t { 31 32 /** name */ 33 const char *name; 34 35 /** 36 * @brief: allow driver to perform once-only initialisation. 37 * Called once only. 38 * @param pool The pool to register the cleanup in. 39 * @param params Optional init parameter string. 40 * @param rc Driver-specific additional error code 41 */ 42 apr_status_t (*init)(apr_pool_t *pool, const char *params, 43 const apu_err_t **result); 44 45 /** 46 * @brief Create a context for supporting encryption. Keys, certificates, 47 * algorithms and other parameters will be set per context. More than 48 * one context can be created at one time. A cleanup will be automatically 49 * registered with the given pool to guarantee a graceful shutdown. 50 * @param f - context pointer will be written here 51 * @param provider - provider to use 52 * @param params - array of key parameters 53 * @param pool - process pool 54 * @return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE 55 * if the engine cannot be initialised. 56 */ 57 apr_status_t (*make)(apr_crypto_t **f, const apr_crypto_driver_t *provider, 58 const char *params, apr_pool_t *pool); 59 60 /** 61 * @brief Get a hash table of key types, keyed by the name of the type against 62 * a pointer to apr_crypto_block_key_type_t. 63 * 64 * @param types - hashtable of key types keyed to constants. 65 * @param f - encryption context 66 * @return APR_SUCCESS for success 67 */ 68 apr_status_t (*get_block_key_types)(apr_hash_t **types, 69 const apr_crypto_t *f); 70 71 /** 72 * @brief Get a hash table of key modes, keyed by the name of the mode against 73 * a pointer to apr_crypto_block_key_mode_t. 74 * 75 * @param modes - hashtable of key modes keyed to constants. 76 * @param f - encryption context 77 * @return APR_SUCCESS for success 78 */ 79 apr_status_t (*get_block_key_modes)(apr_hash_t **modes, 80 const apr_crypto_t *f); 81 82 /** 83 * @brief Create a key from the given passphrase. By default, the PBKDF2 84 * algorithm is used to generate the key from the passphrase. It is expected 85 * that the same pass phrase will generate the same key, regardless of the 86 * backend crypto platform used. The key is cleaned up when the context 87 * is cleaned, and may be reused with multiple encryption or decryption 88 * operations. 89 * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If 90 * *key is not NULL, *key must point at a previously created structure. 91 * @param key The key returned, see note. 92 * @param ivSize The size of the initialisation vector will be returned, based 93 * on whether an IV is relevant for this type of crypto. 94 * @param pass The passphrase to use. 95 * @param passLen The passphrase length in bytes 96 * @param salt The salt to use. 97 * @param saltLen The salt length in bytes 98 * @param type 3DES_192, AES_128, AES_192, AES_256. 99 * @param mode Electronic Code Book / Cipher Block Chaining. 100 * @param doPad Pad if necessary. 101 * @param iterations Iteration count 102 * @param f The context to use. 103 * @param p The pool to use. 104 * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend 105 * error occurred while generating the key. APR_ENOCIPHER if the type or mode 106 * is not supported by the particular backend. APR_EKEYTYPE if the key type is 107 * not known. APR_EPADDING if padding was requested but is not supported. 108 * APR_ENOTIMPL if not implemented. 109 */ 110 apr_status_t (*passphrase)(apr_crypto_key_t **key, apr_size_t *ivSize, 111 const char *pass, apr_size_t passLen, const unsigned char * salt, 112 apr_size_t saltLen, const apr_crypto_block_key_type_e type, 113 const apr_crypto_block_key_mode_e mode, const int doPad, 114 const int iterations, const apr_crypto_t *f, apr_pool_t *p); 115 116 /** 117 * @brief Initialise a context for encrypting arbitrary data using the given key. 118 * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If 119 * *ctx is not NULL, *ctx must point at a previously created structure. 120 * @param ctx The block context returned, see note. 121 * @param iv Optional initialisation vector. If the buffer pointed to is NULL, 122 * an IV will be created at random, in space allocated from the pool. 123 * If the buffer pointed to is not NULL, the IV in the buffer will be 124 * used. 125 * @param key The key structure. 126 * @param blockSize The block size of the cipher. 127 * @param p The pool to use. 128 * @return Returns APR_ENOIV if an initialisation vector is required but not specified. 129 * Returns APR_EINIT if the backend failed to initialise the context. Returns 130 * APR_ENOTIMPL if not implemented. 131 */ 132 apr_status_t (*block_encrypt_init)(apr_crypto_block_t **ctx, 133 const unsigned char **iv, const apr_crypto_key_t *key, 134 apr_size_t *blockSize, apr_pool_t *p); 135 136 /** 137 * @brief Encrypt data provided by in, write it to out. 138 * @note The number of bytes written will be written to outlen. If 139 * out is NULL, outlen will contain the maximum size of the 140 * buffer needed to hold the data, including any data 141 * generated by apr_crypto_block_encrypt_finish below. If *out points 142 * to NULL, a buffer sufficiently large will be created from 143 * the pool provided. If *out points to a not-NULL value, this 144 * value will be used as a buffer instead. 145 * @param out Address of a buffer to which data will be written, 146 * see note. 147 * @param outlen Length of the output will be written here. 148 * @param in Address of the buffer to read. 149 * @param inlen Length of the buffer to read. 150 * @param ctx The block context to use. 151 * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if 152 * not implemented. 153 */ 154 apr_status_t (*block_encrypt)(unsigned char **out, apr_size_t *outlen, 155 const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx); 156 157 /** 158 * @brief Encrypt final data block, write it to out. 159 * @note If necessary the final block will be written out after being 160 * padded. Typically the final block will be written to the 161 * same buffer used by apr_crypto_block_encrypt, offset by the 162 * number of bytes returned as actually written by the 163 * apr_crypto_block_encrypt() call. After this call, the context 164 * is cleaned and can be reused by apr_crypto_block_encrypt_init(). 165 * @param out Address of a buffer to which data will be written. This 166 * buffer must already exist, and is usually the same 167 * buffer used by apr_evp_crypt(). See note. 168 * @param outlen Length of the output will be written here. 169 * @param ctx The block context to use. 170 * @return APR_ECRYPT if an error occurred. 171 * @return APR_EPADDING if padding was enabled and the block was incorrectly 172 * formatted. 173 * @return APR_ENOTIMPL if not implemented. 174 */ 175 apr_status_t (*block_encrypt_finish)(unsigned char *out, 176 apr_size_t *outlen, apr_crypto_block_t *ctx); 177 178 /** 179 * @brief Initialise a context for decrypting arbitrary data using the given key. 180 * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If 181 * *ctx is not NULL, *ctx must point at a previously created structure. 182 * @param ctx The block context returned, see note. 183 * @param blockSize The block size of the cipher. 184 * @param iv Optional initialisation vector. If the buffer pointed to is NULL, 185 * an IV will be created at random, in space allocated from the pool. 186 * If the buffer is not NULL, the IV in the buffer will be used. 187 * @param key The key structure. 188 * @param p The pool to use. 189 * @return Returns APR_ENOIV if an initialisation vector is required but not specified. 190 * Returns APR_EINIT if the backend failed to initialise the context. Returns 191 * APR_ENOTIMPL if not implemented. 192 */ 193 apr_status_t (*block_decrypt_init)(apr_crypto_block_t **ctx, 194 apr_size_t *blockSize, const unsigned char *iv, 195 const apr_crypto_key_t *key, apr_pool_t *p); 196 197 /** 198 * @brief Decrypt data provided by in, write it to out. 199 * @note The number of bytes written will be written to outlen. If 200 * out is NULL, outlen will contain the maximum size of the 201 * buffer needed to hold the data, including any data 202 * generated by apr_crypto_block_decrypt_finish below. If *out points 203 * to NULL, a buffer sufficiently large will be created from 204 * the pool provided. If *out points to a not-NULL value, this 205 * value will be used as a buffer instead. 206 * @param out Address of a buffer to which data will be written, 207 * see note. 208 * @param outlen Length of the output will be written here. 209 * @param in Address of the buffer to read. 210 * @param inlen Length of the buffer to read. 211 * @param ctx The block context to use. 212 * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if 213 * not implemented. 214 */ 215 apr_status_t (*block_decrypt)(unsigned char **out, apr_size_t *outlen, 216 const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx); 217 218 /** 219 * @brief Decrypt final data block, write it to out. 220 * @note If necessary the final block will be written out after being 221 * padded. Typically the final block will be written to the 222 * same buffer used by apr_crypto_block_decrypt, offset by the 223 * number of bytes returned as actually written by the 224 * apr_crypto_block_decrypt() call. After this call, the context 225 * is cleaned and can be reused by apr_crypto_block_decrypt_init(). 226 * @param out Address of a buffer to which data will be written. This 227 * buffer must already exist, and is usually the same 228 * buffer used by apr_evp_crypt(). See note. 229 * @param outlen Length of the output will be written here. 230 * @param ctx The block context to use. 231 * @return APR_ECRYPT if an error occurred. 232 * @return APR_EPADDING if padding was enabled and the block was incorrectly 233 * formatted. 234 * @return APR_ENOTIMPL if not implemented. 235 */ 236 apr_status_t (*block_decrypt_finish)(unsigned char *out, 237 apr_size_t *outlen, apr_crypto_block_t *ctx); 238 239 /** 240 * @brief Clean encryption / decryption context. 241 * @note After cleanup, a context is free to be reused if necessary. 242 * @param ctx The block context to use. 243 * @return Returns APR_ENOTIMPL if not supported. 244 */ 245 apr_status_t (*block_cleanup)(apr_crypto_block_t *ctx); 246 247 /** 248 * @brief Clean encryption / decryption context. 249 * @note After cleanup, a context is free to be reused if necessary. 250 * @param f The context to use. 251 * @return Returns APR_ENOTIMPL if not supported. 252 */ 253 apr_status_t (*cleanup)(apr_crypto_t *f); 254 255 /** 256 * @brief Clean encryption / decryption context. 257 * @note After cleanup, a context is free to be reused if necessary. 258 * @return Returns APR_ENOTIMPL if not supported. 259 */ 260 apr_status_t (*shutdown)(void); 261 262 /** 263 * @brief: fetch the most recent error from this driver. 264 * @param result - the result structure 265 * @param f - context pointer 266 * @return APR_SUCCESS for success. 267 */ 268 apr_status_t (*error)(const apu_err_t **result, const apr_crypto_t *f); 269 270 /** 271 * @brief Create a key from the provided secret or passphrase. The key is cleaned 272 * up when the context is cleaned, and may be reused with multiple encryption 273 * or decryption operations. 274 * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If 275 * *key is not NULL, *key must point at a previously created structure. 276 * @param key The key returned, see note. 277 * @param rec The key record, from which the key will be derived. 278 * @param f The context to use. 279 * @param p The pool to use. 280 * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend 281 * error occurred while generating the key. APR_ENOCIPHER if the type or mode 282 * is not supported by the particular backend. APR_EKEYTYPE if the key type is 283 * not known. APR_EPADDING if padding was requested but is not supported. 284 * APR_ENOTIMPL if not implemented. 285 */ 286 apr_status_t (*key)(apr_crypto_key_t **key, const apr_crypto_key_rec_t *rec, 287 const apr_crypto_t *f, apr_pool_t *p); 288 289}; 290 291#endif 292 293#ifdef __cplusplus 294} 295#endif 296 297#endif 298