Apache Portable Runtime Utility Library
Defines | Typedefs | Enumerations | Functions
Crypto routines
APR Utility Functions

Defines

#define APU_CRYPTO_RECOMMENDED_DRIVER   "openssl"

Typedefs

typedef struct apr_crypto_driver_t apr_crypto_driver_t
typedef struct apr_crypto_t apr_crypto_t
typedef struct apr_crypto_config_t apr_crypto_config_t
typedef struct apr_crypto_key_t apr_crypto_key_t
typedef struct apr_crypto_block_t apr_crypto_block_t

Enumerations

enum  apr_crypto_block_key_type_e {
  APR_KEY_NONE, APR_KEY_3DES_192, APR_KEY_AES_128, APR_KEY_AES_192,
  APR_KEY_AES_256
}
enum  apr_crypto_block_key_mode_e { APR_MODE_NONE, APR_MODE_ECB, APR_MODE_CBC }

Functions

apr_status_t apr_crypto_init (apr_pool_t *pool)
 Perform once-only initialisation. Call once only.
apr_status_t apr_crypto_clear (apr_pool_t *pool, void *buffer, apr_size_t size)
 Register a cleanup to zero out the buffer provided when the pool is cleaned up.
apr_status_t apr_crypto_get_driver (const apr_crypto_driver_t **driver, const char *name, const char *params, const apu_err_t **result, apr_pool_t *pool)
 Get the driver struct for a name.
const char * apr_crypto_driver_name (const apr_crypto_driver_t *driver)
 Return the name of the driver.
apr_status_t apr_crypto_error (const apu_err_t **result, const apr_crypto_t *f)
 Get the result of the last operation on a context. If the result is NULL, the operation was successful.
apr_status_t apr_crypto_make (apr_crypto_t **f, const apr_crypto_driver_t *driver, const char *params, apr_pool_t *pool)
 Create a context for supporting encryption. Keys, certificates, algorithms and other parameters will be set per context. More than one context can be created at one time. A cleanup will be automatically registered with the given pool to guarantee a graceful shutdown.
apr_status_t apr_crypto_get_block_key_types (apr_hash_t **types, const apr_crypto_t *f)
 Get a hash table of key types, keyed by the name of the type against an integer pointer constant.
apr_status_t apr_crypto_get_block_key_modes (apr_hash_t **modes, const apr_crypto_t *f)
 Get a hash table of key modes, keyed by the name of the mode against an integer pointer constant.
apr_status_t apr_crypto_passphrase (apr_crypto_key_t **key, apr_size_t *ivSize, const char *pass, apr_size_t passLen, const unsigned char *salt, apr_size_t saltLen, const apr_crypto_block_key_type_e type, const apr_crypto_block_key_mode_e mode, const int doPad, const int iterations, const apr_crypto_t *f, apr_pool_t *p)
 Create a key from the given passphrase. By default, the PBKDF2 algorithm is used to generate the key from the passphrase. It is expected that the same pass phrase will generate the same key, regardless of the backend crypto platform used. The key is cleaned up when the context is cleaned, and may be reused with multiple encryption or decryption operations.
apr_status_t apr_crypto_block_encrypt_init (apr_crypto_block_t **ctx, const unsigned char **iv, const apr_crypto_key_t *key, apr_size_t *blockSize, apr_pool_t *p)
 Initialise a context for encrypting arbitrary data using the given key.
apr_status_t apr_crypto_block_encrypt (unsigned char **out, apr_size_t *outlen, const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx)
 Encrypt data provided by in, write it to out.
apr_status_t apr_crypto_block_encrypt_finish (unsigned char *out, apr_size_t *outlen, apr_crypto_block_t *ctx)
 Encrypt final data block, write it to out.
apr_status_t apr_crypto_block_decrypt_init (apr_crypto_block_t **ctx, apr_size_t *blockSize, const unsigned char *iv, const apr_crypto_key_t *key, apr_pool_t *p)
 Initialise a context for decrypting arbitrary data using the given key.
apr_status_t apr_crypto_block_decrypt (unsigned char **out, apr_size_t *outlen, const unsigned char *in, apr_size_t inlen, apr_crypto_block_t *ctx)
 Decrypt data provided by in, write it to out.
apr_status_t apr_crypto_block_decrypt_finish (unsigned char *out, apr_size_t *outlen, apr_crypto_block_t *ctx)
 Decrypt final data block, write it to out.
apr_status_t apr_crypto_block_cleanup (apr_crypto_block_t *ctx)
 Clean encryption / decryption context.
apr_status_t apr_crypto_cleanup (apr_crypto_t *f)
 Clean encryption / decryption context.
apr_status_t apr_crypto_shutdown (const apr_crypto_driver_t *driver)
 Shutdown the crypto library.

Enumeration Type Documentation

Enumerator:
APR_MODE_ECB 

An error condition

APR_MODE_CBC 

Electronic Code Book Cipher Block Chaining

Symmetric Key types understood by the library.

NOTE: It is expected that this list will grow over time.

Interoperability Matrix:

The matrix is based on the testcrypto.c unit test, which attempts to test whether a simple encrypt/decrypt will succeed, as well as testing whether an encrypted string by one library can be decrypted by the others.

Some libraries will successfully encrypt and decrypt their own data, but won't decrypt data from another library. It is hoped that over time these anomalies will be found and fixed, but until then it is recommended that ciphers are chosen that interoperate across platform.

An X below means the test passes, it does not necessarily mean that encryption performed is correct or secure. Applications should stick to ciphers that pass the interoperablity tests on the right hand side of the table.

Aligned data is data whose length is a multiple of the block size for the chosen cipher. Padded data is data that is not aligned by block size and must be padded by the crypto library.

OpenSSL NSS Interop Align Pad Align Pad Align Pad 3DES_192/CBC X X X X X X 3DES_192/ECB X X AES_256/CBC X X X X X X AES_256/ECB X X X X AES_192/CBC X X X X AES_192/ECB X X X AES_128/CBC X X X X AES_128/ECB X X X

Conclusion: for padded data, use 3DES_192/CBC or AES_256/CBC. For aligned data, use 3DES_192/CBC, AES_256/CBC or AES_256/ECB.

Enumerator:
APR_KEY_AES_128 

192 bit (3-Key) 3DES

APR_KEY_AES_192 

128 bit AES

APR_KEY_AES_256 

192 bit AES 256 bit AES


Function Documentation

apr_status_t apr_crypto_block_cleanup ( apr_crypto_block_t *  ctx)

Clean encryption / decryption context.

Note:
After cleanup, a context is free to be reused if necessary.
Parameters:
ctxThe block context to use.
Returns:
Returns APR_ENOTIMPL if not supported.
apr_status_t apr_crypto_block_decrypt ( unsigned char **  out,
apr_size_t *  outlen,
const unsigned char *  in,
apr_size_t  inlen,
apr_crypto_block_t *  ctx 
)

Decrypt data provided by in, write it to out.

Note:
The number of bytes written will be written to outlen. If out is NULL, outlen will contain the maximum size of the buffer needed to hold the data, including any data generated by apr_crypto_block_decrypt_finish below. If *out points to NULL, a buffer sufficiently large will be created from the pool provided. If *out points to a not-NULL value, this value will be used as a buffer instead.
Parameters:
outAddress of a buffer to which data will be written, see note.
outlenLength of the output will be written here.
inAddress of the buffer to read.
inlenLength of the buffer to read.
ctxThe block context to use.
Returns:
APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_block_decrypt_finish ( unsigned char *  out,
apr_size_t *  outlen,
apr_crypto_block_t *  ctx 
)

Decrypt final data block, write it to out.

Note:
If necessary the final block will be written out after being padded. Typically the final block will be written to the same buffer used by apr_crypto_block_decrypt, offset by the number of bytes returned as actually written by the apr_crypto_block_decrypt() call. After this call, the context is cleaned and can be reused by apr_crypto_block_decrypt_init().
Parameters:
outAddress of a buffer to which data will be written. This buffer must already exist, and is usually the same buffer used by apr_evp_crypt(). See note.
outlenLength of the output will be written here.
ctxThe block context to use.
Returns:
APR_ECRYPT if an error occurred.
APR_EPADDING if padding was enabled and the block was incorrectly formatted.
APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_block_decrypt_init ( apr_crypto_block_t **  ctx,
apr_size_t *  blockSize,
const unsigned char *  iv,
const apr_crypto_key_t *  key,
apr_pool_t *  p 
)

Initialise a context for decrypting arbitrary data using the given key.

Note:
If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If *ctx is not NULL, *ctx must point at a previously created structure.
Parameters:
ctxThe block context returned, see note.
blockSizeThe block size of the cipher.
ivOptional initialisation vector.
keyThe key structure to use.
pThe pool to use.
Returns:
Returns APR_ENOIV if an initialisation vector is required but not specified. Returns APR_EINIT if the backend failed to initialise the context. Returns APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_block_encrypt ( unsigned char **  out,
apr_size_t *  outlen,
const unsigned char *  in,
apr_size_t  inlen,
apr_crypto_block_t *  ctx 
)

Encrypt data provided by in, write it to out.

Note:
The number of bytes written will be written to outlen. If out is NULL, outlen will contain the maximum size of the buffer needed to hold the data, including any data generated by apr_crypto_block_encrypt_finish below. If *out points to NULL, a buffer sufficiently large will be created from the pool provided. If *out points to a not-NULL value, this value will be used as a buffer instead.
Parameters:
outAddress of a buffer to which data will be written, see note.
outlenLength of the output will be written here.
inAddress of the buffer to read.
inlenLength of the buffer to read.
ctxThe block context to use.
Returns:
APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_block_encrypt_finish ( unsigned char *  out,
apr_size_t *  outlen,
apr_crypto_block_t *  ctx 
)

Encrypt final data block, write it to out.

Note:
If necessary the final block will be written out after being padded. Typically the final block will be written to the same buffer used by apr_crypto_block_encrypt, offset by the number of bytes returned as actually written by the apr_crypto_block_encrypt() call. After this call, the context is cleaned and can be reused by apr_crypto_block_encrypt_init().
Parameters:
outAddress of a buffer to which data will be written. This buffer must already exist, and is usually the same buffer used by apr_evp_crypt(). See note.
outlenLength of the output will be written here.
ctxThe block context to use.
Returns:
APR_ECRYPT if an error occurred.
APR_EPADDING if padding was enabled and the block was incorrectly formatted.
APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_block_encrypt_init ( apr_crypto_block_t **  ctx,
const unsigned char **  iv,
const apr_crypto_key_t *  key,
apr_size_t *  blockSize,
apr_pool_t *  p 
)

Initialise a context for encrypting arbitrary data using the given key.

Note:
If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If *ctx is not NULL, *ctx must point at a previously created structure.
Parameters:
ctxThe block context returned, see note.
ivOptional initialisation vector. If the buffer pointed to is NULL, an IV will be created at random, in space allocated from the pool. If the buffer pointed to is not NULL, the IV in the buffer will be used.
keyThe key structure to use.
blockSizeThe block size of the cipher.
pThe pool to use.
Returns:
Returns APR_ENOIV if an initialisation vector is required but not specified. Returns APR_EINIT if the backend failed to initialise the context. Returns APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_cleanup ( apr_crypto_t *  f)

Clean encryption / decryption context.

Note:
After cleanup, a context is free to be reused if necessary.
Parameters:
fThe context to use.
Returns:
Returns APR_ENOTIMPL if not supported.
apr_status_t apr_crypto_clear ( apr_pool_t *  pool,
void *  buffer,
apr_size_t  size 
)

Register a cleanup to zero out the buffer provided when the pool is cleaned up.

Parameters:
pool- pool to register the cleanup
buffer- buffer to zero out
size- size of the buffer to zero out
const char* apr_crypto_driver_name ( const apr_crypto_driver_t driver)

Return the name of the driver.

Parameters:
driver- The driver in use.
Returns:
The name of the driver.
apr_status_t apr_crypto_error ( const apu_err_t **  result,
const apr_crypto_t *  f 
)

Get the result of the last operation on a context. If the result is NULL, the operation was successful.

Parameters:
result- the result structure
f- context pointer
Returns:
APR_SUCCESS for success
apr_status_t apr_crypto_get_block_key_modes ( apr_hash_t **  modes,
const apr_crypto_t *  f 
)

Get a hash table of key modes, keyed by the name of the mode against an integer pointer constant.

Parameters:
modes- hashtable of key modes keyed to constants.
f- encryption context
Returns:
APR_SUCCESS for success
apr_status_t apr_crypto_get_block_key_types ( apr_hash_t **  types,
const apr_crypto_t *  f 
)

Get a hash table of key types, keyed by the name of the type against an integer pointer constant.

Parameters:
types- hashtable of key types keyed to constants.
f- encryption context
Returns:
APR_SUCCESS for success
apr_status_t apr_crypto_get_driver ( const apr_crypto_driver_t **  driver,
const char *  name,
const char *  params,
const apu_err_t **  result,
apr_pool_t *  pool 
)

Get the driver struct for a name.

Parameters:
driver- pointer to driver struct.
name- driver name
params- array of initialisation parameters
result- result and error message on failure
pool- (process) pool to register cleanup
Returns:
APR_SUCCESS for success
APR_ENOTIMPL for no driver (when DSO not enabled)
APR_EDSOOPEN if DSO driver file can't be opened
APR_ESYMNOTFOUND if the driver file doesn't contain a driver
Remarks:
NSS: the params can have "dir", "key3", "cert7" and "secmod" keys, each followed by an equal sign and a value. Such key/value pairs can be delimited by space or tab. If the value contains a space, surround the whole key value pair in quotes: "dir=My Directory".
OpenSSL: currently no params are supported.
apr_status_t apr_crypto_init ( apr_pool_t *  pool)

Perform once-only initialisation. Call once only.

Parameters:
pool- pool to register any shutdown cleanups, etc
Returns:
APR_NOTIMPL in case of no crypto support.
apr_status_t apr_crypto_make ( apr_crypto_t **  f,
const apr_crypto_driver_t driver,
const char *  params,
apr_pool_t *  pool 
)

Create a context for supporting encryption. Keys, certificates, algorithms and other parameters will be set per context. More than one context can be created at one time. A cleanup will be automatically registered with the given pool to guarantee a graceful shutdown.

Parameters:
f- context pointer will be written here
driver- driver to use
params- array of key parameters
pool- process pool
Returns:
APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE if the engine cannot be initialised.
Remarks:
NSS: currently no params are supported.
OpenSSL: the params can have "engine" as a key, followed by an equal sign and a value.
apr_status_t apr_crypto_passphrase ( apr_crypto_key_t **  key,
apr_size_t *  ivSize,
const char *  pass,
apr_size_t  passLen,
const unsigned char *  salt,
apr_size_t  saltLen,
const apr_crypto_block_key_type_e  type,
const apr_crypto_block_key_mode_e  mode,
const int  doPad,
const int  iterations,
const apr_crypto_t *  f,
apr_pool_t *  p 
)

Create a key from the given passphrase. By default, the PBKDF2 algorithm is used to generate the key from the passphrase. It is expected that the same pass phrase will generate the same key, regardless of the backend crypto platform used. The key is cleaned up when the context is cleaned, and may be reused with multiple encryption or decryption operations.

Note:
If *key is NULL, a apr_crypto_key_t will be created from a pool. If *key is not NULL, *key must point at a previously created structure.
Parameters:
keyThe key returned, see note.
ivSizeThe size of the initialisation vector will be returned, based on whether an IV is relevant for this type of crypto.
passThe passphrase to use.
passLenThe passphrase length in bytes
saltThe salt to use.
saltLenThe salt length in bytes
type3DES_192, AES_128, AES_192, AES_256.
modeElectronic Code Book / Cipher Block Chaining.
doPadPad if necessary.
iterationsNumber of iterations to use in algorithm
fThe context to use.
pThe pool to use.
Returns:
Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend error occurred while generating the key. APR_ENOCIPHER if the type or mode is not supported by the particular backend. APR_EKEYTYPE if the key type is not known. APR_EPADDING if padding was requested but is not supported. APR_ENOTIMPL if not implemented.
apr_status_t apr_crypto_shutdown ( const apr_crypto_driver_t driver)

Shutdown the crypto library.

Note:
After shutdown, it is expected that the init function can be called again.
Parameters:
driver- driver to use
Returns:
Returns APR_ENOTIMPL if not supported.
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines