Crypto routines

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

enum apr_crypto_block_key_mode_e

Enumerator:

APR_MODE_ECB	An error condition
APR_MODE_CBC	Electronic Code Book Cipher Block Chaining

enum apr_crypto_block_key_type_e

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:

ctx	The 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:

out	Address of a buffer to which data will be written, see note.
outlen	Length of the output will be written here.
in	Address of the buffer to read.
inlen	Length of the buffer to read.
ctx	The 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:

out	Address 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.
outlen	Length of the output will be written here.
ctx	The 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:

ctx	The block context returned, see note.
blockSize	The block size of the cipher.
iv	Optional initialisation vector.
key	The key structure to use.
p	The 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:

out	Address of a buffer to which data will be written, see note.
outlen	Length of the output will be written here.
in	Address of the buffer to read.
inlen	Length of the buffer to read.
ctx	The 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:

out	Address 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.
outlen	Length of the output will be written here.
ctx	The 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:

ctx	The block context returned, see note.
iv	Optional 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.
key	The key structure to use.
blockSize	The block size of the cipher.
p	The 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:

f	The 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:

key	The key returned, see note.
ivSize	The size of the initialisation vector will be returned, based on whether an IV is relevant for this type of crypto.
pass	The passphrase to use.
passLen	The passphrase length in bytes
salt	The salt to use.
saltLen	The salt length in bytes
type	3DES_192, AES_128, AES_192, AES_256.
mode	Electronic Code Book / Cipher Block Chaining.
doPad	Pad if necessary.
iterations	Number of iterations to use in algorithm
f	The context to use.
p	The 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.