contrib/apr-util/include/private/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 struct 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      * an integer pointer constant.
  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      * an integer pointer constant.
  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
 272 #endif
 273
 274 #ifdef __cplusplus
 275 }
 276 #endif
 277
 278 #endif