wickr-crypto-c
|
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 |
#define CURRENT_PACKET_VERSION 4 |
The most recent version of the protocol is version 4
#define OLDEST_PACKET_VERSION 2 |
The oldest packet version supported is version 2
wickr_decode_result_t* wickr_decode_result_copy | ( | const wickr_decode_result_t * | result | ) |
Copy a decode result
result | the decode result to copy |
wickr_decode_result_t* wickr_decode_result_create_failure | ( | wickr_decode_error | decode_error | ) |
Create a negative decode result
decode_error | the error found during decoding |
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
decrypted_payload | the decrypted payload found during decoding |
payload_key | the payload key derived during decoding |
void wickr_decode_result_destroy | ( | wickr_decode_result_t ** | result | ) |
Destroy a decode result
result | a pointer to the decode result to destroy. All properties of '*result' will also be destroyed |
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
packet | the packet to decode |
engine | a crypto engine |
parse_result | a previously generated parse result from 'packet' |
receiver_dev_id | the 'msg_proto_id' of 'wickr_dev_info' of the recipient |
receiver_decode_key | the key to attempt to complete the key exchange for discovered in the parse phase, so that the payload can be decoded |
receiver_signing_identity | the recipient of the packet |
sender_signing_identity | the sender of the packet used |
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
engine | a crypto engine supporting ECDH key exchanges |
sender | the identity chain of the sender |
receiver | the node this key exchange is destined for |
packet_exchange_key | an 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_wrap | This is the data we are protecting by the output of the key exchange |
exchange_cipher | the cipher that the exchange should use protect 'data_to_wrap' with |
psk | optional pre-shared key data to put into the 'salt' field of HKDF |
version | the version of the packet being generated |
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
engine | a crypto engine supporting ECDH key exchanges |
sender | the identity chain of the sender |
receiver | the node this key exchange is destined for |
packet_exchange_key | an 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_key | the cipher key to use for encrypting the payload of the message that is being created. This is the data we are protecting |
psk | optional pre-shared key data to put into the 'salt' field of HKDF |
version | the version of the packet being generated |
wickr_packet_t* wickr_packet_copy | ( | const wickr_packet_t * | source | ) |
Copy a packet
source | the packet to copy |
wickr_packet_t* wickr_packet_create | ( | uint8_t | version, |
wickr_buffer_t * | content, | ||
wickr_ecdsa_result_t * | signature | ||
) |
Create a packet from components
version | see 'wickr_protocol' property documentation property documentation |
content | see 'wickr_protocol' property documentation property documentation |
signature | see 'wickr_protocol' property documentation property documentation |
wickr_packet_t* wickr_packet_create_from_buffer | ( | const wickr_buffer_t * | buffer | ) |
Parse a packet from a buffer generated by 'wickr_packet_serialize'
buffer | a buffer output from 'wickr_packet_serialize' |
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
engine | a crypto engine capable of ECDH and signing operations using exchange_key, and cipher operations using payload_key |
header_key | the key to encrypt the key exchange set of the message with |
payload_key | the key to encrypt the payload of the message with |
exchange_key | the 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 |
payload | the plaintext payload to encrypt and bundle into the packet |
recipients | the array of nodes that the |
sender_signing_identity | the identity chain belonging to the creator of the packet |
version | the version of the protocol encoding to use for this packet |
void wickr_packet_destroy | ( | wickr_packet_t ** | packet | ) |
Destroy a packet
packet | a pointer to the packet to destroy. All properties of '*packet' will also be destroyed |
wickr_buffer_t* wickr_packet_serialize | ( | const wickr_packet_t * | packet | ) |
Serialize a packet to a buffer
packet | the packet to serialize |
wickr_parse_result_t* wickr_parse_result_copy | ( | const wickr_parse_result_t * | source | ) |
Copy a parse result
source | the parse result to copy |
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
signature_status | status of packet signature validation |
error | error message related to parsing the packet |
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
key_exchange_set | the parsed public key exchange set for all recipients |
key_exchange | discovered key exchange for a particular requested node, or NULL if no node was specified |
enc_payload | the encrypted payload parsed from the message |
void wickr_parse_result_destroy | ( | wickr_parse_result_t ** | result | ) |
Destroy a parse result
result | a pointer to the parse result to destroy. All properties of '*result' will also be destroyed |
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
engine | a crypto engine |
packet | the packet to parse |
receiver_node_id | node_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_func | a function that can generate a header key for this packet |
sender_signing_identity | the sender of the packet |