wickr-crypto-c
Data Structures | Functions | Variables
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_twickr_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_twickr_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)
 
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
enginethe engine to use for ciphering / kdf functions
algothe kdf algorithm to use for key derivation
cipherthe cipher to use to encrypt 'value' with the output of the KDF function with 'passphrase' as input
valuethe value to protect with the KDF cipher
passphrasethe 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
enginethe engine to use for deciphering / kdf functions
input_bufferthe output of a kdf + cipher operation with 'wickr_crypto_engine_kdf_cipher'
passphrasethe 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
cipherthe 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
curvea 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
cipherthe 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_resulta cipher result generated from 'wickr_crypto_engine_cipher_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.

◆ 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
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

◆ 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
cipherthe 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
lenthe 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_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

◆ 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
bufferthe buffer to hash
salta salt value mix with buffer before taking the hash Passing NULL will allow for no salt to be used
modethe 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_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 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
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

◆ 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
curvethe 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_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

◆ 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
signaturea signature produced with 'wickr_crypto_engine_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'

◆ 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_filethe file to encrypt
keythe key to use for encryption
out_filea file that should contain the encrypted data
Returns
true if encryption succeeds, and 'out_file' can be written

◆ 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
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

◆ 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
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'

◆ 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
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'

◆ 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
algothe algorithm info to use for execution of the KDF
passphrasebytes 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_metathe parameters to use for execution, including a specific salt
passphrasebytes 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