Apache2
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_tapr_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_tapr_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

Structure returned by the crypto_get_block_key_digests() function.

◆ apr_crypto_block_key_mode_t

Structure returned by the crypto_get_block_key_modes() function.

◆ apr_crypto_block_key_type_t

Structure returned by the crypto_get_block_key_types() function.

◆ 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

Structure representing the configuration of the given backend crypto library.

◆ 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

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

Structure used to create a signature.

Implementations must use apr_crypto_digest_rec_make() to allocate this structure.

◆ 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

Structure used to create a signature for verification.

Implementations must use apr_crypto_digest_rec_make() to allocate this structure.

◆ apr_crypto_driver_t

Structure representing a backend crypto driver.

This structure is created with apr_crypto_get_driver().

◆ 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

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

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

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

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

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

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

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

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

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

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

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

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
ctxThe 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
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.
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
outAddress 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.
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_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
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
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
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.
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
outAddress 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.
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_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
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
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
fThe 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
keyThe key structure to use.
recThe 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.
inAddress of the buffer to digest.
inlenLength of the buffer to digest.
pThe 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
ctxThe 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
digestThe 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
dThe digest context returned, see note.
keyThe key structure to use.
recThe 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.
pThe 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
dtypeThe type of digest record to create.
pThe 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
digestThe block context to use.
inAddress of the buffer to digest.
inlenLength 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
keyThe key returned, see note.
recThe key record, from which the key will be derived.
fThe context to use.
pThe 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
ktypeThe apr_crypto_key_type to use.
pThe 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
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
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.