Annotation of win32/apache22/srclib/apr-util/include/apr_crypto.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_H
! 18: #define APR_CRYPTO_H
! 19:
! 20: #include "apu.h"
! 21: #include "apr_pools.h"
! 22: #include "apr_tables.h"
! 23: #include "apr_hash.h"
! 24: #include "apu_errno.h"
! 25:
! 26: #ifdef __cplusplus
! 27: extern "C" {
! 28: #endif
! 29:
! 30: /**
! 31: * @file apr_crypto.h
! 32: * @brief APR-UTIL Crypto library
! 33: */
! 34: /**
! 35: * @defgroup APR_Util_Crypto Crypto routines
! 36: * @ingroup APR_Util
! 37: * @{
! 38: */
! 39:
! 40: #if APU_HAVE_CRYPTO
! 41:
! 42: #ifndef APU_CRYPTO_RECOMMENDED_DRIVER
! 43: #if APU_HAVE_OPENSSL
! 44: #define APU_CRYPTO_RECOMMENDED_DRIVER "openssl"
! 45: #else
! 46: #if APU_HAVE_NSS
! 47: #define APU_CRYPTO_RECOMMENDED_DRIVER "nss"
! 48: #else
! 49: #if APU_HAVE_MSCNG
! 50: #define APU_CRYPTO_RECOMMENDED_DRIVER "mscng"
! 51: #else
! 52: #if APU_HAVE_MSCAPI
! 53: #define APU_CRYPTO_RECOMMENDED_DRIVER "mscapi"
! 54: #else
! 55: #endif
! 56: #endif
! 57: #endif
! 58: #endif
! 59: #endif
! 60:
! 61: /**
! 62: * Symmetric Key types understood by the library.
! 63: *
! 64: * NOTE: It is expected that this list will grow over time.
! 65: *
! 66: * Interoperability Matrix:
! 67: *
! 68: * The matrix is based on the testcrypto.c unit test, which attempts to
! 69: * test whether a simple encrypt/decrypt will succeed, as well as testing
! 70: * whether an encrypted string by one library can be decrypted by the
! 71: * others.
! 72: *
! 73: * Some libraries will successfully encrypt and decrypt their own data,
! 74: * but won't decrypt data from another library. It is hoped that over
! 75: * time these anomalies will be found and fixed, but until then it is
! 76: * recommended that ciphers are chosen that interoperate across platform.
! 77: *
! 78: * An X below means the test passes, it does not necessarily mean that
! 79: * encryption performed is correct or secure. Applications should stick
! 80: * to ciphers that pass the interoperablity tests on the right hand side
! 81: * of the table.
! 82: *
! 83: * Aligned data is data whose length is a multiple of the block size for
! 84: * the chosen cipher. Padded data is data that is not aligned by block
! 85: * size and must be padded by the crypto library.
! 86: *
! 87: * OpenSSL NSS Interop
! 88: * Align Pad Align Pad Align Pad
! 89: * 3DES_192/CBC X X X X X X
! 90: * 3DES_192/ECB X X
! 91: * AES_256/CBC X X X X X X
! 92: * AES_256/ECB X X X X
! 93: * AES_192/CBC X X X X
! 94: * AES_192/ECB X X X
! 95: * AES_128/CBC X X X X
! 96: * AES_128/ECB X X X
! 97: *
! 98: * Conclusion: for padded data, use 3DES_192/CBC or AES_256/CBC. For
! 99: * aligned data, use 3DES_192/CBC, AES_256/CBC or AES_256/ECB.
! 100: */
! 101:
! 102: typedef enum
! 103: {
! 104: APR_KEY_NONE, APR_KEY_3DES_192, /** 192 bit (3-Key) 3DES */
! 105: APR_KEY_AES_128, /** 128 bit AES */
! 106: APR_KEY_AES_192, /** 192 bit AES */
! 107: APR_KEY_AES_256
! 108: /** 256 bit AES */
! 109: } apr_crypto_block_key_type_e;
! 110:
! 111: typedef enum
! 112: {
! 113: APR_MODE_NONE, /** An error condition */
! 114: APR_MODE_ECB, /** Electronic Code Book */
! 115: APR_MODE_CBC
! 116: /** Cipher Block Chaining */
! 117: } apr_crypto_block_key_mode_e;
! 118:
! 119: /* These are opaque structs. Instantiation is up to each backend */
! 120: typedef struct apr_crypto_driver_t apr_crypto_driver_t;
! 121: typedef struct apr_crypto_t apr_crypto_t;
! 122: typedef struct apr_crypto_config_t apr_crypto_config_t;
! 123: typedef struct apr_crypto_key_t apr_crypto_key_t;
! 124: typedef struct apr_crypto_block_t apr_crypto_block_t;
! 125:
! 126: /**
! 127: * @brief Perform once-only initialisation. Call once only.
! 128: *
! 129: * @param pool - pool to register any shutdown cleanups, etc
! 130: * @return APR_NOTIMPL in case of no crypto support.
! 131: */
! 132: APU_DECLARE(apr_status_t) apr_crypto_init(apr_pool_t *pool);
! 133:
! 134: /**
! 135: * @brief Register a cleanup to zero out the buffer provided
! 136: * when the pool is cleaned up.
! 137: *
! 138: * @param pool - pool to register the cleanup
! 139: * @param buffer - buffer to zero out
! 140: * @param size - size of the buffer to zero out
! 141: */
! 142: APU_DECLARE(apr_status_t) apr_crypto_clear(apr_pool_t *pool, void *buffer,
! 143: apr_size_t size);
! 144:
! 145: /**
! 146: * @brief Get the driver struct for a name
! 147: *
! 148: * @param driver - pointer to driver struct.
! 149: * @param name - driver name
! 150: * @param params - array of initialisation parameters
! 151: * @param result - result and error message on failure
! 152: * @param pool - (process) pool to register cleanup
! 153: * @return APR_SUCCESS for success
! 154: * @return APR_ENOTIMPL for no driver (when DSO not enabled)
! 155: * @return APR_EDSOOPEN if DSO driver file can't be opened
! 156: * @return APR_ESYMNOTFOUND if the driver file doesn't contain a driver
! 157: * @remarks NSS: the params can have "dir", "key3", "cert7" and "secmod"
! 158: * keys, each followed by an equal sign and a value. Such key/value pairs can
! 159: * be delimited by space or tab. If the value contains a space, surround the
! 160: * whole key value pair in quotes: "dir=My Directory".
! 161: * @remarks OpenSSL: currently no params are supported.
! 162: */
! 163: APU_DECLARE(apr_status_t) apr_crypto_get_driver(
! 164: const apr_crypto_driver_t **driver,
! 165: const char *name, const char *params, const apu_err_t **result,
! 166: apr_pool_t *pool);
! 167:
! 168: /**
! 169: * @brief Return the name of the driver.
! 170: *
! 171: * @param driver - The driver in use.
! 172: * @return The name of the driver.
! 173: */
! 174: APU_DECLARE(const char *) apr_crypto_driver_name(
! 175: const apr_crypto_driver_t *driver);
! 176:
! 177: /**
! 178: * @brief Get the result of the last operation on a context. If the result
! 179: * is NULL, the operation was successful.
! 180: * @param result - the result structure
! 181: * @param f - context pointer
! 182: * @return APR_SUCCESS for success
! 183: */
! 184: APU_DECLARE(apr_status_t) apr_crypto_error(const apu_err_t **result,
! 185: const apr_crypto_t *f);
! 186:
! 187: /**
! 188: * @brief Create a context for supporting encryption. Keys, certificates,
! 189: * algorithms and other parameters will be set per context. More than
! 190: * one context can be created at one time. A cleanup will be automatically
! 191: * registered with the given pool to guarantee a graceful shutdown.
! 192: * @param f - context pointer will be written here
! 193: * @param driver - driver to use
! 194: * @param params - array of key parameters
! 195: * @param pool - process pool
! 196: * @return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE
! 197: * if the engine cannot be initialised.
! 198: * @remarks NSS: currently no params are supported.
! 199: * @remarks OpenSSL: the params can have "engine" as a key, followed by an equal
! 200: * sign and a value.
! 201: */
! 202: APU_DECLARE(apr_status_t) apr_crypto_make(apr_crypto_t **f,
! 203: const apr_crypto_driver_t *driver, const char *params,
! 204: apr_pool_t *pool);
! 205:
! 206: /**
! 207: * @brief Get a hash table of key types, keyed by the name of the type against
! 208: * an integer pointer constant.
! 209: *
! 210: * @param types - hashtable of key types keyed to constants.
! 211: * @param f - encryption context
! 212: * @return APR_SUCCESS for success
! 213: */
! 214: APU_DECLARE(apr_status_t) apr_crypto_get_block_key_types(apr_hash_t **types,
! 215: const apr_crypto_t *f);
! 216:
! 217: /**
! 218: * @brief Get a hash table of key modes, keyed by the name of the mode against
! 219: * an integer pointer constant.
! 220: *
! 221: * @param modes - hashtable of key modes keyed to constants.
! 222: * @param f - encryption context
! 223: * @return APR_SUCCESS for success
! 224: */
! 225: APU_DECLARE(apr_status_t) apr_crypto_get_block_key_modes(apr_hash_t **modes,
! 226: const apr_crypto_t *f);
! 227:
! 228: /**
! 229: * @brief Create a key from the given passphrase. By default, the PBKDF2
! 230: * algorithm is used to generate the key from the passphrase. It is expected
! 231: * that the same pass phrase will generate the same key, regardless of the
! 232: * backend crypto platform used. The key is cleaned up when the context
! 233: * is cleaned, and may be reused with multiple encryption or decryption
! 234: * operations.
! 235: * @note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
! 236: * *key is not NULL, *key must point at a previously created structure.
! 237: * @param key The key returned, see note.
! 238: * @param ivSize The size of the initialisation vector will be returned, based
! 239: * on whether an IV is relevant for this type of crypto.
! 240: * @param pass The passphrase to use.
! 241: * @param passLen The passphrase length in bytes
! 242: * @param salt The salt to use.
! 243: * @param saltLen The salt length in bytes
! 244: * @param type 3DES_192, AES_128, AES_192, AES_256.
! 245: * @param mode Electronic Code Book / Cipher Block Chaining.
! 246: * @param doPad Pad if necessary.
! 247: * @param iterations Number of iterations to use in algorithm
! 248: * @param f The context to use.
! 249: * @param p The pool to use.
! 250: * @return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
! 251: * error occurred while generating the key. APR_ENOCIPHER if the type or mode
! 252: * is not supported by the particular backend. APR_EKEYTYPE if the key type is
! 253: * not known. APR_EPADDING if padding was requested but is not supported.
! 254: * APR_ENOTIMPL if not implemented.
! 255: */
! 256: APU_DECLARE(apr_status_t) apr_crypto_passphrase(apr_crypto_key_t **key,
! 257: apr_size_t *ivSize, const char *pass, apr_size_t passLen,
! 258: const unsigned char * salt, apr_size_t saltLen,
! 259: const apr_crypto_block_key_type_e type,
! 260: const apr_crypto_block_key_mode_e mode, const int doPad,
! 261: const int iterations, const apr_crypto_t *f, apr_pool_t *p);
! 262:
! 263: /**
! 264: * @brief Initialise a context for encrypting arbitrary data using the given key.
! 265: * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
! 266: * *ctx is not NULL, *ctx must point at a previously created structure.
! 267: * @param ctx The block context returned, see note.
! 268: * @param iv Optional initialisation vector. If the buffer pointed to is NULL,
! 269: * an IV will be created at random, in space allocated from the pool.
! 270: * If the buffer pointed to is not NULL, the IV in the buffer will be
! 271: * used.
! 272: * @param key The key structure to use.
! 273: * @param blockSize The block size of the cipher.
! 274: * @param p The pool to use.
! 275: * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
! 276: * Returns APR_EINIT if the backend failed to initialise the context. Returns
! 277: * APR_ENOTIMPL if not implemented.
! 278: */
! 279: APU_DECLARE(apr_status_t) apr_crypto_block_encrypt_init(
! 280: apr_crypto_block_t **ctx, const unsigned char **iv,
! 281: const apr_crypto_key_t *key, apr_size_t *blockSize, apr_pool_t *p);
! 282:
! 283: /**
! 284: * @brief Encrypt data provided by in, write it to out.
! 285: * @note The number of bytes written will be written to outlen. If
! 286: * out is NULL, outlen will contain the maximum size of the
! 287: * buffer needed to hold the data, including any data
! 288: * generated by apr_crypto_block_encrypt_finish below. If *out points
! 289: * to NULL, a buffer sufficiently large will be created from
! 290: * the pool provided. If *out points to a not-NULL value, this
! 291: * value will be used as a buffer instead.
! 292: * @param out Address of a buffer to which data will be written,
! 293: * see note.
! 294: * @param outlen Length of the output will be written here.
! 295: * @param in Address of the buffer to read.
! 296: * @param inlen Length of the buffer to read.
! 297: * @param ctx The block context to use.
! 298: * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
! 299: * not implemented.
! 300: */
! 301: APU_DECLARE(apr_status_t) apr_crypto_block_encrypt(unsigned char **out,
! 302: apr_size_t *outlen, const unsigned char *in, apr_size_t inlen,
! 303: apr_crypto_block_t *ctx);
! 304:
! 305: /**
! 306: * @brief Encrypt final data block, write it to out.
! 307: * @note If necessary the final block will be written out after being
! 308: * padded. Typically the final block will be written to the
! 309: * same buffer used by apr_crypto_block_encrypt, offset by the
! 310: * number of bytes returned as actually written by the
! 311: * apr_crypto_block_encrypt() call. After this call, the context
! 312: * is cleaned and can be reused by apr_crypto_block_encrypt_init().
! 313: * @param out Address of a buffer to which data will be written. This
! 314: * buffer must already exist, and is usually the same
! 315: * buffer used by apr_evp_crypt(). See note.
! 316: * @param outlen Length of the output will be written here.
! 317: * @param ctx The block context to use.
! 318: * @return APR_ECRYPT if an error occurred.
! 319: * @return APR_EPADDING if padding was enabled and the block was incorrectly
! 320: * formatted.
! 321: * @return APR_ENOTIMPL if not implemented.
! 322: */
! 323: APU_DECLARE(apr_status_t) apr_crypto_block_encrypt_finish(unsigned char *out,
! 324: apr_size_t *outlen, apr_crypto_block_t *ctx);
! 325:
! 326: /**
! 327: * @brief Initialise a context for decrypting arbitrary data using the given key.
! 328: * @note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
! 329: * *ctx is not NULL, *ctx must point at a previously created structure.
! 330: * @param ctx The block context returned, see note.
! 331: * @param blockSize The block size of the cipher.
! 332: * @param iv Optional initialisation vector.
! 333: * @param key The key structure to use.
! 334: * @param p The pool to use.
! 335: * @return Returns APR_ENOIV if an initialisation vector is required but not specified.
! 336: * Returns APR_EINIT if the backend failed to initialise the context. Returns
! 337: * APR_ENOTIMPL if not implemented.
! 338: */
! 339: APU_DECLARE(apr_status_t) apr_crypto_block_decrypt_init(
! 340: apr_crypto_block_t **ctx, apr_size_t *blockSize,
! 341: const unsigned char *iv, const apr_crypto_key_t *key, apr_pool_t *p);
! 342:
! 343: /**
! 344: * @brief Decrypt data provided by in, write it to out.
! 345: * @note The number of bytes written will be written to outlen. If
! 346: * out is NULL, outlen will contain the maximum size of the
! 347: * buffer needed to hold the data, including any data
! 348: * generated by apr_crypto_block_decrypt_finish below. If *out points
! 349: * to NULL, a buffer sufficiently large will be created from
! 350: * the pool provided. If *out points to a not-NULL value, this
! 351: * value will be used as a buffer instead.
! 352: * @param out Address of a buffer to which data will be written,
! 353: * see note.
! 354: * @param outlen Length of the output will be written here.
! 355: * @param in Address of the buffer to read.
! 356: * @param inlen Length of the buffer to read.
! 357: * @param ctx The block context to use.
! 358: * @return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
! 359: * not implemented.
! 360: */
! 361: APU_DECLARE(apr_status_t) apr_crypto_block_decrypt(unsigned char **out,
! 362: apr_size_t *outlen, const unsigned char *in, apr_size_t inlen,
! 363: apr_crypto_block_t *ctx);
! 364:
! 365: /**
! 366: * @brief Decrypt final data block, write it to out.
! 367: * @note If necessary the final block will be written out after being
! 368: * padded. Typically the final block will be written to the
! 369: * same buffer used by apr_crypto_block_decrypt, offset by the
! 370: * number of bytes returned as actually written by the
! 371: * apr_crypto_block_decrypt() call. After this call, the context
! 372: * is cleaned and can be reused by apr_crypto_block_decrypt_init().
! 373: * @param out Address of a buffer to which data will be written. This
! 374: * buffer must already exist, and is usually the same
! 375: * buffer used by apr_evp_crypt(). See note.
! 376: * @param outlen Length of the output will be written here.
! 377: * @param ctx The block context to use.
! 378: * @return APR_ECRYPT if an error occurred.
! 379: * @return APR_EPADDING if padding was enabled and the block was incorrectly
! 380: * formatted.
! 381: * @return APR_ENOTIMPL if not implemented.
! 382: */
! 383: APU_DECLARE(apr_status_t) apr_crypto_block_decrypt_finish(unsigned char *out,
! 384: apr_size_t *outlen, apr_crypto_block_t *ctx);
! 385:
! 386: /**
! 387: * @brief Clean encryption / decryption context.
! 388: * @note After cleanup, a context is free to be reused if necessary.
! 389: * @param ctx The block context to use.
! 390: * @return Returns APR_ENOTIMPL if not supported.
! 391: */
! 392: APU_DECLARE(apr_status_t) apr_crypto_block_cleanup(apr_crypto_block_t *ctx);
! 393:
! 394: /**
! 395: * @brief Clean encryption / decryption context.
! 396: * @note After cleanup, a context is free to be reused if necessary.
! 397: * @param f The context to use.
! 398: * @return Returns APR_ENOTIMPL if not supported.
! 399: */
! 400: APU_DECLARE(apr_status_t) apr_crypto_cleanup(apr_crypto_t *f);
! 401:
! 402: /**
! 403: * @brief Shutdown the crypto library.
! 404: * @note After shutdown, it is expected that the init function can be called again.
! 405: * @param driver - driver to use
! 406: * @return Returns APR_ENOTIMPL if not supported.
! 407: */
! 408: APU_DECLARE(apr_status_t) apr_crypto_shutdown(
! 409: const apr_crypto_driver_t *driver);
! 410:
! 411: #endif /* APU_HAVE_CRYPTO */
! 412:
! 413: /** @} */
! 414:
! 415: #ifdef __cplusplus
! 416: }
! 417: #endif
! 418:
! 419: #endif
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_crypto.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