wickr-crypto-c
Functions
OpenSSL Crypto Engine

Functions

wickr_buffer_topenssl_crypto_random (size_t len)
 
wickr_cipher_key_topenssl_cipher_key_random (wickr_cipher_t cipher)
 
wickr_cipher_result_topenssl_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_topenssl_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_topenssl_sha2 (const wickr_buffer_t *buffer, const wickr_buffer_t *salt, wickr_digest_t mode)
 
wickr_ec_key_topenssl_ec_rand_key (wickr_ec_curve_t curve)
 
wickr_ec_key_topenssl_ec_key_import (const wickr_buffer_t *buffer, bool is_private)
 
wickr_ecdsa_result_topenssl_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_topenssl_gen_shared_secret (const wickr_ec_key_t *local, const wickr_ec_key_t *peer)
 
wickr_buffer_topenssl_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_topenssl_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_topenssl_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_resulta cipher result generated from 'openssl_aes256_encrypt'
aadadditional data to authenticate with the ciphertext (only works with authenticated ciphers)
keythe key to use to attempt to decrypt 'cipher_result'
only_auth_ciphersif 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
plaintextthe content to encrypt using 'key'
aadadditional data to authenticate with the ciphertext (only works with authenticated ciphers)
keythe cipher key to use to encrypt 'plaintext'
ivan 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
cipherthe 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
lenthe 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_filethe encrypted file to decrypt
keythe key to use for decryption
out_filethe file to write the decrypted data from 'in_file'
only_auth_ciphersif 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
bufferthe buffer representing Elliptic Curve key material
is_privatefalse 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
curvethe 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_keyprivate signing key to use for the ECDSA algorithm
data_to_signthe data to hash with 'digest_mode', and then sign with 'ec_signing_key'
digest_modethe 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
signaturea signature produced with 'openssl_ec_sign'
ec_public_keythe public signing key to use for verification
data_to_verifythe 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_filethe file to encrypt
keythe key to use for AES256
out_filea 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
localthe local elliptic curve private key
peerthe 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_materialthe original key to extract and expand using HKDF
salta salt value to provide to HKDF, this should be randomly generated or NULL if no salt should be used
infocontextual information to pass to HKDF, this can be NULL if no contextual information should be used
hash_modethe 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
datathe data to take the HMAC of
hmac_keya key to use for HMAC
modethe 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
datathe data to calculate the expected HMAC with
hmac_keythe key to use along with 'data' to create the expected HMAC with
modethe mode to use for generating the expected HMAC
expectedthe 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
bufferthe buffer to hash
salta 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
modethe 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_filea file to take the hash of it's contents
modethe mode to use for calculating the hash
Returns
a buffer containing the output of the chosen SHA2 mode of the contents of in_file