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_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)
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)
wickr_packet_t * | wickr_packet_create (uint8_t version, wickr_buffer_t *content, wickr_ecdsa_result_t *signature)
wickr_packet_t * | wickr_packet_create_from_buffer (const wickr_buffer_t *buffer)
wickr_buffer_t * | wickr_packet_serialize (const wickr_packet_t *packet)
wickr_packet_t * | wickr_packet_copy (const wickr_packet_t *source)
void | wickr_packet_destroy (wickr_packet_t **packet)
wickr_parse_result_t * | wickr_parse_result_create_failure (wickr_packet_signature_status signature_status, wickr_decode_error error)
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)
wickr_parse_result_t * | wickr_parse_result_copy (const wickr_parse_result_t *source)
void | wickr_parse_result_destroy (wickr_parse_result_t **result)
wickr_decode_result_t * | wickr_decode_result_create_failure (wickr_decode_error decode_error)
wickr_decode_result_t * | wickr_decode_result_create_success (wickr_payload_t *decrypted_payload, wickr_cipher_key_t *payload_key)
wickr_decode_result_t * | wickr_decode_result_copy (const wickr_decode_result_t *result)
void | wickr_decode_result_destroy (wickr_decode_result_t **result)
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)
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)
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)

## 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

  result | the 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_error | the 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_payload | the decrypted payload found during decoding
  payload_key | the 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

  result | a 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

  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

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

  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

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

  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

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

  source | the 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

  version | see 'wickr_protocol' property documentation property documentation
  content | see 'wickr_protocol' property documentation property documentation
  signature | see '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

  buffer | a 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

  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

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

  packet | a 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

  packet | the 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

  source | the 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_status | status of packet signature validation
  error | error 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_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

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

  result | a 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

  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

Returns
  a parse result containing a successful or unsuccessful error and signature status