wickr-crypto-c

wickr_ctx.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 wickr_ctx_h
23 #define wickr_ctx_h
24
25 #include "eckey.h"
26 #include "devinfo.h"
27 #include "root_keys.h"
28 #include "ephemeral_keypair.h"
29 #include "storage.h"
30 #include "identity.h"
31 #include "protocol.h"
32 #include "encoder_result.h"
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 /****************************************
39 ****************************************
40 ** __ ___ _ **
41 ** \ \ / (_) | | **
42 ** \ \ /\ / / _ ___| | ___ __ **
43 ** \ \/ \/ / | |/ __| |/ / '__| **
44 ** \ /\ / | | (__| <| | **
45 ** \/ \/ |_|\___|_|\_\_| **
46 ** **
47 ****************************************
48 ***************************************/
49
73 struct wickr_ctx {
74 wickr_crypto_engine_t engine;
75 wickr_dev_info_t *dev_info;
76 wickr_identity_chain_t *id_chain;
77 wickr_storage_keys_t *storage_keys;
78 wickr_cipher_key_t *packet_header_key;
79 uint8_t pkt_enc_version;
80 };
81
82 typedef struct wickr_ctx wickr_ctx_t;
83
84 #define DEFAULT_PKT_ENC_VERSION 4
85
98 struct wickr_ctx_gen_result {
99 wickr_ctx_t *ctx;
100 wickr_cipher_key_t *recovery_key;
101 wickr_root_keys_t *root_keys;
102 };
103
104 typedef struct wickr_ctx_gen_result wickr_ctx_gen_result_t;
105
106 /* Generation Functions */
107
119 wickr_ctx_gen_result_t *wickr_ctx_gen_new(const wickr_crypto_engine_t engine,
120 wickr_dev_info_t *dev_info,
121 wickr_buffer_t *identifier);
122
135 wickr_ctx_gen_result_t *wickr_ctx_gen_new_with_sig_key(const wickr_crypto_engine_t engine,
136 wickr_dev_info_t *dev_info,
137 wickr_ec_key_t *sig_key,
138 wickr_buffer_t *identifier);
139
154 wickr_ctx_gen_result_t *wickr_ctx_gen_with_root_keys(const wickr_crypto_engine_t engine,
155 wickr_dev_info_t *dev_info,
156 wickr_root_keys_t *root_keys,
157 wickr_buffer_t *identifier);
158
175 wickr_ctx_gen_result_t *wickr_ctx_gen_with_passphrase(const wickr_crypto_engine_t engine,
176 wickr_dev_info_t *dev_info,
177 wickr_buffer_t *exported_recovery_key,
178 wickr_buffer_t *passphrase,
179 wickr_buffer_t *recovery_data,
180 wickr_buffer_t *identifier);
181
196 wickr_ctx_gen_result_t *wickr_ctx_gen_with_recovery(const wickr_crypto_engine_t engine,
197 wickr_dev_info_t *dev_info,
198 wickr_buffer_t *recovery_data,
199 wickr_cipher_key_t *recovery_key,
200 wickr_buffer_t *identifier);
201
216 wickr_buffer_t *wickr_ctx_gen_export_recovery_key_passphrase(const wickr_ctx_gen_result_t *result, const wickr_buffer_t *passphrase);
217
226 wickr_cipher_key_t *wickr_ctx_gen_import_recovery_key_passphrase(const wickr_crypto_engine_t engine, const wickr_buffer_t *exported_recovery_key, const wickr_buffer_t *passphrase);
227
235 wickr_buffer_t *wickr_ctx_gen_result_make_recovery(const wickr_ctx_gen_result_t *result);
236
245 wickr_root_keys_t *wickr_ctx_gen_import_recovery(const wickr_crypto_engine_t engine,
246 const wickr_buffer_t *recovery_data,
247 const wickr_cipher_key_t *recovery_key);
248
258 wickr_ctx_gen_result_t *wickr_ctx_gen_result_copy(const wickr_ctx_gen_result_t *source);
259
260
269 void wickr_ctx_gen_result_destroy(wickr_ctx_gen_result_t **result);
270
271 /* Context Functions */
272
284 wickr_ctx_t *wickr_ctx_create(const wickr_crypto_engine_t engine,
285 wickr_dev_info_t *dev_info,
286 wickr_identity_chain_t *id_chain,
287 wickr_storage_keys_t *storage_keys);
288
298 wickr_ctx_t *wickr_ctx_copy(const wickr_ctx_t *ctx);
299
308 void wickr_ctx_destroy(wickr_ctx_t **ctx);
309
319 wickr_buffer_t *wickr_ctx_serialize(const wickr_ctx_t *ctx);
320
332 wickr_ctx_t *wickr_ctx_create_from_buffer(const wickr_crypto_engine_t engine,
333 wickr_dev_info_t *dev_info,
334 const wickr_buffer_t *buffer);
335
345 wickr_buffer_t *wickr_ctx_export(const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase);
346
357 wickr_ctx_t *wickr_ctx_import(const wickr_crypto_engine_t engine,
358 wickr_dev_info_t *dev_info,
359 const wickr_buffer_t *exported,
360 const wickr_buffer_t *passphrase);
361
374 wickr_buffer_t *wickr_ctx_export_storage_keys(const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase);
375
385 wickr_storage_keys_t *wickr_ctx_import_storage_keys(const wickr_crypto_engine_t engine,
386 const wickr_buffer_t *exported,
387 const wickr_buffer_t *passphrase);
388
398 wickr_cipher_result_t *wickr_ctx_cipher_local(const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext);
399
407 wickr_buffer_t *wickr_ctx_decipher_local(const wickr_ctx_t *ctx, const wickr_cipher_result_t *cipher_text);
408
417 wickr_cipher_result_t *wickr_ctx_cipher_remote(const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext);
418
428 wickr_buffer_t *wickr_ctx_decipher_remote(const wickr_ctx_t *ctx, const wickr_cipher_result_t *cipher_text);
429
441 wickr_ephemeral_keypair_t *wickr_ctx_ephemeral_keypair_gen(const wickr_ctx_t *ctx, uint64_t key_id);
442
455 struct wickr_ctx_packet {
456 wickr_packet_t *packet;
457 wickr_identity_chain_t *sender;
458 wickr_parse_result_t *parse_result;
459 };
460
461 typedef struct wickr_ctx_packet wickr_ctx_packet_t;
462
473 wickr_ctx_packet_t *wickr_ctx_packet_create(wickr_packet_t *packet,
474 wickr_identity_chain_t *sender,
475 wickr_parse_result_t *parse_result);
476
484 void wickr_ctx_packet_destroy(wickr_ctx_packet_t **packet);
485
486 /* Message Encode / Decode */
487
498 wickr_encoder_result_t *wickr_ctx_encode_packet(const wickr_ctx_t *ctx,
499 const wickr_payload_t *payload,
500 const wickr_node_array_t *nodes);
501
512 wickr_ctx_packet_t *wickr_ctx_parse_packet(const wickr_ctx_t *ctx,
513 const wickr_buffer_t *packet_buffer,
514 const wickr_identity_chain_t *sender);
515
524 wickr_ctx_packet_t *wickr_ctx_parse_packet_no_decode(const wickr_ctx_t *ctx,
525 const wickr_buffer_t *packet_buffer,
526 const wickr_identity_chain_t *sender);
527
538 wickr_decode_result_t *wickr_ctx_decode_packet(const wickr_ctx_t *ctx,
539 const wickr_ctx_packet_t *packet,
540 wickr_ec_key_t *keypair);
541
542 #ifdef __cplusplus
543 }
544 #endif
545
546 #endif /* wickr_ctx_h */
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)
wickr_ctx_cipher_remote
wickr_cipher_result_t * wickr_ctx_cipher_remote(const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext)
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)
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)
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)
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)
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)
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)
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)
wickr_ctx_ephemeral_keypair_gen
wickr_ephemeral_keypair_t * wickr_ctx_ephemeral_keypair_gen(const wickr_ctx_t *ctx, uint64_t key_id)
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)
wickr_ctx_export
wickr_buffer_t * wickr_ctx_export(const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase)
wickr_ctx_export_storage_keys
wickr_buffer_t * wickr_ctx_export_storage_keys(const wickr_ctx_t *ctx, const wickr_buffer_t *passphrase)
wickr_ctx_gen_result_destroy
void wickr_ctx_gen_result_destroy(wickr_ctx_gen_result_t **result)
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)
wickr_ctx_gen_result_make_recovery
wickr_buffer_t * wickr_ctx_gen_result_make_recovery(const wickr_ctx_gen_result_t *result)
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)
wickr_ctx_copy
wickr_ctx_t * wickr_ctx_copy(const wickr_ctx_t *ctx)
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)
wickr_ctx_destroy
void wickr_ctx_destroy(wickr_ctx_t **ctx)
wickr_ctx_decipher_remote
wickr_buffer_t * wickr_ctx_decipher_remote(const wickr_ctx_t *ctx, const wickr_cipher_result_t *cipher_text)
wickr_ctx_packet_destroy
void wickr_ctx_packet_destroy(wickr_ctx_packet_t **packet)
wickr_ctx_gen_result_copy
wickr_ctx_gen_result_t * wickr_ctx_gen_result_copy(const wickr_ctx_gen_result_t *source)
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)
wickr_ctx_cipher_local
wickr_cipher_result_t * wickr_ctx_cipher_local(const wickr_ctx_t *ctx, const wickr_buffer_t *plaintext)
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)
wickr_ctx_serialize
wickr_buffer_t * wickr_ctx_serialize(const wickr_ctx_t *ctx)
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_crypto_engine
Interface to a set of cryptographic operations used throughout the library. Currently the default imp...
Definition: crypto_engine.h:53
wickr_ctx_gen_result
the output of a context generation
Definition: wickr_ctx.h:98
wickr_ctx_gen_result::recovery_key
wickr_cipher_key_t * recovery_key
Definition: wickr_ctx.h:100
wickr_ctx_gen_result::root_keys
wickr_root_keys_t * root_keys
Definition: wickr_ctx.h:101
wickr_ctx_gen_result::ctx
wickr_ctx_t * ctx
Definition: wickr_ctx.h:99
wickr_ctx_packet
a parsed inbound wickr packet that has yet to be decoded by this context
Definition: wickr_ctx.h:455
wickr_ctx_packet::packet
wickr_packet_t * packet
Definition: wickr_ctx.h:456
wickr_ctx_packet::parse_result
wickr_parse_result_t * parse_result
Definition: wickr_ctx.h:458
wickr_ctx_packet::sender
wickr_identity_chain_t * sender
Definition: wickr_ctx.h:457
wickr_ctx
Wickr encryption context for high level management of sending / receiving packets using the Wickr pro...
Definition: wickr_ctx.h:73
wickr_ctx::dev_info
wickr_dev_info_t * dev_info
Definition: wickr_ctx.h:75
wickr_ctx::id_chain
wickr_identity_chain_t * id_chain
Definition: wickr_ctx.h:76
wickr_ctx::engine
wickr_crypto_engine_t engine
Definition: wickr_ctx.h:74
wickr_ctx::packet_header_key
wickr_cipher_key_t * packet_header_key
Definition: wickr_ctx.h:78
wickr_ctx::storage_keys
wickr_storage_keys_t * storage_keys
Definition: wickr_ctx.h:77
wickr_ctx::pkt_enc_version
uint8_t pkt_enc_version
Definition: wickr_ctx.h:79
wickr_decode_result
a packet decoding result
Definition: protocol.h:334
wickr_dev_info
Device Information used to make a uniquely identifying set of data for each context running the Wickr...
Definition: devinfo.h:58
wickr_ec_key
Representation of public and private Elliptic Curve Keypair information as buffers.
Definition: eckey.h:92
wickr_encoder_result
the result of a packet encoding operation
Definition: encoder_result.h:45
wickr_ephemeral_keypair
Represents a key pair used for message key exchanges within the Wickr Messaging Protocol.
Definition: ephemeral_keypair.h:62
wickr_identity_chain
Represents a root -> node relationship as well as it's signature status.
Definition: identity.h:116
wickr_packet
An encrypted packet made with the Wickr protocol.
Definition: protocol.h:188
wickr_parse_result
result from parsing an inbound packet
Definition: protocol.h:266
wickr_payload
The encrypted body content of a Wickr packet.
Definition: payload.h:46
wickr_root_keys
Root level crypto keys for signatures, local encryption, and remote encryption.
Definition: root_keys.h:50
wickr_storage_keys
Key's used for the client to encrypt data meant for itself, and not for other clients.
Definition: storage.h:48