wickr-crypto-c

Data Structures | Functions
Wickr_ctx

## Data Structures
struct | wickr_ctx
| Wickr encryption context for high level management of sending / receiving packets using the Wickr protocol. More...
struct | wickr_ctx_gen_result
| the output of a context generation More...
struct | wickr_ctx_packet
| a parsed inbound wickr packet that has yet to be decoded by this context More...

## Functions
wickr_ctx_gen_result_t * | wickr_ctx_gen_new (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_buffer_t *identifier)
wickr_ctx_gen_result_t * | wickr_ctx_gen_new_with_sig_key (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_ec_key_t *sig_key, wickr_buffer_t *identifier)
wickr_ctx_gen_result_t * | wickr_ctx_gen_with_root_keys (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_root_keys_t *root_keys, wickr_buffer_t *identifier)
wickr_ctx_gen_result_t * | wickr_ctx_gen_with_passphrase (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_buffer_t *exported_recovery_key, wickr_buffer_t *passphrase, wickr_buffer_t *recovery_data, wickr_buffer_t *identifier)
wickr_ctx_gen_result_t * | wickr_ctx_gen_with_recovery (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_buffer_t *recovery_data, wickr_cipher_key_t *recovery_key, wickr_buffer_t *identifier)
wickr_buffer_t * | wickr_ctx_gen_export_recovery_key_passphrase (const wickr_ctx_gen_result_t *result, const wickr_buffer_t *passphrase)
wickr_buffer_t * | wickr_ctx_gen_result_make_recovery (const wickr_ctx_gen_result_t *result)
wickr_root_keys_t * | wickr_ctx_gen_import_recovery (const wickr_crypto_engine_t engine, const wickr_buffer_t *recovery_data, const wickr_cipher_key_t *recovery_key)
wickr_ctx_gen_result_t * | wickr_ctx_gen_result_copy (const wickr_ctx_gen_result_t *source)
void | wickr_ctx_gen_result_destroy (wickr_ctx_gen_result_t **result)
wickr_ctx_t * | wickr_ctx_create (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_identity_chain_t *id_chain, wickr_storage_keys_t *storage_keys)
wickr_ctx_t * | wickr_ctx_copy (const wickr_ctx_t *ctx)
void | wickr_ctx_destroy (wickr_ctx_t **ctx)
wickr_buffer_t * | wickr_ctx_serialize (const wickr_ctx_t *ctx)
wickr_ctx_t * | wickr_ctx_create_from_buffer (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, const wickr_buffer_t *buffer)
wickr_buffer_t * | wickr_ctx_export (const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase)
wickr_ctx_t * | wickr_ctx_import (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, const wickr_buffer_t *exported, const wickr_buffer_t *passphrase)
wickr_buffer_t * | wickr_ctx_export_storage_keys (const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase)
wickr_storage_keys_t * | wickr_ctx_import_storage_keys (const wickr_crypto_engine_t engine, const wickr_buffer_t *exported, const wickr_buffer_t *passphrase)
wickr_cipher_result_t * | wickr_ctx_cipher_local (const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext)
wickr_cipher_result_t * | wickr_ctx_cipher_remote (const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext)
wickr_buffer_t * | wickr_ctx_decipher_remote (const wickr_ctx_t *ctx, const wickr_cipher_result_t *cipher_text)
wickr_ephemeral_keypair_t * | wickr_ctx_ephemeral_keypair_gen (const wickr_ctx_t *ctx, uint64_t key_id)
wickr_ctx_packet_t * | wickr_ctx_packet_create (wickr_packet_t *packet, wickr_identity_chain_t *sender, wickr_parse_result_t *parse_result)
void | wickr_ctx_packet_destroy (wickr_ctx_packet_t **packet)
wickr_encoder_result_t * | wickr_ctx_encode_packet (const wickr_ctx_t *ctx, const wickr_payload_t *payload, const wickr_node_array_t *nodes)
wickr_ctx_packet_t * | wickr_ctx_parse_packet (const wickr_ctx_t *ctx, const wickr_buffer_t *packet_buffer, const wickr_identity_chain_t *sender)

## Detailed Description

## Function Documentation

## ◆ wickr_ctx_cipher_local()

wickr_cipher_result_t* wickr_ctx_cipher_local | ( | const wickr_ctx_t * | ctx,
|  | const wickr_buffer_t * | plaintext
| ) |  |

Encrypts data using the local storage key

Parameters

  ctx | the context to use for encryption
  plaintext | the bytes to encrypt for local storage

Returns
  'plaintext' encrypted with the context's local storage key

## ◆ wickr_ctx_cipher_remote()

wickr_cipher_result_t* wickr_ctx_cipher_remote | ( | const wickr_ctx_t * | ctx,
|  | const wickr_buffer_t * | plaintext
| ) |  |

Encrypts data using the remote storage key

Parameters

  ctx | the context to use for encryption
  plaintext | plaintext the bytes to encrypt for remote storage

Returns
  'plaintext' encrypted with the context's remote storage key

## ◆ wickr_ctx_copy()

wickr_ctx_t* wickr_ctx_copy | ( | const wickr_ctx_t * | ctx | ) |

Copy a context

Parameters

  ctx | the context to copy

Returns
  a newly allocated context holding a deep copy of the properties of 'ctx'

## ◆ wickr_ctx_create()

wickr_ctx_t* wickr_ctx_create | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | wickr_identity_chain_t * | id_chain,
|  | wickr_storage_keys_t * | storage_keys
| ) |  |

Create a context from components

Parameters

  engine | a crypto engine to support context operations
  dev_info | the device information the context should be bound to
  id_chain | the identity chain that belongs to this context and will be used for encoding / decoding messages
  storage_keys | the storage keys used for local and remote ciphers of this context

Returns
  a newly allocated context owning the passed in parameters

## ◆ wickr_ctx_create_from_buffer()

wickr_ctx_t* wickr_ctx_create_from_buffer | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | const wickr_buffer_t * | buffer
| ) |  |

Recreate a context from a serizlied representation

Parameters

  engine | a crypto engine to support context operations
  dev_info | the device information the context should be bound to
  buffer | data created with 'wickr_ctx_serialize'

Returns
  a context restored from 'buffer' or NULL if parsing fails

## ◆ wickr_ctx_decipher_remote()

wickr_buffer_t* wickr_ctx_decipher_remote | ( | const wickr_ctx_t * | ctx,
|  | const wickr_cipher_result_t * | cipher_text
| ) |  |

Decrypts data using the local storage key

Parameters

  ctx | the context to use for decryption
  cipher_text | a cipher result from 'wickr_ctx_cipher_remote'

Returns
  'cipher_text' decoded with remote storage key

## ◆ wickr_ctx_destroy()

void wickr_ctx_destroy | ( | wickr_ctx_t ** | ctx | ) |

Destroy a context

Parameters

  ctx | a pointer to the context to destroy. All properties of '*ctx' will also be destroyed

## ◆ wickr_ctx_encode_packet()

wickr_encoder_result_t* wickr_ctx_encode_packet | ( | const wickr_ctx_t * | ctx,
|  | const wickr_payload_t * | payload,
|  | const wickr_node_array_t * | nodes
| ) |  |

Encode a Wickr packet to a set of nodes

Parameters

  ctx | the context to use to encode 'payload' to 'nodes'
  payload | the metadata and body information to send to 'nodes'
  nodes | the recipient nodes for this packet

Returns
  an encode result containing an encrypted Wickr packet that transfers 'payload' to 'nodes'

## ◆ wickr_ctx_ephemeral_keypair_gen()

wickr_ephemeral_keypair_t* wickr_ctx_ephemeral_keypair_gen | ( | const wickr_ctx_t * | ctx,
|  | uint64_t | key_id
| ) |  |

Generate ephemeral message keypairs

NOTE: the result of this function should be kept in a local cache to allow for decoding a message that was created with it's public components. The public buffer of the contained EC key, along with the key_id, and the key signature should be published to a pool for consumption and use by a sender looking to addresss a message to this context

Parameters

  ctx | the context to use for ephemeral key pair generation
  key_id | the identifier to assign to the generated keypair

Returns
  an ephemeral key pair containing the private and public components, signed by the ctx node signing identity

## ◆ wickr_ctx_export()

wickr_buffer_t* wickr_ctx_export | ( | const wickr_ctx_t * | ctx,
|  | const wickr_buffer_t * | passphrase
| ) |  |

Serialize and encrypt a context with a passphrase

Parameters

  ctx | the context to serialize and encrypt
  passphrase | the password to use for locking the exported data, can be a string or bytes

Returns
  bytes representing an scrypt encrypted context

## ◆ wickr_ctx_export_storage_keys()

wickr_buffer_t* wickr_ctx_export_storage_keys | ( | const wickr_ctx_t * | ctx,
|  | const wickr_buffer_t * | passphrase
| ) |  |

Exports storage keys for a context using a KDF + CIPHER function

For more information on the KDF + CIPHER functionality, review documentation for 'wickr_crypto_engine_kdf_cipher'

Defaults are currently using KDF_SCRYPT_2_17 for a KDF and CIPHER_AES256_GCM for a cipher

Parameters

  ctx | the context to export storage keys from
  passphrase | the passphrase to use as input to a KDF that will generated a key to protect storage keys

Returns
  a buffer containing exported storage keys

## ◆ wickr_ctx_gen_export_recovery_key_passphrase()

wickr_buffer_t* wickr_ctx_gen_export_recovery_key_passphrase | ( | const wickr_ctx_gen_result_t * | result,
|  | const wickr_buffer_t * | passphrase
| ) |  |

Exports the recovery key using a KDF + CIPHER function

For more information on the KDF + CIPHER functionality, review documentation for 'wickr_crypto_engine_kdf_cipher'

Defaults are currently using KDF_SCRYPT_2_17 for a KDF and CIPHER_AES256_GCM for a cipher

Parameters

  result | a context generation result to export the recovery key from
  passphrase | the passphrase to use as input to the KDF function

Returns
  a buffer that was created by first taking KDF(randomSalt || passphrase) and then using that output as a key that encrypted

## ◆ wickr_ctx_gen_import_recovery()

wickr_root_keys_t* wickr_ctx_gen_import_recovery | ( | const wickr_crypto_engine_t | engine,
|  | const wickr_buffer_t * | recovery_data,
|  | const wickr_cipher_key_t * | recovery_key
| ) |  |

Parameters

  engine | a crypto engine that was used to call 'wickr_ctx_gen_result_make_recovery'
  recovery_data | an encrypted recovery as created by 'wickr_ctx_gen_result_make_recovery'
  recovery_key | the recovery key from the 'wickr_ctx_gen_result' that called 'wickr_ctx_gen_result_make_recovery' to make 'recovery'

Returns
  root keys created from decoding 'recovery' with 'recovery_key' or NULL if the decryption operation failed

## ◆ wickr_ctx_gen_new()

wickr_ctx_gen_result_t* wickr_ctx_gen_new | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | wickr_buffer_t * | identifier
| ) |  |

Makes a new root and random node identity + context with random keys

NOTE: The resulting wickr_ctx_gen_result does not gain ownership over the parameters to this function

Parameters

  engine | the crypto engine to use for all context operations
  dev_info | the device info for which to bind this context to
  identifier | a system unique identifier that will represent the root identity that is being generated

Returns
  a generation result containing a root identity represented by 'identifier' and a node identity signed by 'root' with a random set of keys

## ◆ wickr_ctx_gen_new_with_sig_key()

wickr_ctx_gen_result_t* wickr_ctx_gen_new_with_sig_key | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | wickr_ec_key_t * | sig_key,
|  | wickr_buffer_t * | identifier
| ) |  |

Makes a new root and random node identity + context with random keys except for a provided root signing key

NOTE: The resulting wickr_ctx_gen_result does not gain ownership over the parameters to this function

Parameters

  engine | the crypto engine to use for all context operations
  dev_info | the device info for which to bind this context to
  sig_key | a signature key to associate with the generated root identity
  identifier | a system unique identifier that will represent the root identity that is being generated

Returns
  a generation result containing a root identity represented by 'identifier' and a node identity signed by 'root' with 'sig_key' as the root signing key

## ◆ wickr_ctx_gen_result_copy()

wickr_ctx_gen_result_t* wickr_ctx_gen_result_copy | ( | const wickr_ctx_gen_result_t * | source | ) |

Copy a context generation result

Parameters

  source | the context generation result to copy

Returns
  a newly allocated context generation result holding a deep copy of the properties of 'source'

## ◆ wickr_ctx_gen_result_destroy()

void wickr_ctx_gen_result_destroy | ( | wickr_ctx_gen_result_t ** | result | ) |

Destroy a context generation result

Parameters

  result | a pointer to the context generation result to destroy. All properties of '*result' will also be destroyed

## ◆ wickr_ctx_gen_result_make_recovery()

wickr_buffer_t* wickr_ctx_gen_result_make_recovery | ( | const wickr_ctx_gen_result_t * | result | ) |

Serializes root keys and ciphers them with the recovery key

Parameters

  result | the context generation result to make an recovery from

Returns
  a buffer with a serialized cipher_result generated by encrypting 'root_keys' with the 'recovery_key' held in 'result'.

## ◆ wickr_ctx_gen_with_passphrase()

wickr_ctx_gen_result_t* wickr_ctx_gen_with_passphrase | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | wickr_buffer_t * | exported_recovery_key,
|  | wickr_buffer_t * | passphrase,
|  | wickr_buffer_t * | recovery_data,
|  | wickr_buffer_t * | identifier
| ) |  |

Makes a new context using an existing root identity's exported recovery key and a passphrase

NOTE: The resulting wickr_ctx_gen_result does not gain ownership over the parameters to this function

Parameters

  engine | the crypto engine to use for all context operations
  dev_info | the device info for which to bind this context to
  exported_recovery_key | a previously exported random recovery key that was protected with a KDF using 'passphrase' as the key. See 'wickr_ctx_gen_export_recovery_key_passphrase' for more information
  passphrase | the passphrase to decode exported_recovery_key with
  recovery_data | an export of 'root_keys' from a previous context encrypted with recovery_key
  identifier | identifier the system unique identifier that was previously associated with the root keys held in 'recovery'

Returns
  a generation result containing an existing root identity represented by 'identifier' and a node identity signed by the existing root. NULL if decoding 'exported_recovery_key' or 'recovery' fails due to an invalid passphrase

## ◆ wickr_ctx_gen_with_recovery()

wickr_ctx_gen_result_t* wickr_ctx_gen_with_recovery | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | wickr_buffer_t * | recovery_data,
|  | wickr_cipher_key_t * | recovery_key,
|  | wickr_buffer_t * | identifier
| ) |  |

Makes a new context using an existing exported root keys and a provided recovery key

NOTE: The resulting wickr_ctx_gen_result does not gain ownership over the parameters to this function

Parameters

  engine | the crypto engine to use for all context operations
  dev_info | the device info for which to bind this context to
  recovery_data | an recovery containing exported root_keys from a previous context using 'recovery_key'
  recovery_key | the key to decrypt 'recovery' with to attempt recovery of root_keys to use for context generation
  identifier | identifier the system unique identifier that was previously associated with the root keys held in 'recovery'

Returns
  a generation result containing an existing root identity represented by 'identifier' and a node identity signed by the existing root. NULL if decoding 'recovery' fails due to an incorrect key

## ◆ wickr_ctx_gen_with_root_keys()

wickr_ctx_gen_result_t* wickr_ctx_gen_with_root_keys | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | wickr_root_keys_t * | root_keys,
|  | wickr_buffer_t * | identifier
| ) |  |

Makes a new context using an existing root keys set

NOTE: The resulting wickr_ctx_gen_result does not gain ownership over the parameters to this function

This function is used to provision a new node identity onto the system given an existing root identity

Parameters

  engine | the crypto engine to use for all context operations
  dev_info | the device info for which to bind this context to
  root_keys | the root keys to use for the generation, the generated node will be signed by the root key's signing key, and the storage keys will be derived from the root remote / local cipher keys
  identifier | the system unique identifier that was previously associated with root_keys

Returns
  a generation result containing an existing root identity represented by 'identifier' and a node identity signed by the existing root

## ◆ wickr_ctx_import()

wickr_ctx_t* wickr_ctx_import | ( | const wickr_crypto_engine_t | engine,
|  | wickr_dev_info_t * | dev_info,
|  | const wickr_buffer_t * | exported,
|  | const wickr_buffer_t * | passphrase
| ) |  |

Import a ctx exported by 'wickr_ctx_export'

Parameters

  engine | the crypto engine to use for decryption and the resulting context
  dev_info | the device information the context should be bound to
  exported | the result of the call to 'wickr_ctx_export'
  passphrase | the passphrase used to export the context

## ◆ wickr_ctx_import_storage_keys()

wickr_storage_keys_t* wickr_ctx_import_storage_keys | ( | const wickr_crypto_engine_t | engine,
|  | const wickr_buffer_t * | exported,
|  | const wickr_buffer_t * | passphrase
| ) |  |

Import storage keys exported with 'wickr_ctx_export_storage_keys'

Parameters

  engine | a crypto engine supporting KDF based encryption
  exported | keys exported with 'wickr_ctx_export_storage_keys'
  passphrase | the passphrase used to export storage keys

Returns
  decoded storage keys or NULL if the passphrase is invalid

## ◆ wickr_ctx_packet_create()

wickr_ctx_packet_t* wickr_ctx_packet_create | ( | wickr_packet_t * | packet,
|  | wickr_identity_chain_t * | sender,
|  | wickr_parse_result_t * | parse_result
| ) |  |

Create a context packet parse result from components

Parameters

  packet | see property description from 'wickr_ctx_packet'
  sender | see property description from 'wickr_ctx_packet'
  parse_result | see property description from 'wickr_ctx_packet'

Returns
  a newly allocated context packet parse result owning the parameters passed in

## ◆ wickr_ctx_packet_destroy()

void wickr_ctx_packet_destroy | ( | wickr_ctx_packet_t ** | packet | ) |

Destroy a packet parse result

Parameters

  packet | a pointer to a context packet parse result to destroy. Will destroy the sub properties of '*packet' as well

## ◆ wickr_ctx_parse_packet()

wickr_ctx_packet_t* wickr_ctx_parse_packet | ( | const wickr_ctx_t * | ctx,
|  | const wickr_buffer_t * | packet_buffer,
|  | const wickr_identity_chain_t * | sender
| ) |  |

Parse a Wickr packet into components, fail if the current node's key exchange is not found

Parameters

  ctx | the context to use for parsing
  packet_buffer | the buffer representing the serialized packet that was delivered to 'ctx'
  sender | the sender of the 'packet_buffer'

Returns
  a parse result holding the parsed information from 'packet_buffer' as well as a discovered key exchange from the current ctx node_id. If the packet was not addressed to this context, an error is generated

## ◆ wickr_ctx_serialize()

wickr_buffer_t* wickr_ctx_serialize | ( | const wickr_ctx_t * | ctx | ) |

Serialize a context

Parameters

  ctx | the context to serialize to bytes

Returns
  bytes representing a combination of the storage keys and id chain from 'ctx'