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_twickr_ctx_gen_new (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, wickr_buffer_t *identifier)
 
wickr_ctx_gen_result_twickr_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_twickr_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_twickr_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_twickr_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_twickr_ctx_gen_export_recovery_key_passphrase (const wickr_ctx_gen_result_t *result, const wickr_buffer_t *passphrase)
 
wickr_buffer_twickr_ctx_gen_result_make_recovery (const wickr_ctx_gen_result_t *result)
 
wickr_root_keys_twickr_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_twickr_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_twickr_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_twickr_ctx_copy (const wickr_ctx_t *ctx)
 
void wickr_ctx_destroy (wickr_ctx_t **ctx)
 
wickr_buffer_twickr_ctx_serialize (const wickr_ctx_t *ctx)
 
wickr_ctx_twickr_ctx_create_from_buffer (const wickr_crypto_engine_t engine, wickr_dev_info_t *dev_info, const wickr_buffer_t *buffer)
 
wickr_buffer_twickr_ctx_export (const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase)
 
wickr_ctx_twickr_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_twickr_ctx_export_storage_keys (const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase)
 
wickr_storage_keys_twickr_ctx_import_storage_keys (const wickr_crypto_engine_t engine, const wickr_buffer_t *exported, const wickr_buffer_t *passphrase)
 
wickr_cipher_result_twickr_ctx_cipher_local (const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext)
 
wickr_cipher_result_twickr_ctx_cipher_remote (const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext)
 
wickr_buffer_twickr_ctx_decipher_remote (const wickr_ctx_t *ctx, const wickr_cipher_result_t *cipher_text)
 
wickr_ephemeral_keypair_twickr_ctx_ephemeral_keypair_gen (const wickr_ctx_t *ctx, uint64_t key_id)
 
wickr_ctx_packet_twickr_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_twickr_ctx_encode_packet (const wickr_ctx_t *ctx, const wickr_payload_t *payload, const wickr_node_array_t *nodes)
 
wickr_ctx_packet_twickr_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
ctxthe context to use for encryption
plaintextthe 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
ctxthe context to use for encryption
plaintextplaintext 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
ctxthe 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
enginea crypto engine to support context operations
dev_infothe device information the context should be bound to
id_chainthe identity chain that belongs to this context and will be used for encoding / decoding messages
storage_keysthe 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
enginea crypto engine to support context operations
dev_infothe device information the context should be bound to
bufferdata 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
ctxthe context to use for decryption
cipher_texta 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
ctxa 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
ctxthe context to use to encode 'payload' to 'nodes'
payloadthe metadata and body information to send to 'nodes'
nodesthe 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
ctxthe context to use for ephemeral key pair generation
key_idthe 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
ctxthe context to serialize and encrypt
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
ctxthe context to export storage keys from
passphrasethe 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
resulta context generation result to export the recovery key from
passphrasethe 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
enginea crypto engine that was used to call 'wickr_ctx_gen_result_make_recovery'
recovery_dataan encrypted recovery as created by 'wickr_ctx_gen_result_make_recovery'
recovery_keythe 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
enginethe crypto engine to use for all context operations
dev_infothe device info for which to bind this context to
identifiera 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
enginethe crypto engine to use for all context operations
dev_infothe device info for which to bind this context to
sig_keya signature key to associate with the generated root identity
identifiera 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
sourcethe 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
resulta 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
resultthe 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
enginethe crypto engine to use for all context operations
dev_infothe device info for which to bind this context to
exported_recovery_keya 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
passphrasethe passphrase to decode exported_recovery_key with
recovery_dataan export of 'root_keys' from a previous context encrypted with recovery_key
identifieridentifier 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
enginethe crypto engine to use for all context operations
dev_infothe device info for which to bind this context to
recovery_dataan recovery containing exported root_keys from a previous context using 'recovery_key'
recovery_keythe key to decrypt 'recovery' with to attempt recovery of root_keys to use for context generation
identifieridentifier 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
enginethe crypto engine to use for all context operations
dev_infothe device info for which to bind this context to
root_keysthe 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
identifierthe 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
enginethe crypto engine to use for decryption and the resulting context
dev_infothe device information the context should be bound to
exportedthe result of the call to 'wickr_ctx_export'
passphasethe 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
enginea crypto engine supporting KDF based encryption
exportedkeys exported with 'wickr_ctx_export_storage_keys'
passphrasethe 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
packetsee property description from 'wickr_ctx_packet'
sendersee property description from 'wickr_ctx_packet'
parse_resultsee 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
packeta 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
ctxthe context to use for parsing
packet_bufferthe buffer representing the serialized packet that was delivered to 'ctx'
senderthe 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
ctxthe context to serialize to bytes
Returns
bytes representing a combination of the storage keys and id chain from 'ctx'