wickr-crypto-c

protocol.h
1 /*
2 * Copyright © 2012-2020 Wickr Inc. All rights reserved.
3 *
4 * This code is being released for EDUCATIONAL, ACADEMIC, AND CODE REVIEW PURPOSES
5 * ONLY. COMMERCIAL USE OF THE CODE IS EXPRESSLY PROHIBITED. For additional details,
6 * please see LICENSE
7 *
8 * THE CODE IS MADE AVAILABLE "AS-IS" AND WITHOUT ANY EXPRESS OR
9 * IMPLIED GUARANTEES AS TO FITNESS, MERCHANTABILITY, NON-
10 * INFRINGEMENT OR OTHERWISE. IT IS NOT BEING PROVIDED IN TRADE BUT ON
11 * A VOLUNTARY BASIS ON BEHALF OF THE AUTHOR’S PART FOR THE BENEFIT
12 * OF THE LICENSEE AND IS NOT MADE AVAILABLE FOR CONSUMER USE OR ANY
13 * OTHER USE OUTSIDE THE TERMS OF THIS LICENSE. ANYONE ACCESSING THE
14 * CODE SHOULD HAVE THE REQUISITE EXPERTISE TO SECURE THEIR SYSTEM
15 * AND DEVICES AND TO ACCESS AND USE THE CODE FOR REVIEW PURPOSES
16 * ONLY. LICENSEE BEARS THE RISK OF ACCESSING AND USING THE CODE. IN
17 * PARTICULAR, AUTHOR BEARS NO LIABILITY FOR ANY INTERFERENCE WITH OR
18 * ADVERSE EFFECT THAT MAY OCCUR AS A RESULT OF THE LICENSEE
19 * ACCESSING AND/OR USING THE CODE ON LICENSEE’S SYSTEM.
20 */
21
22 #ifndef protocol_h
23 #define protocol_h
24
25 #include <stdlib.h>
26 #include "node.h"
27 #include "key_exchange.h"
28 #include "payload.h"
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
42 #define OLDEST_PACKET_VERSION 2
43
48 #define CURRENT_PACKET_VERSION 4
49
50 typedef enum {
51 E_SUCCESS,
52 ERROR_INVALID_INPUT,
53 ERROR_NODE_NOT_FOUND,
54 ERROR_CORRUPT_PACKET,
55 ERROR_KEY_EXCHANGE_FAILED,
56 ERROR_MAC_INVALID
57 } wickr_decode_error;
58
59 typedef enum {
60 PACKET_SIGNATURE_UNKNOWN,
61 PACKET_SIGNATURE_VALID,
62 PACKET_SIGNATURE_INVALID
63 } wickr_packet_signature_status;
64
86 wickr_key_exchange_t *wickr_key_exchange_create_with_packet_key(const wickr_crypto_engine_t *engine,
87 const wickr_identity_chain_t *sender,
88 const wickr_node_t *receiver,
89 wickr_ec_key_t *packet_exchange_key,
90 const wickr_cipher_key_t *packet_key,
91 const wickr_buffer_t *psk,
92 uint8_t version);
93
117 wickr_key_exchange_t *wickr_key_exchange_create_with_data(const wickr_crypto_engine_t *engine,
118 const wickr_identity_chain_t *sender,
119 const wickr_node_t *receiver,
120 wickr_ec_key_t *packet_exchange_key,
121 const wickr_buffer_t *data_to_wrap,
122 wickr_cipher_t exchange_cipher,
123 const wickr_buffer_t *psk,
124 uint8_t version);
125
144 wickr_cipher_key_t *wickr_key_exchange_derive_packet_key(const wickr_crypto_engine_t *engine,
145 const wickr_identity_chain_t *sender,
146 const wickr_node_t *receiver,
147 wickr_ec_key_t *packet_exchange_key,
148 const wickr_key_exchange_t *exchange,
149 const wickr_buffer_t *psk,
150 uint8_t version);
151
168 wickr_buffer_t *wickr_key_exchange_derive_data(const wickr_crypto_engine_t *engine,
169 const wickr_identity_chain_t *sender,
170 const wickr_node_t *receiver,
171 wickr_ec_key_t *packet_exchange_key,
172 const wickr_key_exchange_t *exchange,
173 const wickr_buffer_t *psk,
174 uint8_t version);
175
188 struct wickr_packet {
189 uint8_t version;
190 wickr_buffer_t *content;
191 wickr_ecdsa_result_t *signature;
192 };
193
194 typedef struct wickr_packet wickr_packet_t;
195
206 wickr_packet_t *wickr_packet_create(uint8_t version, wickr_buffer_t *content, wickr_ecdsa_result_t *signature);
207
216 wickr_packet_t *wickr_packet_create_from_buffer(const wickr_buffer_t *buffer);
217
227 wickr_buffer_t *wickr_packet_serialize(const wickr_packet_t *packet);
228
238 wickr_packet_t *wickr_packet_copy(const wickr_packet_t *source);
239
248 void wickr_packet_destroy(wickr_packet_t **packet);
249
266 struct wickr_parse_result {
267 wickr_decode_error err;
268 wickr_packet_signature_status signature_status;
269 wickr_key_exchange_set_t *key_exchange_set;
270 wickr_key_exchange_t *key_exchange;
271 wickr_cipher_result_t *enc_payload;
272 };
273
274 typedef struct wickr_parse_result wickr_parse_result_t;
275
285 wickr_parse_result_t *wickr_parse_result_create_failure(wickr_packet_signature_status signature_status,
286 wickr_decode_error error);
287
298 wickr_parse_result_t *wickr_parse_result_create_success(wickr_key_exchange_set_t *key_exchange_set,
299 wickr_key_exchange_t *key_exchange,
300 wickr_cipher_result_t *enc_payload);
301
311 wickr_parse_result_t *wickr_parse_result_copy(const wickr_parse_result_t *source);
312
321 void wickr_parse_result_destroy(wickr_parse_result_t **result);
322
334 struct wickr_decode_result {
335 wickr_decode_error err;
336 wickr_cipher_key_t *payload_key;
337 wickr_payload_t *decrypted_payload;
338 };
339
340 typedef struct wickr_decode_result wickr_decode_result_t;
341
350 wickr_decode_result_t *wickr_decode_result_create_failure(wickr_decode_error decode_error);
351
361 wickr_decode_result_t *wickr_decode_result_create_success(wickr_payload_t *decrypted_payload,
362 wickr_cipher_key_t *payload_key);
363
373 wickr_decode_result_t *wickr_decode_result_copy(const wickr_decode_result_t *result);
374
383 void wickr_decode_result_destroy(wickr_decode_result_t **result);
384
404 wickr_packet_t *wickr_packet_create_from_components(const wickr_crypto_engine_t *engine,
405 const wickr_cipher_key_t *header_key,
406 const wickr_cipher_key_t *payload_key,
407 wickr_ec_key_t *exchange_key,
408 const wickr_payload_t *payload,
409 const wickr_node_array_t *recipients,
410 const wickr_identity_chain_t *sender_signing_identity,
411 uint8_t version);
412
413 typedef wickr_cipher_key_t *(*wickr_header_keygen_func)(const wickr_crypto_engine_t engine, wickr_cipher_t cipher, const wickr_identity_chain_t *id_chain);
414
431 wickr_parse_result_t *wickr_parse_result_from_packet(const wickr_crypto_engine_t *engine,
432 const wickr_packet_t *packet,
433 const wickr_buffer_t *receiver_node_id,
434 wickr_header_keygen_func header_keygen_func,
435 const wickr_identity_chain_t *sender_signing_identity);
436
455 wickr_decode_result_t *wickr_decode_result_from_parse_result(const wickr_packet_t *packet,
456 const wickr_crypto_engine_t *engine,
457 const wickr_parse_result_t *parse_result,
458 wickr_buffer_t *receiver_dev_id,
459 wickr_ec_key_t *receiver_decode_key,
460 wickr_identity_chain_t *receiver_signing_identity,
461 const wickr_identity_chain_t *sender_signing_identity);
462
463 #ifdef __cplusplus
464 }
465 #endif
466
467 #endif /* protocol_h */
wickr_packet_copy
wickr_packet_t * wickr_packet_copy(const wickr_packet_t *source)
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)
wickr_parse_result_copy
wickr_parse_result_t * wickr_parse_result_copy(const wickr_parse_result_t *source)
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)
wickr_decode_result_create_failure
wickr_decode_result_t * wickr_decode_result_create_failure(wickr_decode_error decode_error)
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)
wickr_packet_create_from_buffer
wickr_packet_t * wickr_packet_create_from_buffer(const wickr_buffer_t *buffer)
wickr_decode_result_copy
wickr_decode_result_t * wickr_decode_result_copy(const wickr_decode_result_t *result)
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)
wickr_parse_result_destroy
void wickr_parse_result_destroy(wickr_parse_result_t **result)
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)
wickr_decode_result_destroy
void wickr_decode_result_destroy(wickr_decode_result_t **result)
wickr_packet_serialize
wickr_buffer_t * wickr_packet_serialize(const wickr_packet_t *packet)
wickr_packet_destroy
void wickr_packet_destroy(wickr_packet_t **packet)
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)
wickr_parse_result_create_failure
wickr_parse_result_t * wickr_parse_result_create_failure(wickr_packet_signature_status signature_status, wickr_decode_error error)
wickr_packet_create
wickr_packet_t * wickr_packet_create(uint8_t version, wickr_buffer_t *content, wickr_ecdsa_result_t *signature)
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)
wickr_buffer
Represents an array of bytes and the length of the allocation associated with those bytes.
Definition: buffer.h:51
wickr_cipher_key
Definition: cipher.h:189
wickr_cipher_result
Definition: cipher.h:97
wickr_cipher
Represents a cipher that can be used in the crypto_engine. This meta object holds parameters for the ...
Definition: cipher.h:56
wickr_crypto_engine
Interface to a set of cryptographic operations used throughout the library. Currently the default imp...
Definition: crypto_engine.h:53
wickr_decode_result
a packet decoding result
Definition: protocol.h:334
wickr_decode_result::decrypted_payload
wickr_payload_t * decrypted_payload
Definition: protocol.h:337
wickr_decode_result::err
wickr_decode_error err
Definition: protocol.h:335
wickr_decode_result::payload_key
wickr_cipher_key_t * payload_key
Definition: protocol.h:336
wickr_ec_key
Representation of public and private Elliptic Curve Keypair information as buffers.
Definition: eckey.h:92
wickr_ecdsa_result
Elliptic Curve Digital Signature Algorithm Result.
Definition: ecdsa.h:54
wickr_identity_chain
Represents a root -> node relationship as well as it's signature status.
Definition: identity.h:116
wickr_key_exchange_set
A collection of key exchanges for a set of recipients. The data protected inside 'exchange_ciphertext...
Definition: key_exchange.h:169
wickr_key_exchange
Public key exchange protected data. After a shared secret is generated using a public key with identi...
Definition: key_exchange.h:53
wickr_node
Represents a message destination at a point in time.
Definition: node.h:87
wickr_packet
An encrypted packet made with the Wickr protocol.
Definition: protocol.h:188
wickr_packet::version
uint8_t version
Definition: protocol.h:189
wickr_packet::content
wickr_buffer_t * content
Definition: protocol.h:190
wickr_packet::signature
wickr_ecdsa_result_t * signature
Definition: protocol.h:191
wickr_parse_result
result from parsing an inbound packet
Definition: protocol.h:266
wickr_parse_result::enc_payload
wickr_cipher_result_t * enc_payload
Definition: protocol.h:271
wickr_parse_result::err
wickr_decode_error err
Definition: protocol.h:267
wickr_parse_result::signature_status
wickr_packet_signature_status signature_status
Definition: protocol.h:268
wickr_parse_result::key_exchange_set
wickr_key_exchange_set_t * key_exchange_set
Definition: protocol.h:269
wickr_parse_result::key_exchange
wickr_key_exchange_t * key_exchange
Definition: protocol.h:270
wickr_payload
The encrypted body content of a Wickr packet.
Definition: payload.h:46