Apache Portable Runtime
apr_crypto_internal.h
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_INTERNAL_H
00018 #define APR_CRYPTO_INTERNAL_H
00019 
00020 #include <stdarg.h>
00021 
00022 #include "apr_crypto.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 #if APU_HAVE_CRYPTO
00029 
00030 struct apr_crypto_driver_t {
00031 
00032     /** name */
00033     const char *name;
00034 
00035     /**
00036      * @brief: allow driver to perform once-only initialisation.
00037      * Called once only.
00038      * @param pool The pool to register the cleanup in.
00039      * @param params Optional init parameter string.
00040      * @param rc Driver-specific additional error code
00041      */
00042     apr_status_t (*init)(apr_pool_t *pool, const char *params,
00043             const apu_err_t **result);
00044 
00045     /**
00046      * @brief Create a context for supporting encryption. Keys, certificates,
00047      *        algorithms and other parameters will be set per context. More than
00048      *        one context can be created at one time. A cleanup will be automatically
00049      *        registered with the given pool to guarantee a graceful shutdown.
00050      * @param f - context pointer will be written here
00051      * @param provider - provider to use
00052      * @param params - array of key parameters
00053      * @param pool - process pool
00054      * @return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE
00055      * if the engine cannot be initialised.
00056      */
00057     apr_status_t (*make)(apr_crypto_t **f, const apr_crypto_driver_t *provider,
00058             const char *params, apr_pool_t *pool);
00059 
00060     /**
00061      * @brief Get a hash table of key types, keyed by the name of the type against
00062      * an integer pointer constant.
00063      *
00064      * @param types - hashtable of key types keyed to constants.
00065      * @param f - encryption context
00066      * @return APR_SUCCESS for success
00067      */
00068     apr_status_t (*get_block_key_types)(apr_hash_t **types,
00069             const apr_crypto_t *f);
00070 
00071     /**
00072      * @brief Get a hash table of key modes, keyed by the name of the mode against
00073      * an integer pointer constant.
00074      *
00075      * @param modes - hashtable of key modes keyed to constants.
00076      * @param f - encryption context
00077      * @return APR_SUCCESS for success
00078      */
00079     apr_status_t (*get_block_key_modes)(apr_hash_t **modes,
00080             const apr_crypto_t *f);
00081 
00082     /**
00083      * @brief Create a key from the given passphrase. By default, the PBKDF2
00084      *        algorithm is used to generate the key from the passphrase. It is expected
00085      *        that the same pass phrase will generate the same key, regardless of the
00086      *        backend crypto platform used. The key is cleaned up when the context
00087      *        is cleaned, and may be reused with multiple encryption or decryption
00088      *        operations.
00089      * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
00090      *       *key is not NULL, *key must point at a previously created structure.
00091      * @param key The key returned, see note.
00092      * @param ivSize The size of the initialisation vector will be returned, based
00093      *               on whether an IV is relevant for this type of crypto.
00094      * @param pass The passphrase to use.
00095      * @param passLen The passphrase length in bytes
00096      * @param salt The salt to use.
00097      * @param saltLen The salt length in bytes
00098      * @param type 3DES_192, AES_128, AES_192, AES_256.
00099      * @param mode Electronic Code Book / Cipher Block Chaining.
00100      * @param doPad Pad if necessary.
00101      * @param iterations Iteration count
00102      * @param f The context to use.
00103      * @param p The pool to use.
00104      * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
00105      *         error occurred while generating the key. APR_ENOCIPHER if the type or mode
00106      *         is not supported by the particular backend. APR_EKEYTYPE if the key type is
00107      *         not known. APR_EPADDING if padding was requested but is not supported.
00108      *         APR_ENOTIMPL if not implemented.
00109      */
00110     apr_status_t (*passphrase)(apr_crypto_key_t **key, apr_size_t *ivSize,
00111             const char *pass, apr_size_t passLen, const unsigned char * salt,
00112             apr_size_t saltLen, const apr_crypto_block_key_type_e type,
00113             const apr_crypto_block_key_mode_e mode, const int doPad,
00114             const int iterations, const apr_crypto_t *f, apr_pool_t *p);
00115 
00116     /**
00117      * @brief Initialise a context for encrypting arbitrary data using the given key.
00118      * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
00119      *       *ctx is not NULL, *ctx must point at a previously created structure.
00120      * @param ctx The block context returned, see note.
00121      * @param iv Optional initialisation vector. If the buffer pointed to is NULL,
00122      *           an IV will be created at random, in space allocated from the pool.
00123      *           If the buffer pointed to is not NULL, the IV in the buffer will be
00124      *           used.
00125      * @param key The key structure.
00126      * @param blockSize The block size of the cipher.
00127      * @param p The pool to use.
00128      * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
00129      *         Returns APR_EINIT if the backend failed to initialise the context. Returns
00130      *         APR_ENOTIMPL if not implemented.
00131      */
00132     apr_status_t (*block_encrypt_init)(apr_crypto_block_t **ctx,
00133             const unsigned char **iv, const apr_crypto_key_t *key,
00134             apr_size_t *blockSize, apr_pool_t *p);
00135 
00136     /**
00137      * @brief Encrypt data provided by in, write it to out.
00138      * @note The number of bytes written will be written to outlen. If
00139      *       out is NULL, outlen will contain the maximum size of the
00140      *       buffer needed to hold the data, including any data
00141      *       generated by apr_crypto_block_encrypt_finish below. If *out points
00142      *       to NULL, a buffer sufficiently large will be created from
00143      *       the pool provided. If *out points to a not-NULL value, this
00144      *       value will be used as a buffer instead.
00145      * @param out Address of a buffer to which data will be written,
00146      *        see note.
00147      * @param outlen Length of the output will be written here.
00148      * @param in Address of the buffer to read.
00149      * @param inlen Length of the buffer to read.
00150      * @param ctx The block context to use.
00151      * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
00152      *         not implemented.
00153      */
00154     apr_status_t (*block_encrypt)(unsigned char **out, apr_size_t *outlen,
00155             const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx);
00156 
00157     /**
00158      * @brief Encrypt final data block, write it to out.
00159      * @note If necessary the final block will be written out after being
00160      *       padded. Typically the final block will be written to the
00161      *       same buffer used by apr_crypto_block_encrypt, offset by the
00162      *       number of bytes returned as actually written by the
00163      *       apr_crypto_block_encrypt() call. After this call, the context
00164      *       is cleaned and can be reused by apr_crypto_block_encrypt_init().
00165      * @param out Address of a buffer to which data will be written. This
00166      *            buffer must already exist, and is usually the same
00167      *            buffer used by apr_evp_crypt(). See note.
00168      * @param outlen Length of the output will be written here.
00169      * @param ctx The block context to use.
00170      * @return APR_ECRYPT if an error occurred.
00171      * @return APR_EPADDING if padding was enabled and the block was incorrectly
00172      *         formatted.
00173      * @return APR_ENOTIMPL if not implemented.
00174      */
00175     apr_status_t (*block_encrypt_finish)(unsigned char *out,
00176             apr_size_t *outlen, apr_crypto_block_t *ctx);
00177 
00178     /**
00179      * @brief Initialise a context for decrypting arbitrary data using the given key.
00180      * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
00181      *       *ctx is not NULL, *ctx must point at a previously created structure.
00182      * @param ctx The block context returned, see note.
00183      * @param blockSize The block size of the cipher.
00184      * @param iv Optional initialisation vector. If the buffer pointed to is NULL,
00185      *           an IV will be created at random, in space allocated from the pool.
00186      *           If the buffer is not NULL, the IV in the buffer will be used.
00187      * @param key The key structure.
00188      * @param p The pool to use.
00189      * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
00190      *         Returns APR_EINIT if the backend failed to initialise the context. Returns
00191      *         APR_ENOTIMPL if not implemented.
00192      */
00193     apr_status_t (*block_decrypt_init)(apr_crypto_block_t **ctx,
00194             apr_size_t *blockSize, const unsigned char *iv,
00195             const apr_crypto_key_t *key, apr_pool_t *p);
00196 
00197     /**
00198      * @brief Decrypt data provided by in, write it to out.
00199      * @note The number of bytes written will be written to outlen. If
00200      *       out is NULL, outlen will contain the maximum size of the
00201      *       buffer needed to hold the data, including any data
00202      *       generated by apr_crypto_block_decrypt_finish below. If *out points
00203      *       to NULL, a buffer sufficiently large will be created from
00204      *       the pool provided. If *out points to a not-NULL value, this
00205      *       value will be used as a buffer instead.
00206      * @param out Address of a buffer to which data will be written,
00207      *        see note.
00208      * @param outlen Length of the output will be written here.
00209      * @param in Address of the buffer to read.
00210      * @param inlen Length of the buffer to read.
00211      * @param ctx The block context to use.
00212      * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
00213      *         not implemented.
00214      */
00215     apr_status_t (*block_decrypt)(unsigned char **out, apr_size_t *outlen,
00216             const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx);
00217 
00218     /**
00219      * @brief Decrypt final data block, write it to out.
00220      * @note If necessary the final block will be written out after being
00221      *       padded. Typically the final block will be written to the
00222      *       same buffer used by apr_crypto_block_decrypt, offset by the
00223      *       number of bytes returned as actually written by the
00224      *       apr_crypto_block_decrypt() call. After this call, the context
00225      *       is cleaned and can be reused by apr_crypto_block_decrypt_init().
00226      * @param out Address of a buffer to which data will be written. This
00227      *            buffer must already exist, and is usually the same
00228      *            buffer used by apr_evp_crypt(). See note.
00229      * @param outlen Length of the output will be written here.
00230      * @param ctx The block context to use.
00231      * @return APR_ECRYPT if an error occurred.
00232      * @return APR_EPADDING if padding was enabled and the block was incorrectly
00233      *         formatted.
00234      * @return APR_ENOTIMPL if not implemented.
00235      */
00236     apr_status_t (*block_decrypt_finish)(unsigned char *out,
00237             apr_size_t *outlen, apr_crypto_block_t *ctx);
00238 
00239     /**
00240      * @brief Clean encryption / decryption context.
00241      * @note After cleanup, a context is free to be reused if necessary.
00242      * @param ctx The block context to use.
00243      * @return Returns APR_ENOTIMPL if not supported.
00244      */
00245     apr_status_t (*block_cleanup)(apr_crypto_block_t *ctx);
00246 
00247     /**
00248      * @brief Clean encryption / decryption context.
00249      * @note After cleanup, a context is free to be reused if necessary.
00250      * @param f The context to use.
00251      * @return Returns APR_ENOTIMPL if not supported.
00252      */
00253     apr_status_t (*cleanup)(apr_crypto_t *f);
00254 
00255     /**
00256      * @brief Clean encryption / decryption context.
00257      * @note After cleanup, a context is free to be reused if necessary.
00258      * @return Returns APR_ENOTIMPL if not supported.
00259      */
00260     apr_status_t (*shutdown)(void);
00261 
00262     /**
00263      * @brief: fetch the most recent error from this driver.
00264      * @param result - the result structure
00265      * @param f - context pointer
00266      * @return APR_SUCCESS for success.
00267      */
00268     apr_status_t (*error)(const apu_err_t **result, const apr_crypto_t *f);
00269 
00270 };
00271 
00272 #endif
00273 
00274 #ifdef __cplusplus
00275 }
00276 #endif
00277 
00278 #endif
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines