wickr-crypto-c

Functions
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