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