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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.