Annotation of win32/apache22/srclib/apr-util/include/private/apr_crypto_internal.h, revision 1.1
1.1 ! moko 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
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_crypto_internal.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr-util / include / private