wickr-crypto-c
Data Structures | Macros | Functions
Wickr Protocol

Data Structures

struct  wickr_packet
 An encrypted packet made with the Wickr protocol. More...
 
struct  wickr_parse_result
 result from parsing an inbound packet More...
 
struct  wickr_decode_result
 a packet decoding result More...
 

Macros

#define OLDEST_PACKET_VERSION   2
 
#define CURRENT_PACKET_VERSION   4
 

Functions

wickr_key_exchange_twickr_key_exchange_create_with_packet_key (const wickr_crypto_engine_t *engine, const wickr_identity_chain_t *sender, const wickr_node_t *receiver, wickr_ec_key_t *packet_exchange_key, const wickr_cipher_key_t *packet_key, const wickr_buffer_t *psk, uint8_t version)
 
wickr_key_exchange_twickr_key_exchange_create_with_data (const wickr_crypto_engine_t *engine, const wickr_identity_chain_t *sender, const wickr_node_t *receiver, wickr_ec_key_t *packet_exchange_key, const wickr_buffer_t *data_to_wrap, wickr_cipher_t exchange_cipher, const wickr_buffer_t *psk, uint8_t version)
 
wickr_packet_twickr_packet_create (uint8_t version, wickr_buffer_t *content, wickr_ecdsa_result_t *signature)
 
wickr_packet_twickr_packet_create_from_buffer (const wickr_buffer_t *buffer)
 
wickr_buffer_twickr_packet_serialize (const wickr_packet_t *packet)
 
wickr_packet_twickr_packet_copy (const wickr_packet_t *source)
 
void wickr_packet_destroy (wickr_packet_t **packet)
 
wickr_parse_result_twickr_parse_result_create_failure (wickr_packet_signature_status signature_status, wickr_decode_error error)
 
wickr_parse_result_twickr_parse_result_create_success (wickr_key_exchange_set_t *key_exchange_set, wickr_key_exchange_t *key_exchange, wickr_cipher_result_t *enc_payload)
 
wickr_parse_result_twickr_parse_result_copy (const wickr_parse_result_t *source)
 
void wickr_parse_result_destroy (wickr_parse_result_t **result)
 
wickr_decode_result_twickr_decode_result_create_failure (wickr_decode_error decode_error)
 
wickr_decode_result_twickr_decode_result_create_success (wickr_payload_t *decrypted_payload, wickr_cipher_key_t *payload_key)
 
wickr_decode_result_twickr_decode_result_copy (const wickr_decode_result_t *result)
 
void wickr_decode_result_destroy (wickr_decode_result_t **result)
 
wickr_packet_twickr_packet_create_from_components (const wickr_crypto_engine_t *engine, const wickr_cipher_key_t *header_key, const wickr_cipher_key_t *payload_key, wickr_ec_key_t *exchange_key, const wickr_payload_t *payload, const wickr_node_array_t *recipients, const wickr_identity_chain_t *sender_signing_identity, uint8_t version)
 
wickr_parse_result_twickr_parse_result_from_packet (const wickr_crypto_engine_t *engine, const wickr_packet_t *packet, const wickr_buffer_t *receiver_node_id, wickr_header_keygen_func header_keygen_func, const wickr_identity_chain_t *sender_signing_identity)
 
wickr_decode_result_twickr_decode_result_from_parse_result (const wickr_packet_t *packet, const wickr_crypto_engine_t *engine, const wickr_parse_result_t *parse_result, wickr_buffer_t *receiver_dev_id, wickr_ec_key_t *receiver_decode_key, wickr_identity_chain_t *receiver_signing_identity, const wickr_identity_chain_t *sender_signing_identity)
 

Detailed Description

Macro Definition Documentation

◆ CURRENT_PACKET_VERSION

#define CURRENT_PACKET_VERSION   4

The most recent version of the protocol is version 4

◆ OLDEST_PACKET_VERSION

#define OLDEST_PACKET_VERSION   2

The oldest packet version supported is version 2

Function Documentation

◆ wickr_decode_result_copy()

wickr_decode_result_t* wickr_decode_result_copy ( const wickr_decode_result_t result)

Copy a decode result

Parameters
resultthe decode result to copy
Returns
a newly allocated decode result holding a deep copy of the properties of 'source'

◆ wickr_decode_result_create_failure()

wickr_decode_result_t* wickr_decode_result_create_failure ( wickr_decode_error  decode_error)

Create a negative decode result

Parameters
decode_errorthe error found during decoding
Returns
a newly allocated decode result with error 'decode_error' and NULL for other properties

◆ wickr_decode_result_create_success()

wickr_decode_result_t* wickr_decode_result_create_success ( wickr_payload_t decrypted_payload,
wickr_cipher_key_t payload_key 
)

Create a positive decode result

Parameters
decrypted_payloadthe decrypted payload found during decoding
payload_keythe payload key derived during decoding
Returns
a newly allocated decode result with no error

◆ wickr_decode_result_destroy()

void wickr_decode_result_destroy ( wickr_decode_result_t **  result)

Destroy a decode result

Parameters
resulta pointer to the decode result to destroy. All properties of '*result' will also be destroyed

◆ wickr_decode_result_from_parse_result()

wickr_decode_result_t* wickr_decode_result_from_parse_result ( const wickr_packet_t packet,
const wickr_crypto_engine_t engine,
const wickr_parse_result_t parse_result,
wickr_buffer_t receiver_dev_id,
wickr_ec_key_t receiver_decode_key,
wickr_identity_chain_t receiver_signing_identity,
const wickr_identity_chain_t sender_signing_identity 
)

Decode a parsed packet payload using a fetched ephemeral decode_key

For more information see Wickr white paper (Receiving a Message 6-9)

NOTE: This is a low level function that should not be called directly from this API if it can be avoided. Please use the 'wickr_ctx' API instead since it is a higher level and safer set of functions

Parameters
packetthe packet to decode
enginea crypto engine
parse_resulta previously generated parse result from 'packet'
receiver_dev_idthe 'msg_proto_id' of 'wickr_dev_info' of the recipient
receiver_decode_keythe key to attempt to complete the key exchange for discovered in the parse phase, so that the payload can be decoded
receiver_signing_identitythe recipient of the packet
sender_signing_identitythe sender of the packet used
Returns
a decode result containing decrypted packet information if decode succeeded

◆ wickr_key_exchange_create_with_data()

wickr_key_exchange_t* wickr_key_exchange_create_with_data ( const wickr_crypto_engine_t engine,
const wickr_identity_chain_t sender,
const wickr_node_t receiver,
wickr_ec_key_t packet_exchange_key,
const wickr_buffer_t data_to_wrap,
wickr_cipher_t  exchange_cipher,
const wickr_buffer_t psk,
uint8_t  version 
)

Compute a key exchange given sender/receiver information and bytes to protect (Sender Encoding) This method at a high level creates a shared secret between a sender and receiver (ECDH), runs the shared secret through a kdf (HKDF) and then uses the resulting secret as a cipher key to encrypt bytes of data. 'wickr_key_exchange_create_with_packet_key' also exists as a version of this function to specifically wrap cipher_keys instead of raw data

See Wickr white paper 'Prepare Key Exchange Data' for more information

NOTE: This is a low level function that should not be called directly from this API if it can be avoided. Please use the 'wickr_ctx' API instead since it is a higher level and safer set of functions

Parameters
enginea crypto engine supporting ECDH key exchanges
senderthe identity chain of the sender
receiverthe node this key exchange is destined for
packet_exchange_keyan EC key to use for the sender side of the ECDH function, the private component of this key is no longer needed after this function is called. The public component of it will get forwarded in the message key exchange set to the receiver
data_to_wrapThis is the data we are protecting by the output of the key exchange
exchange_cipherthe cipher that the exchange should use protect 'data_to_wrap' with
pskoptional pre-shared key data to put into the 'salt' field of HKDF
versionthe version of the packet being generated
Returns
a newly allocated key exchange object holding public metadata about this exchange and the computed exchange data

◆ wickr_key_exchange_create_with_packet_key()

wickr_key_exchange_t* wickr_key_exchange_create_with_packet_key ( const wickr_crypto_engine_t engine,
const wickr_identity_chain_t sender,
const wickr_node_t receiver,
wickr_ec_key_t packet_exchange_key,
const wickr_cipher_key_t packet_key,
const wickr_buffer_t psk,
uint8_t  version 
)

Compute a key exchange given sender/receiver information and a packet key to protect (Sender Encoding) Thie function is a convience function around 'wickr_key_exchange_create_with_data' that determines exchange_cipher automaticallly based on 'packet_key' cipher and also takes care of serializing 'packet_key'

See Wickr white paper 'Prepare Key Exchange Data' for more information

NOTE: This is a low level function that should not be called directly from this API if it can be avoided. Please use the 'wickr_ctx' API instead since it is a higher level and safer set of functions

Parameters
enginea crypto engine supporting ECDH key exchanges
senderthe identity chain of the sender
receiverthe node this key exchange is destined for
packet_exchange_keyan EC key to use for the sender side of the ECDH function, the private component of this key is no longer needed after this function is called. The public component of it will get forwarded in the message key exchange set to the receiver
packet_keythe cipher key to use for encrypting the payload of the message that is being created. This is the data we are protecting
pskoptional pre-shared key data to put into the 'salt' field of HKDF
versionthe version of the packet being generated
Returns
a newly allocated key exchange object holding public metadata about this exchange and the computed exchange data

◆ wickr_packet_copy()

wickr_packet_t* wickr_packet_copy ( const wickr_packet_t source)

Copy a packet

Parameters
sourcethe packet to copy
Returns
a newly allocated packet holding a deep copy of the properties of 'source'

◆ wickr_packet_create()

wickr_packet_t* wickr_packet_create ( uint8_t  version,
wickr_buffer_t content,
wickr_ecdsa_result_t signature 
)

Create a packet from components

Parameters
versionsee 'wickr_protocol' property documentation property documentation
contentsee 'wickr_protocol' property documentation property documentation
signaturesee 'wickr_protocol' property documentation property documentation
Returns
a newly allocated packet owning the properties passed in

◆ wickr_packet_create_from_buffer()

wickr_packet_t* wickr_packet_create_from_buffer ( const wickr_buffer_t buffer)

Parse a packet from a buffer generated by 'wickr_packet_serialize'

Parameters
buffera buffer output from 'wickr_packet_serialize'
Returns
a newly allocated packet using parsed data from 'buffer' or NULL if parsing fails

◆ wickr_packet_create_from_components()

wickr_packet_t* wickr_packet_create_from_components ( const wickr_crypto_engine_t engine,
const wickr_cipher_key_t header_key,
const wickr_cipher_key_t payload_key,
wickr_ec_key_t exchange_key,
const wickr_payload_t payload,
const wickr_node_array_t *  recipients,
const wickr_identity_chain_t sender_signing_identity,
uint8_t  version 
)

Generate a packet given components

For more information see Wickr white paper (Sending a Message)

NOTE: This is a low level function that should not be called directly from this API if it can be avoided. Please use the 'wickr_ctx' API instead since it is a higher level and safer set of functions

Parameters
enginea crypto engine capable of ECDH and signing operations using exchange_key, and cipher operations using payload_key
header_keythe key to encrypt the key exchange set of the message with
payload_keythe key to encrypt the payload of the message with
exchange_keythe key to use as the local key exchange keypair, the public side of this key will wind up in the resulting packet key exchange set
payloadthe plaintext payload to encrypt and bundle into the packet
recipientsthe array of nodes that the
sender_signing_identitythe identity chain belonging to the creator of the packet
versionthe version of the protocol encoding to use for this packet
Returns
a 'sender_signing_identity' signed packet containing encrypted payload 'payload, and key exchange set for 'recipients'

◆ wickr_packet_destroy()

void wickr_packet_destroy ( wickr_packet_t **  packet)

Destroy a packet

Parameters
packeta pointer to the packet to destroy. All properties of '*packet' will also be destroyed

◆ wickr_packet_serialize()

wickr_buffer_t* wickr_packet_serialize ( const wickr_packet_t packet)

Serialize a packet to a buffer

Parameters
packetthe packet to serialize
Returns
a buffer representing the packet in the following format: | VERSION (4BITS) SIGNATURE_CURVE_ID (4BITS) | CONTENT | SIGNATURE OF CONTENT |

◆ wickr_parse_result_copy()

wickr_parse_result_t* wickr_parse_result_copy ( const wickr_parse_result_t source)

Copy a parse result

Parameters
sourcethe parse result to copy
Returns
a newly allocated parse result holding a deep copy of the properties of 'source'

◆ wickr_parse_result_create_failure()

wickr_parse_result_t* wickr_parse_result_create_failure ( wickr_packet_signature_status  signature_status,
wickr_decode_error  error 
)

Create a negative parse result due to a failure

Parameters
signature_statusstatus of packet signature validation
errorerror message related to parsing the packet
Returns
a parse result containing the provided status information and NULL properties

◆ wickr_parse_result_create_success()

wickr_parse_result_t* wickr_parse_result_create_success ( wickr_key_exchange_set_t key_exchange_set,
wickr_key_exchange_t key_exchange,
wickr_cipher_result_t enc_payload 
)

Create a positive parse result

Parameters
key_exchange_setthe parsed public key exchange set for all recipients
key_exchangediscovered key exchange for a particular requested node, or NULL if no node was specified
enc_payloadthe encrypted payload parsed from the message
Returns
a parse result containing the provided information and non-error codes for 'signature_status' and 'err'

◆ wickr_parse_result_destroy()

void wickr_parse_result_destroy ( wickr_parse_result_t **  result)

Destroy a parse result

Parameters
resulta pointer to the parse result to destroy. All properties of '*result' will also be destroyed

◆ wickr_parse_result_from_packet()

wickr_parse_result_t* wickr_parse_result_from_packet ( const wickr_crypto_engine_t engine,
const wickr_packet_t packet,
const wickr_buffer_t receiver_node_id,
wickr_header_keygen_func  header_keygen_func,
const wickr_identity_chain_t sender_signing_identity 
)

Parse a received packet and validate it's signature

For more information see Wickr white paper (Receiving a Message 1-5)

NOTE: This is a low level function that should not be called directly from this API if it can be avoided. Please use the 'wickr_ctx' API instead since it is a higher level and safer set of functions

Parameters
enginea crypto engine
packetthe packet to parse
receiver_node_idnode_id of the recipient. If set, parsing will fail if a node_id labeled key exchange is not found in the key exchange list. If not set, the resulting parse result will contain NULL for the key exchange and simply return all other properties
header_keygen_funca function that can generate a header key for this packet
sender_signing_identitythe sender of the packet
Returns
a parse result containing a successful or unsuccessful error and signature status