Collaboration diagram for Crypto routines:

Data Structures
struct	apr_crypto_block_key_digest_t

struct	apr_crypto_block_key_type_t

struct	apr_crypto_block_key_mode_t

struct	apr_crypto_passphrase_t

struct	apr_crypto_secret_t

struct	apr_crypto_key_hash_t

struct	apr_crypto_key_hmac_t

struct	apr_crypto_key_cmac_t

struct	apr_crypto_digest_hash_t

struct	apr_crypto_digest_sign_t

struct	apr_crypto_digest_verify_t

struct	apr_crypto_key_rec_t

struct	apr_crypto_digest_rec_t

Typedefs
typedef struct apr_crypto_block_key_digest_t	apr_crypto_block_key_digest_t

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

typedef struct apr_crypto_digest_t	apr_crypto_digest_t

typedef struct apr_crypto_block_key_type_t	apr_crypto_block_key_type_t

typedef struct apr_crypto_block_key_mode_t	apr_crypto_block_key_mode_t

typedef struct apr_crypto_passphrase_t	apr_crypto_passphrase_t

typedef struct apr_crypto_secret_t	apr_crypto_secret_t

typedef struct apr_crypto_key_hash_t	apr_crypto_key_hash_t

typedef struct apr_crypto_key_hmac_t	apr_crypto_key_hmac_t

typedef struct apr_crypto_key_cmac_t	apr_crypto_key_cmac_t

typedef struct apr_crypto_digest_hash_t	apr_crypto_digest_hash_t

typedef struct apr_crypto_digest_sign_t	apr_crypto_digest_sign_t

typedef struct apr_crypto_digest_verify_t	apr_crypto_digest_verify_t

typedef struct apr_crypto_key_rec_t	apr_crypto_key_rec_t

typedef struct apr_crypto_digest_rec_t	apr_crypto_digest_rec_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 }

enum	apr_crypto_block_key_digest_e { APR_CRYPTO_DIGEST_NONE , APR_CRYPTO_DIGEST_MD5 , APR_CRYPTO_DIGEST_SHA1 , APR_CRYPTO_DIGEST_SHA224 , APR_CRYPTO_DIGEST_SHA256 , APR_CRYPTO_DIGEST_SHA384 , APR_CRYPTO_DIGEST_SHA512 }

enum	apr_crypto_cipher_e { APR_CRYPTO_CIPHER_AUTO , APR_CRYPTO_CIPHER_AES_256_CTR , APR_CRYPTO_CIPHER_CHACHA20 }

enum	apr_crypto_key_type { APR_CRYPTO_KTYPE_PASSPHRASE = 1 , APR_CRYPTO_KTYPE_SECRET = 2 , APR_CRYPTO_KTYPE_HASH = 3 , APR_CRYPTO_KTYPE_HMAC = 4 , APR_CRYPTO_KTYPE_CMAC = 5 }

enum	apr_crypto_digest_type_e { APR_CRYPTO_DTYPE_HASH = 1 , APR_CRYPTO_DTYPE_SIGN = 2 , APR_CRYPTO_DTYPE_VERIFY = 3 }

Functions
apr_status_t	apr_crypto_init (apr_pool_t *pool)
	Perform once-only initialisation. Call once only. More...

apr_status_t	apr_crypto_lib_version (const char name, const char *version)

apr_status_t	apr_crypto_lib_init (const char name, const char params, const apu_err_t *result, apr_pool_t pool)

apr_status_t	apr_crypto_lib_term (const char *name)

int	apr_crypto_lib_is_active (const char *name)

apr_status_t	apr_crypto_clear (apr_pool_t pool, void buffer, apr_size_t size)
	Zero out the buffer provided when the pool is cleaned up. More...

apr_status_t	apr_crypto_memzero (void *buffer, apr_size_t size)
	Always zero out the buffer provided, without being optimized out by the compiler. More...

int	apr_crypto_equals (const void buf1, const void buf2, apr_size_t size)
	Timing attacks safe buffers comparison, where the executing time does not depend on the bytes compared but solely on the number of bytes. More...

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. More...

const char *	apr_crypto_driver_name (const apr_crypto_driver_t *driver)
	Return the name of the driver. More...

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. More...

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. More...

apr_status_t	apr_crypto_get_block_key_digests (apr_hash_t *digests, const apr_crypto_t f)
	Get a hash table of key digests, keyed by the name of the digest against a pointer to apr_crypto_block_key_digest_t, which in turn begins with an integer. More...

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 a pointer to apr_crypto_block_key_type_t, which in turn begins with an integer. More...

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 a pointer to apr_crypto_block_key_mode_t, which in turn begins with an integer. More...

apr_crypto_key_rec_t *	apr_crypto_key_rec_make (apr_crypto_key_type ktype, apr_pool_t *p)
	Create a key record to be passed to apr_crypto_key(). More...

apr_crypto_digest_rec_t *	apr_crypto_digest_rec_make (apr_crypto_digest_type_e dtype, apr_pool_t *p)
	Create a digest record to be passed to apr_crypto_digest_init(). More...

apr_status_t	apr_crypto_key (apr_crypto_key_t *key, const apr_crypto_key_rec_t rec, const apr_crypto_t f, apr_pool_t p)
	Create a key from the provided secret or passphrase. The key is cleaned up when the context is cleaned, and may be reused with multiple encryption, decryption, signing or verifying operations. The choice of key type much match the intended operation. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

apr_status_t	apr_crypto_block_cleanup (apr_crypto_block_t *ctx)
	Clean encryption / decryption context. More...

apr_status_t	apr_crypto_digest_init (apr_crypto_digest_t *d, const apr_crypto_key_t key, apr_crypto_digest_rec_t rec, apr_pool_t p)
	Initialise a context for hashing, signing or verifying arbitrary data. More...

apr_status_t	apr_crypto_digest_update (apr_crypto_digest_t digest, const unsigned char in, apr_size_t inlen)
	Update the digest with data provided by in. More...

apr_status_t	apr_crypto_digest_final (apr_crypto_digest_t *digest)
	Finalise the digest and write the result. More...

apr_status_t	apr_crypto_digest (const apr_crypto_key_t key, apr_crypto_digest_rec_t rec, const unsigned char in, apr_size_t inlen, apr_pool_t p)
	One shot digest on a single memory buffer. More...

apr_status_t	apr_crypto_digest_cleanup (apr_crypto_digest_t *ctx)
	Clean digest context. More...

apr_status_t	apr_crypto_cleanup (apr_crypto_t *f)
	Clean encryption / decryption context. More...

apr_status_t	apr_crypto_shutdown (const apr_crypto_driver_t *driver)
	Shutdown the crypto library. More...

Detailed Description

Typedef Documentation

◆ apr_crypto_block_key_digest_t

typedef struct apr_crypto_block_key_digest_t apr_crypto_block_key_digest_t

Structure returned by the crypto_get_block_key_digests() function.

◆ apr_crypto_block_key_mode_t

typedef struct apr_crypto_block_key_mode_t apr_crypto_block_key_mode_t

Structure returned by the crypto_get_block_key_modes() function.

◆ apr_crypto_block_key_type_t

typedef struct apr_crypto_block_key_type_t apr_crypto_block_key_type_t

Structure returned by the crypto_get_block_key_types() function.

◆ apr_crypto_block_t

typedef struct apr_crypto_block_t apr_crypto_block_t

Structure representing a block context for encryption, decryption, signing or verifying.

This structure is created using the apr_crypto_block_encrypt_init() and apr_crypto_block_decrypt_init() functions.

◆ apr_crypto_config_t

typedef struct apr_crypto_config_t apr_crypto_config_t

Structure representing the configuration of the given backend crypto library.

◆ apr_crypto_digest_hash_t

typedef struct apr_crypto_digest_hash_t apr_crypto_digest_hash_t

Structure used to create a hashed digest.

Implementations must use apr_crypto_digest_rec_make() to allocate this structure.

◆ apr_crypto_digest_rec_t

typedef struct apr_crypto_digest_rec_t apr_crypto_digest_rec_t

Structure describing a digest to be hashed, signed or verified.

This structure is passed to the apr_crypto_digest_init() and apr_crypto_digest() functions.

Implementations must use apr_crypto_digest_rec_make() to allocate this structure.

◆ apr_crypto_digest_sign_t

typedef struct apr_crypto_digest_sign_t apr_crypto_digest_sign_t

Structure used to create a signature.

Implementations must use apr_crypto_digest_rec_make() to allocate this structure.

◆ apr_crypto_digest_t

typedef struct apr_crypto_digest_t apr_crypto_digest_t

Structure representing a digest context for signing or verifying.

This structure is created using the apr_crypto_digest_init() function.

◆ apr_crypto_digest_verify_t

typedef struct apr_crypto_digest_verify_t apr_crypto_digest_verify_t

Structure used to create a signature for verification.

Implementations must use apr_crypto_digest_rec_make() to allocate this structure.

◆ apr_crypto_driver_t

typedef struct apr_crypto_driver_t apr_crypto_driver_t

Structure representing a backend crypto driver.

This structure is created with apr_crypto_get_driver().

◆ apr_crypto_key_cmac_t

typedef struct apr_crypto_key_cmac_t apr_crypto_key_cmac_t

Structure describing a CMAC key and digest to be generated by the apr_crypto_key() function.

Implementations must use apr_crypto_key_rec_make() to allocate this structure.

◆ apr_crypto_key_hash_t

typedef struct apr_crypto_key_hash_t apr_crypto_key_hash_t

Structure describing a simple digest hash to be generated by the apr_crypto_key() function.

Implementations must use apr_crypto_key_rec_make() to allocate this structure.

◆ apr_crypto_key_hmac_t

typedef struct apr_crypto_key_hmac_t apr_crypto_key_hmac_t

Structure describing a HMAC key and digest to be generated by the apr_crypto_key() function.

Implementations must use apr_crypto_key_rec_make() to allocate this structure.

◆ apr_crypto_key_rec_t

typedef struct apr_crypto_key_rec_t apr_crypto_key_rec_t

Structure describing a key to be generated by the apr_crypto_key() function.

Implementations must use apr_crypto_key_rec_make() to allocate this structure.

◆ apr_crypto_key_t

typedef struct apr_crypto_key_t apr_crypto_key_t

Structure representing a key prepared for encryption, decryption, signing or verifying.

This structure is created using the apr_crypto_key() function.

◆ apr_crypto_passphrase_t

typedef struct apr_crypto_passphrase_t apr_crypto_passphrase_t

Structure describing a key to be derived from PBKDF2 to be passed by the apr_crypto_key() function.

Derived keys are used for encryption and decryption.

Implementations must use apr_crypto_key_rec_make() to allocate this structure.

◆ apr_crypto_secret_t

typedef struct apr_crypto_secret_t apr_crypto_secret_t

Structure describing a raw key to be passed by the apr_crypto_key() function.

Raw keys are used for encryption and decryption, and must match the correct sizes for each cipher.

Implementations must use apr_crypto_key_rec_make() to allocate this structure.

◆ apr_crypto_t

typedef struct apr_crypto_t apr_crypto_t

Structure to support a group of crypto operations.

This structure is created with apr_crypto_make().

Enumeration Type Documentation

◆ apr_crypto_block_key_digest_e

enum apr_crypto_block_key_digest_e

Types of digests supported by the apr_crypto_key() function.

Enumerator
APR_CRYPTO_DIGEST_NONE
APR_CRYPTO_DIGEST_MD5	An error condition
APR_CRYPTO_DIGEST_SHA1	MD5
APR_CRYPTO_DIGEST_SHA224	SHA1
APR_CRYPTO_DIGEST_SHA256	SHA224
APR_CRYPTO_DIGEST_SHA384	SHA256
APR_CRYPTO_DIGEST_SHA512	SHA384

◆ apr_crypto_block_key_mode_e

enum apr_crypto_block_key_mode_e

Types of modes supported by the ciphers.

Enumerator
APR_MODE_NONE
APR_MODE_ECB	An error condition
APR_MODE_CBC	Electronic Code Book Cipher Block Chaining

◆ apr_crypto_block_key_type_e

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    CommonCrypto   NSS       Interop
            Align  Pad  Align  Pad  Align  Pad  Align  Pad

3DES_192/CBC X X X X X X X X 3DES_192/ECB X X X X AES_256/CBC X X X X X X X X AES_256/ECB X X X X X X AES_192/CBC X X X X X X AES_192/ECB X X X X X AES_128/CBC X X X X X X AES_128/ECB X X 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. Types of ciphers.

Enumerator
APR_KEY_NONE
APR_KEY_3DES_192
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

◆ apr_crypto_cipher_e

enum apr_crypto_cipher_e

Types of ciphers supported by the apr_

Enumerator
APR_CRYPTO_CIPHER_AUTO
APR_CRYPTO_CIPHER_AES_256_CTR	Choose the recommended cipher / autodetect the cipher
APR_CRYPTO_CIPHER_CHACHA20	AES 256 - CTR mode

◆ apr_crypto_digest_type_e

enum apr_crypto_digest_type_e

Types of digests supported by the apr_crypto_digest() functions and the apr_crypto_digest_rec_t structure.

Enumerator

APR_CRYPTO_DTYPE_HASH

Simple digest operation.

Use with apr_crypto_key_rec_t APR_CRYPTO_KTYPE_HASH.

APR_CRYPTO_DTYPE_SIGN

Sign operation.

Use with apr_crypto_key_rec_t APR_CRYPTO_KTYPE_HMAC or APR_CRYPTO_KTYPE_CMAC.

APR_CRYPTO_DTYPE_VERIFY

Verify operation.

Use with apr_crypto_key_rec_t APR_CRYPTO_KTYPE_HMAC or APR_CRYPTO_KTYPE_CMAC.

◆ apr_crypto_key_type

enum apr_crypto_key_type

Types of keys supported by the apr_crypto_key() function and the apr_crypto_key_rec_t structure.

Enumerator
APR_CRYPTO_KTYPE_PASSPHRASE	Key is derived from a passphrase. Used with the encrypt / decrypt functions.
APR_CRYPTO_KTYPE_SECRET	Key is derived from a raw key. Used with the encrypt / decrypt functions.
APR_CRYPTO_KTYPE_HASH	Simple digest, no key. Used with the digest functions.
APR_CRYPTO_KTYPE_HMAC	HMAC Key is derived from a raw key. Used with the digest functions.
APR_CRYPTO_KTYPE_CMAC	CMAC Key is derived from a raw key. Used with the digest functions.

Function Documentation

◆ apr_crypto_block_cleanup()

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_crypto_block_decrypt()

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.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_block_decrypt_finish()

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_crypto_block_decrypt(). 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_EINVAL if the key type does not support the given operation.

◆ apr_crypto_block_decrypt_init()

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: APR_ENOIV if an initialisation vector is required but not specified.; APR_EINIT if the backend failed to initialise the context.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_block_encrypt()

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.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_block_encrypt_finish()

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_crypto_block_encrypt(). 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_EINVAL if the key type does not support the given operation.

◆ apr_crypto_block_encrypt_init()

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: APR_ENOIV if an initialisation vector is required but not specified.; APR_EINIT if the backend failed to initialise the context.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_cleanup()

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_crypto_clear()

apr_status_t apr_crypto_clear	(	apr_pool_t *	pool,
		void *	buffer,
		apr_size_t	size
	)

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

◆ apr_crypto_digest()

apr_status_t apr_crypto_digest	(	const apr_crypto_key_t *	key,
		apr_crypto_digest_rec_t *	rec,
		const unsigned char *	in,
		apr_size_t	inlen,
		apr_pool_t *	p
	)

One shot digest on a single memory buffer.

Parameters

key	The key structure to use.
rec	The digest record indicating whether we want to sign or verify. This record contains digest we want to verify against, as well as the signature we have generated. This record will contain the digest calculated.
in	Address of the buffer to digest.
inlen	Length of the buffer to digest.
p	The pool to use.

Returns: APR_ENOIV if an initialisation vector is required but not specified.; APR_EINIT if the backend failed to initialise the context.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_digest_cleanup()

apr_status_t apr_crypto_digest_cleanup ( apr_crypto_digest_t * ctx )

Clean digest context.

Note: After cleanup, a digest context is free to be reused if necessary.

Parameters

ctx	The digest context to use.

Returns: Returns APR_ENOTIMPL if not supported.

◆ apr_crypto_digest_final()

apr_status_t apr_crypto_digest_final ( apr_crypto_digest_t * digest )

Finalise the digest and write the result.

   The result is written to the apr_crypto_digest_rec_t structure
   passed into apr_crypto_digest_init().

   If verification is requested, this function will return the
   result of the verification.

Note: After this call, the context is cleaned and can be reused by apr_crypto_digest_init().

Parameters

digest The digest context to use.

Returns: APR_SUCCESS if hash, signing or verification was successful.; APR_ENOVERIFY if the verification failed.; APR_ECRYPT if an error occurred.; APR_EPADDING if padding was enabled and the block was incorrectly formatted.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_digest_init()

apr_status_t apr_crypto_digest_init	(	apr_crypto_digest_t **	d,
		const apr_crypto_key_t *	key,
		apr_crypto_digest_rec_t *	rec,
		apr_pool_t *	p
	)

Initialise a context for hashing, signing or verifying arbitrary data.

This function supports:

Simple hashing (MD5, SHA1, SHA224, SHA256, SHA384, SHA512).
HMAC (with a secret key)
CMAC (with a secret key)

Details of the key and the type of digest to be performed are passed in the constant apr_crypto_key_t structure, which can be reused by many calls to apr_crypto_digest_init().

Details of this particular operation are read from and written to the apr_crypto_digest_rec_t structure, which is expected to contain the message digest to be verified, as well as message digest generated during the hashing or signing process. This structure will be modified by each digest operation, and cannot be shared.

Note: If *d is NULL, a apr_crypto_digest_t will be created from a pool. If *d is not NULL, *d must point at a previously created structure.

Parameters

d	The digest context returned, see note.
key	The key structure to use.
rec	The digest record indicating whether we want to sign or verify. This record contains digest we want to verify against, as well as the signature we have generated.
p	The pool to use.

Returns: APR_SUCCESS if successful.; APR_ENOIV if an initialisation vector is required but not specified.; APR_EINIT if the backend failed to initialise the context.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_digest_rec_make()

apr_crypto_digest_rec_t* apr_crypto_digest_rec_make	(	apr_crypto_digest_type_e	dtype,
		apr_pool_t *	p
	)

Create a digest record to be passed to apr_crypto_digest_init().

Parameters

dtype	The type of digest record to create.
p	The pool to use.

Returns: Returns a blank structure of the correct size.

◆ apr_crypto_digest_update()

apr_status_t apr_crypto_digest_update	(	apr_crypto_digest_t *	digest,
		const unsigned char *	in,
		apr_size_t	inlen
	)

Update the digest with data provided by in.

Parameters

digest	The block context to use.
in	Address of the buffer to digest.
inlen	Length of the buffer to digest.

Returns: APR_SUCCESS if successful.; APR_ECRYPT if an error occurred.; APR_ENOTIMPL if not implemented.; APR_EINVAL if the key type does not support the given operation.

◆ apr_crypto_driver_name()

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_crypto_equals()

int apr_crypto_equals	(	const void *	buf1,
		const void *	buf2,
		apr_size_t	size
	)

Timing attacks safe buffers comparison, where the executing time does not depend on the bytes compared but solely on the number of bytes.

Parameters

buf1	- first buffer to compare
buf2	- second buffer to compare
size	- size of the buffers to compare

Returns: 1 if the buffers are equals, 0 otherwise.

◆ apr_crypto_error()

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_crypto_get_block_key_digests()

apr_status_t apr_crypto_get_block_key_digests	(	apr_hash_t **	digests,
		const apr_crypto_t *	f
	)

Get a hash table of key digests, keyed by the name of the digest against a pointer to apr_crypto_block_key_digest_t, which in turn begins with an integer.

Parameters

digests	- hashtable of key digests keyed to constants.
f	- encryption context

Returns: APR_SUCCESS for success

◆ apr_crypto_get_block_key_modes()

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 a pointer to apr_crypto_block_key_mode_t, which in turn begins with an integer.

Parameters

modes	- hashtable of key modes keyed to constants.
f	- encryption context

Returns: APR_SUCCESS for success

◆ apr_crypto_get_block_key_types()

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 a pointer to apr_crypto_block_key_type_t, which in turn begins with an integer.

Parameters

types	- hashtable of key types keyed to constants.
f	- encryption context

Returns: APR_SUCCESS for success

◆ apr_crypto_get_driver()

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_crypto_init()

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_ENOTIMPL in case of no crypto support.

◆ apr_crypto_key()

apr_status_t apr_crypto_key	(	apr_crypto_key_t **	key,
		const apr_crypto_key_rec_t *	rec,
		const apr_crypto_t *	f,
		apr_pool_t *	p
	)

Create a key from the provided secret or passphrase. The key is cleaned up when the context is cleaned, and may be reused with multiple encryption, decryption, signing or verifying operations. The choice of key type much match the intended operation.

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.
rec	The key record, from which the key will be derived.
f	The context to use.
p	The pool to use.

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_crypto_key_rec_make()

apr_crypto_key_rec_t* apr_crypto_key_rec_make	(	apr_crypto_key_type	ktype,
		apr_pool_t *	p
	)

Create a key record to be passed to apr_crypto_key().

Parameters

ktype	The apr_crypto_key_type to use.
p	The pool to use.

Returns: Returns a blank structure of the correct size.

◆ apr_crypto_lib_init()

apr_status_t apr_crypto_lib_init	(	const char *	name,
		const char *	params,
		const apu_err_t **	result,
		apr_pool_t *	pool
	)

◆ apr_crypto_lib_is_active()

int apr_crypto_lib_is_active ( const char * name )

◆ apr_crypto_lib_term()

apr_status_t apr_crypto_lib_term ( const char * name )

◆ apr_crypto_lib_version()

apr_status_t apr_crypto_lib_version	(	const char *	name,
		const char **	version
	)

◆ apr_crypto_make()

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_crypto_memzero()

apr_status_t apr_crypto_memzero	(	void *	buffer,
		apr_size_t	size
	)

Always zero out the buffer provided, without being optimized out by the compiler.

Parameters

buffer	- buffer to zero out
size	- size of the buffer to zero out

◆ apr_crypto_passphrase()

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: 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.

Deprecated:: Replaced by apr_crypto_key().

◆ apr_crypto_shutdown()

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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ apr_crypto_block_key_digest_t

◆ apr_crypto_block_key_mode_t

◆ apr_crypto_block_key_type_t

◆ apr_crypto_block_t

◆ apr_crypto_config_t

◆ apr_crypto_digest_hash_t

◆ apr_crypto_digest_rec_t

◆ apr_crypto_digest_sign_t

◆ apr_crypto_digest_t

◆ apr_crypto_digest_verify_t

◆ apr_crypto_driver_t

◆ apr_crypto_key_cmac_t

◆ apr_crypto_key_hash_t

◆ apr_crypto_key_hmac_t

◆ apr_crypto_key_rec_t

◆ apr_crypto_key_t

◆ apr_crypto_passphrase_t

◆ apr_crypto_secret_t

◆ apr_crypto_t

Enumeration Type Documentation

◆ apr_crypto_block_key_digest_e

◆ apr_crypto_block_key_mode_e

◆ apr_crypto_block_key_type_e

◆ apr_crypto_cipher_e

◆ apr_crypto_digest_type_e

◆ apr_crypto_key_type

Function Documentation

◆ apr_crypto_block_cleanup()

◆ apr_crypto_block_decrypt()

◆ apr_crypto_block_decrypt_finish()

◆ apr_crypto_block_decrypt_init()

◆ apr_crypto_block_encrypt()

◆ apr_crypto_block_encrypt_finish()

◆ apr_crypto_block_encrypt_init()

◆ apr_crypto_cleanup()

◆ apr_crypto_clear()

◆ apr_crypto_digest()

◆ apr_crypto_digest_cleanup()

◆ apr_crypto_digest_final()

◆ apr_crypto_digest_init()

◆ apr_crypto_digest_rec_make()

◆ apr_crypto_digest_update()

◆ apr_crypto_driver_name()

◆ apr_crypto_equals()

◆ apr_crypto_error()

◆ apr_crypto_get_block_key_digests()

◆ apr_crypto_get_block_key_modes()

◆ apr_crypto_get_block_key_types()

◆ apr_crypto_get_driver()

◆ apr_crypto_init()

◆ apr_crypto_key()

◆ apr_crypto_key_rec_make()

◆ apr_crypto_lib_init()

◆ apr_crypto_lib_is_active()

◆ apr_crypto_lib_term()

◆ apr_crypto_lib_version()

◆ apr_crypto_make()

◆ apr_crypto_memzero()

◆ apr_crypto_passphrase()

◆ apr_crypto_shutdown()