OpenSSL Crypto Engine

Functions
wickr_buffer_t *	openssl_crypto_random (size_t len)
wickr_cipher_key_t *	openssl_cipher_key_random (wickr_cipher_t cipher)
wickr_cipher_result_t *	openssl_aes256_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 *	openssl_aes256_decrypt (const wickr_cipher_result_t *cipher_result, const wickr_buffer_t *aad, const wickr_cipher_key_t *key, bool only_auth_ciphers)
wickr_buffer_t *	openssl_sha2 (const wickr_buffer_t *buffer, const wickr_buffer_t *salt, wickr_digest_t mode)
wickr_ec_key_t *	openssl_ec_rand_key (wickr_ec_curve_t curve)
wickr_ec_key_t *	openssl_ec_key_import (const wickr_buffer_t *buffer, bool is_private)
wickr_ecdsa_result_t *	openssl_ec_sign (const wickr_ec_key_t *ec_signing_key, const wickr_buffer_t *data_to_sign, wickr_digest_t digest_mode)
bool	openssl_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 *	openssl_gen_shared_secret (const wickr_ec_key_t *local, const wickr_ec_key_t *peer)
wickr_buffer_t *	openssl_hmac_create (const wickr_buffer_t *data, const wickr_buffer_t *hmac_key, wickr_digest_t mode)
bool	openssl_hmac_verify (const wickr_buffer_t *data, const wickr_buffer_t *hmac_key, wickr_digest_t mode, const wickr_buffer_t *expected)
wickr_buffer_t *	openssl_hkdf (const wickr_buffer_t *input_key_material, const wickr_buffer_t *salt, const wickr_buffer_t *info, wickr_digest_t hash_mode)
wickr_buffer_t *	openssl_sha2_file (FILE *in_file, wickr_digest_t mode)
bool	openssl_encrypt_file (FILE *in_file, const wickr_cipher_key_t *key, FILE *out_file)
bool	openssl_decrypt_file (FILE *in_file, const wickr_cipher_key_t *key, FILE *out_file, bool only_auth_ciphers)
bool	openssl_enable_fips_mode (void)
bool	openssl_is_fips_supported ()

Detailed Description

Function Documentation

openssl_aes256_decrypt()

wickr_buffer_t* openssl_aes256_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 using AES256 Currently supports AES256-GCM and AES256-CTR cipher modes

Parameters

cipher_result	a cipher result generated from 'openssl_aes256_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.

openssl_aes256_encrypt()

wickr_cipher_result_t* openssl_aes256_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 using AES256 Currently supports AES256-GCM and AES256-CTR cipher modes

NOTE: IV is randomly chosen using 'openssl_crypto_random' 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

openssl_cipher_key_random()

wickr_cipher_key_t* openssl_cipher_key_random

(

wickr_cipher_t

cipher

)

Generate a secure random cipher key for a particular cipher Currently supports AES256-GCM and AES256-CTR cipher modes

Parameters

cipher

the cipher to generate a random key for

Returns

a cipher key containing key material generated by 'openssl_crypto_random' or NULL if random byte generation fails

openssl_crypto_random()

wickr_buffer_t* openssl_crypto_random

(

size_t

len

)

Generate secure random bytes using the rand_bytes function from OpenSSL

Parameters

len	the number of bytes to generate

Returns

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

openssl_decrypt_file()

bool openssl_decrypt_file	(	FILE *	in_file,
		const wickr_cipher_key_t *	key,
		FILE *	out_file,
		bool	only_auth_ciphers
	)

Decrypt a file with AES256

Note: Unauthenticated modes will always succeed and the contents of 'out_file' may be incorrect For this reason it is useful to use an authenticated mode such as AES256 GCM when encrypting files

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

openssl_ec_key_import()

wickr_ec_key_t* openssl_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

openssl_ec_rand_key()

wickr_ec_key_t* openssl_ec_rand_key

(

wickr_ec_curve_t

curve

)

Generate a random Elliptic Curve keypair Supported curve is currently limited to NIST P521

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

openssl_ec_sign()

wickr_ecdsa_result_t* openssl_ec_sign	(	const wickr_ec_key_t *	ec_signing_key,
		const wickr_buffer_t *	data_to_sign,
		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

openssl_ec_verify()

bool openssl_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 'openssl_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'

openssl_enable_fips_mode()

bool openssl_enable_fips_mode

(

void

)

Enable FIPS mode

Returns

true if openssl fips enable is allowed

openssl_encrypt_file()

bool openssl_encrypt_file	(	FILE *	in_file,
		const wickr_cipher_key_t *	key,
		FILE *	out_file
	)

Encrypt a file with AES256

Parameters

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

Returns

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

openssl_gen_shared_secret()

wickr_buffer_t* openssl_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

openssl_hkdf()

wickr_buffer_t* openssl_hkdf	(	const wickr_buffer_t *	input_key_material,
		const wickr_buffer_t *	salt,
		const wickr_buffer_t *	info,
		wickr_digest_t	hash_mode
	)

Derive a key with HMAC Key Derivation Function

Parameters

input_key_material	the original key to extract and expand using HKDF
salt	a salt value to provide to HKDF, this should be randomly generated or NULL if no salt should be used
info	contextual information to pass to HKDF, this can be NULL if no contextual information should be used
hash_mode	the hash mode to use for the HKDF output, this will determine the length of the final output

Returns

a buffer containing the calculated HKDF value

openssl_hmac_create()

wickr_buffer_t* openssl_hmac_create	(	const wickr_buffer_t *	data,
		const wickr_buffer_t *	hmac_key,
		wickr_digest_t	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'

openssl_hmac_verify()

bool openssl_hmac_verify	(	const wickr_buffer_t *	data,
		const wickr_buffer_t *	hmac_key,
		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'

openssl_is_fips_supported()

bool openssl_is_fips_supported

(

)

Determine if FIPS mode is available

Returns

true if openssl fips mode is available

openssl_sha2()

wickr_buffer_t* openssl_sha2	(	const wickr_buffer_t *	buffer,
		const wickr_buffer_t *	salt,
		wickr_digest_t	mode
	)

Calculate a SHA2 hash of a buffer using an optional salt value Supported modes of SHA2 are SHA256, SHA384 and SHA512

Parameters

buffer	the buffer to hash
salt	a salt value to concatenate to buffer before taking the hash. The input to the SHA2 function will be SHA2(buffer || salt) Passing NULL will allow for no salt to be used
mode	the mode of SHA2 to use for hashing

Returns

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

openssl_sha2_file()

wickr_buffer_t* openssl_sha2_file	(	FILE *	in_file,
		wickr_digest_t	mode
	)

Calculate the SHA2 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 SHA2 mode of the contents of in_file