Wickr_crypto_engine

Data Structures
struct	wickr_crypto_engine
	Interface to a set of cryptographic operations used throughout the library. Currently the default implementation of this can be found along with documentation in openssl_suite.h and kdf.h. More...

Functions
const wickr_crypto_engine_t	wickr_crypto_engine_get_default (void)
wickr_buffer_t *	wickr_crypto_engine_kdf_cipher (const wickr_crypto_engine_t *engine, wickr_kdf_algo_t algo, wickr_cipher_t cipher, const wickr_buffer_t *value, const wickr_buffer_t *passphrase)
wickr_buffer_t *	wickr_crypto_engine_kdf_decipher (const wickr_crypto_engine_t *engine, const wickr_buffer_t *input_buffer, const wickr_buffer_t *passphrase)
wickr_digest_t	wickr_digest_matching_cipher (wickr_cipher_t cipher)
wickr_digest_t	wickr_digest_matching_curve (wickr_ec_curve_t curve)
wickr_cipher_t	wickr_exchange_cipher_matching_cipher (wickr_cipher_t cipher)

Variables
wickr_buffer_t *(*	wickr_crypto_engine::wickr_crypto_engine_crypto_random )(size_t len)
wickr_cipher_key_t *(*	wickr_crypto_engine::wickr_crypto_engine_cipher_key_random )(wickr_cipher_t cipher)
wickr_cipher_result_t *(*	wickr_crypto_engine::wickr_crypto_engine_cipher_encrypt )(const wickr_buffer_t *plaintext, const wickr_buffer_t *aad, const wickr_cipher_key_t *key, const wickr_buffer_t *iv)
wickr_buffer_t *(*	wickr_crypto_engine::wickr_crypto_engine_cipher_decrypt )(const wickr_cipher_result_t *cipher_result, const wickr_buffer_t *aad, const wickr_cipher_key_t *key, bool only_auth_ciphers)
bool(*	wickr_crypto_engine::wickr_crypto_engine_encrypt_file )(const wickr_cipher_key_t *key, const char *sourceFilePath, const char *destinationFilePath)
bool(*	wickr_crypto_engine::wickr_crypto_engine_decrypt_file )(const wickr_cipher_key_t *key, const char *sourceFilePath, const char *destinationFilePath, bool only_auth_ciphers)
bool(*	wickr_crypto_engine::wickr_crypto_engine_encrypt_ofile )(FILE *fin, const wickr_cipher_key_t *key, FILE *fout)
bool(*	wickr_crypto_engine::wickr_crypto_engine_decrypt_ofile )(FILE *fin, const wickr_cipher_key_t *key, FILE *fout, bool only_auth_ciphers)
wickr_buffer_t *(*	wickr_crypto_engine::wickr_crypto_engine_digest )(const wickr_buffer_t *buffer, const wickr_buffer_t *salt, wickr_digest_t digest_mode)
wickr_buffer_t *(*	wickr_crypto_engine::wickr_crypto_engine_digest_file )(FILE *in_file, const wickr_digest_t mode)
wickr_ec_key_t *(*	wickr_crypto_engine::wickr_crypto_engine_ec_rand_key )(wickr_ec_curve_t curve)
wickr_ec_key_t *(*	wickr_crypto_engine::wickr_crypto_engine_ec_key_import )(const wickr_buffer_t *buffer, bool is_private)
wickr_ecdsa_result_t *(*	wickr_crypto_engine::wickr_crypto_engine_ec_sign )(const wickr_ec_key_t *ec_signing_key, const wickr_buffer_t *data_to_sign, const wickr_digest_t digest_mode)
bool(*	wickr_crypto_engine::wickr_crypto_engine_ec_verify )(const wickr_ecdsa_result_t *signature, const wickr_ec_key_t *ec_public_key, const wickr_buffer_t *data_to_verify)
wickr_buffer_t *(*	wickr_crypto_engine::wickr_crypto_engine_gen_shared_secret )(const wickr_ec_key_t *local, const wickr_ec_key_t *peer)
wickr_buffer_t *(*	wickr_crypto_engine::wickr_crypto_engine_hmac_create )(const wickr_buffer_t *data, const wickr_buffer_t *hmac_key, wickr_digest_t digest_mode)
bool(*	wickr_crypto_engine::wickr_crypto_engine_hmac_verify )(const wickr_buffer_t *data, const wickr_buffer_t *hmac_key, const wickr_digest_t mode, const wickr_buffer_t *expected)
wickr_kdf_result_t *(*	wickr_crypto_engine::wickr_crypto_kdf_gen )(wickr_kdf_algo_t algo, const wickr_buffer_t *passphrase)
wickr_kdf_result_t *(*	wickr_crypto_engine::wickr_crypto_kdf_meta )(const wickr_kdf_meta_t *existing_meta, const wickr_buffer_t *passphrase)

Detailed Description

Function Documentation

wickr_crypto_engine_get_default()

const wickr_crypto_engine_t wickr_crypto_engine_get_default

(

void

)

Wickr default crypto engine

Returns

an engine containing default crypto primitive implementations (currently implemented with OpenSSL 1.0.2, libscrypt, libbcrypt)

wickr_crypto_engine_kdf_cipher()

wickr_buffer_t* wickr_crypto_engine_kdf_cipher	(	const wickr_crypto_engine_t *	engine,
		wickr_kdf_algo_t	algo,
		wickr_cipher_t	cipher,
		const wickr_buffer_t *	value,
		const wickr_buffer_t *	passphrase
	)

Encrypt a buffer with a KDF + CIPHER

The KDF + CIPHER functions currently acts as follows:

1. Calculate KDF(randomSalt || passphrase)
2. Use the output of step 1. as a cipher key to encrypt the buffer 'value' with the default engine cipher
3. The output of step 2 is then packed as | KDF_ID | RANDOM_SALT | CIPHER_TEXT |

Parameters

engine	the engine to use for ciphering / kdf functions
algo	the kdf algorithm to use for key derivation
cipher	the cipher to use to encrypt 'value' with the output of the KDF function with 'passphrase' as input
value	the value to protect with the KDF cipher
passphrase	the KDF input to use for getting a cipher key

Returns

a buffer serialized in the following format:

wickr_crypto_engine_kdf_decipher()

wickr_buffer_t* wickr_crypto_engine_kdf_decipher	(	const wickr_crypto_engine_t *	engine,
		const wickr_buffer_t *	input_buffer,
		const wickr_buffer_t *	passphrase
	)

Parameters

engine	the engine to use for deciphering / kdf functions
input_buffer	the output of a kdf + cipher operation with 'wickr_crypto_engine_kdf_cipher'
passphrase	the passphrase for the kdf + cipher operation

Returns

the original buffer protected by 'wickr_crypto_engine_kdf_cipher' or NULL if the KDF + cipher function fails due to an incorrect passphrase

wickr_digest_matching_cipher()

wickr_digest_t wickr_digest_matching_cipher

(

wickr_cipher_t

cipher

)

Get the matching digest type for a function based on size

DEPRECATED IN FAVOR OF wickr_exchange_kdf_matching_cipher

NOTE: Currently only 256bit AES ciphers are supported, so this function always returns SHA_256

Parameters

cipher

the cipher to find the matching digest for

Returns

a digest that has an output which is the same size as the length of the cipher's key

wickr_digest_matching_curve()

wickr_digest_t wickr_digest_matching_curve

(

wickr_ec_curve_t

curve

)

Get the matching digest for a curve, this is to be used for signature operations using this curve

Parameters

curve

a curve to get the matching digest for

Returns

the digest to use for signature operations using 'curve'

wickr_exchange_cipher_matching_cipher()

wickr_cipher_t wickr_exchange_cipher_matching_cipher

(

wickr_cipher_t

cipher

)

Get the matching exchange cipher given a message packet cipher

An exchange cipher is used for wrapping / unwrapping packet content decryption key material (see wickr_key_exchange_create_with_packet_key) This function currently always returns CIPHER_ID_AES256_CTR The lack of authentication on this layer is a performance / space optimization, since it is ultimately protecting authenticated mode key material (currently always CIPHER_ID_AES256_GCM) to be used for packet content decryption If bits are flipped in the key exchange itself, the resulting unauthenticated output will not be able to decrypt the GCM mode packet content

Parameters

cipher

the cipher being used for packet content encryption / decryption

Returns

the exchange cipher matching 'cipher'

Variable Documentation

wickr_crypto_engine_cipher_decrypt

wickr_buffer_t*(* wickr_crypto_engine::wickr_crypto_engine_cipher_decrypt) (const wickr_cipher_result_t *cipher_result, const wickr_buffer_t *aad, const wickr_cipher_key_t *key, bool only_auth_ciphers)

Decrypt a cipher_result

Parameters

cipher_result	a cipher result generated from 'wickr_crypto_engine_cipher_encrypt'
aad	additional data to authenticate with the ciphertext (only works with authenticated ciphers)
key	the key to use to attempt to decrypt 'cipher_result'
only_auth_ciphers	if true, only authenticated ciphers may be used for decryption

Returns

a buffer containing decrypted bytes. If the AES mode is authenticated, NULL will be returned if key is incorrect.

wickr_crypto_engine_cipher_encrypt

wickr_cipher_result_t*(* wickr_crypto_engine::wickr_crypto_engine_cipher_encrypt) (const wickr_buffer_t *plaintext, const wickr_buffer_t *aad, const wickr_cipher_key_t *key, const wickr_buffer_t *iv)

Encrypt a buffer

NOTE: IV is randomly chosen using a secure random function if one is not provided

Parameters

plaintext	the content to encrypt using 'key'
aad	additional data to authenticate with the ciphertext (only works with authenticated ciphers)
key	the cipher key to use to encrypt 'plaintext'
iv	an initialization vector to use with the cipher mode, or NULL if one should be chosen at random

Returns

a cipher result containing encrypted bytes, or NULL if the cipher mode fails or is not supported

wickr_crypto_engine_cipher_key_random

wickr_cipher_key_t*(* wickr_crypto_engine::wickr_crypto_engine_cipher_key_random) (wickr_cipher_t cipher)

Generate a secure random cipher key for a particular cipher

Parameters

cipher

the cipher to generate a random key for

Returns

a cipher key containing key material generated by a secure random function or NULL if random byte generation fails

wickr_crypto_engine_crypto_random

wickr_buffer_t*(* wickr_crypto_engine::wickr_crypto_engine_crypto_random) (size_t len)

Generate secure random bytes

Parameters

len	the number of bytes to generate

Returns

a buffer containing 'len' secure random bytes or NULL if random byte generation fails

wickr_crypto_engine_decrypt_file

bool(* wickr_crypto_engine::wickr_crypto_engine_decrypt_file) (const wickr_cipher_key_t *key, const char *sourceFilePath, const char *destinationFilePath, bool only_auth_ciphers)

Decrypt a file

Parameters

in_file	the encrypted file to decrypt
key	the key to use for decryption
out_file	the file to write the decrypted data from 'in_file'
only_auth_ciphers	if true, only authenticated ciphers may be used for decryption

Returns

true if the decryption operation succeeds, and 'out_file' can be written

wickr_crypto_engine_decrypt_ofile

bool(* wickr_crypto_engine::wickr_crypto_engine_decrypt_ofile) (FILE *fin, const wickr_cipher_key_t *key, FILE *fout, bool only_auth_ciphers)

Decrypt an open file

Parameters

fin	read encrypted data from this FILE pointer
key	the key to use for decryption
fout	write decrypted data to this FILE pointer
only_auth_ciphers	if true, only authenticated ciphers may be used for decryption

Returns

true if the decryption operation succeeds

wickr_crypto_engine_digest

wickr_buffer_t*(* wickr_crypto_engine::wickr_crypto_engine_digest) (const wickr_buffer_t *buffer, const wickr_buffer_t *salt, wickr_digest_t digest_mode)

Calculate a hash of a buffer using an optional salt value

Parameters

buffer	the buffer to hash
salt	a salt value mix with buffer before taking the hash Passing NULL will allow for no salt to be used
mode	the mode of the hash

Returns

a buffer containing the derived hash or NULL if the hashing operation fails

wickr_crypto_engine_digest_file

wickr_buffer_t*(* wickr_crypto_engine::wickr_crypto_engine_digest_file) (FILE *in_file, const wickr_digest_t mode)

Calculate the hash of a file

Parameters

in_file	a file to take the hash of it's contents
mode	the mode to use for calculating the hash

Returns

a buffer containing the output of the chosen mode of the contents of in_file

wickr_crypto_engine_ec_key_import

wickr_ec_key_t*(* wickr_crypto_engine::wickr_crypto_engine_ec_key_import) (const wickr_buffer_t *buffer, bool is_private)

Import an Elliptic Curve key from a buffer

Parameters

buffer	the buffer representing Elliptic Curve key material
is_private	false if the buffer represents a public key

Returns

an Elliptic Curve key pair parsed from buffer or NULL if buffer does not contain a valid key, or is_private is incorrectly set

wickr_crypto_engine_ec_rand_key

wickr_ec_key_t*(* wickr_crypto_engine::wickr_crypto_engine_ec_rand_key) (wickr_ec_curve_t curve)

Generate a random Elliptic Curve keypair

Parameters

curve

the curve parameters to use for random key pair generation

Returns

a random Elliptic Curve key pair or NULL if the random generation fails

wickr_crypto_engine_ec_sign

wickr_ecdsa_result_t*(* wickr_crypto_engine::wickr_crypto_engine_ec_sign) (const wickr_ec_key_t *ec_signing_key, const wickr_buffer_t *data_to_sign, const wickr_digest_t digest_mode)

Sign data using an Elliptic Curve key Data is hashed before signing. This function will calculate ECDSA(SHA2(data_to_sign))

Parameters

ec_signing_key	private signing key to use for the ECDSA algorithm
data_to_sign	the data to hash with 'digest_mode', and then sign with 'ec_signing_key'
digest_mode	the digest mode to use for SHA2

Returns

an ecdsa result containing the output of ECDSA(SHA2(data_to_sign)) or NULL if the 'ec_signing_key' is not a private key

wickr_crypto_engine_ec_verify

bool(* wickr_crypto_engine::wickr_crypto_engine_ec_verify) (const wickr_ecdsa_result_t *signature, const wickr_ec_key_t *ec_public_key, const wickr_buffer_t *data_to_verify)

Verify ECDSA signatures

Parameters

signature	a signature produced with 'wickr_crypto_engine_ec_sign'
ec_public_key	the public signing key to use for verification
data_to_verify	the original data that should have been signed with 'ec_public_key'. It will be hashed inside this function as part of the verification process

Returns

true if 'signature' can be verified by 'ec_public_key'

wickr_crypto_engine_encrypt_file

bool(* wickr_crypto_engine::wickr_crypto_engine_encrypt_file) (const wickr_cipher_key_t *key, const char *sourceFilePath, const char *destinationFilePath)

Encrypt a file

Parameters

in_file	the file to encrypt
key	the key to use for encryption
out_file	a file that should contain the encrypted data

Returns

true if encryption succeeds, and 'out_file' can be written

wickr_crypto_engine_encrypt_ofile

bool(* wickr_crypto_engine::wickr_crypto_engine_encrypt_ofile) (FILE *fin, const wickr_cipher_key_t *key, FILE *fout)

Encrypt an open file

Parameters

fin	read data to be encrypted from this FILE pointer
key	the key to use for decryption
fout	write encrypted data to this FILE pointer
only_auth_ciphers	if true, only authenticated ciphers may be used for decryption

Returns

true if the decryption operation succeeds

wickr_crypto_engine_gen_shared_secret

wickr_buffer_t*(* wickr_crypto_engine::wickr_crypto_engine_gen_shared_secret) (const wickr_ec_key_t *local, const wickr_ec_key_t *peer)

Generate a shared secret given Elliptic Curve Diffie-Hellman parameters

Parameters

local	the local elliptic curve private key
peer	the remote elliptic curve public key

Returns

a buffer containing the shared secret computed with 'local' private key and 'peer' public key

wickr_crypto_engine_hmac_create

wickr_buffer_t*(* wickr_crypto_engine::wickr_crypto_engine_hmac_create) (const wickr_buffer_t *data, const wickr_buffer_t *hmac_key, wickr_digest_t digest_mode)

Generate an HMAC

Parameters

data	the data to take the HMAC of
hmac_key	a key to use for HMAC
mode	the digest mode to perform HMAC with. This will determine the length of the output

Returns

a buffer containing the HMAC of 'data' with 'hmac_key'

wickr_crypto_engine_hmac_verify

bool(* wickr_crypto_engine::wickr_crypto_engine_hmac_verify) (const wickr_buffer_t *data, const wickr_buffer_t *hmac_key, const wickr_digest_t mode, const wickr_buffer_t *expected)

Verify an HMAC against an expected result

Parameters

data	the data to calculate the expected HMAC with
hmac_key	the key to use along with 'data' to create the expected HMAC with
mode	the mode to use for generating the expected HMAC
expected	the value to compare the generated HMAC with

Returns

true if 'expected' is equal to the HMAC of 'data' and 'hmac_key'

wickr_crypto_kdf_gen

wickr_kdf_result_t*(* wickr_crypto_engine::wickr_crypto_kdf_gen) (wickr_kdf_algo_t algo, const wickr_buffer_t *passphrase)

Execute a KDF function given an input buffer

Parameters

algo	the algorithm info to use for execution of the KDF
passphrase	bytes to use as input to the KDF function. There are no restrictions for the content of the buffer

Returns

the output of the KDF function, including the generated random salt that was used for the computation

wickr_crypto_kdf_meta

wickr_kdf_result_t*(* wickr_crypto_engine::wickr_crypto_kdf_meta) (const wickr_kdf_meta_t *existing_meta, const wickr_buffer_t *passphrase)

Execute a KDF function given an input buffer and specified parameters

Parameters

existing_meta	the parameters to use for execution, including a specific salt
passphrase	bytes to use as input to the KDF function. There are no restrictions for the content of the buffer

Returns

the output of the KDF function, including the generated random salt that was used for the computation