wickr-crypto-c
Data Structures | Functions
Wickr_transport_ctx

Data Structures

struct  wickr_transport_ctx
 Transport context to manage the state machine of a point to point connection using fundamentals of the Wickr protocol as building blocks. More...
 
struct  wickr_transport_callbacks
 callbacks to notify the user of events within the transport More...
 

Functions

wickr_transport_ctx_twickr_transport_ctx_create (const wickr_crypto_engine_t engine, wickr_node_t *local_identity, wickr_node_t *remote_identity, uint32_t evo_count, wickr_transport_callbacks_t callbacks, void *user)
 
wickr_transport_ctx_twickr_transport_ctx_copy (const wickr_transport_ctx_t *ctx)
 
void wickr_transport_ctx_destroy (wickr_transport_ctx_t **ctx)
 
void wickr_transport_ctx_start (wickr_transport_ctx_t *ctx)
 
wickr_buffer_twickr_transport_ctx_process_tx_buffer (wickr_transport_ctx_t *ctx, const wickr_buffer_t *buffer)
 
wickr_buffer_twickr_transport_ctx_process_rx_buffer (wickr_transport_ctx_t *ctx, const wickr_buffer_t *buffer)
 
wickr_transport_status wickr_transport_ctx_get_status (const wickr_transport_ctx_t *ctx)
 
const wickr_buffer_twickr_transport_ctx_get_rxstream_user_data (const wickr_transport_ctx_t *ctx)
 
const wickr_node_twickr_transport_ctx_get_local_node_ptr (const wickr_transport_ctx_t *ctx)
 
const wickr_node_twickr_transport_ctx_get_remote_node_ptr (const wickr_transport_ctx_t *ctx)
 
const void * wickr_transport_ctx_get_user_ctx (const wickr_transport_ctx_t *ctx)
 
void wickr_transport_ctx_set_user_ctx (wickr_transport_ctx_t *ctx, void *user)
 
const wickr_buffer_twickr_transport_ctx_get_user_psk (const wickr_transport_ctx_t *ctx)
 
wickr_transport_data_flow wickr_transport_ctx_get_data_flow_mode (const wickr_transport_ctx_t *ctx)
 
void wickr_transport_ctx_set_data_flow_mode (wickr_transport_ctx_t *ctx, wickr_transport_data_flow flow_mode)
 
const wickr_transport_callbacks_twickr_transport_ctx_get_callbacks (const wickr_transport_ctx_t *ctx)
 
void wickr_transport_ctx_set_callbacks (wickr_transport_ctx_t *ctx, const wickr_transport_callbacks_t *callbacks)
 
bool wickr_transport_ctx_force_tx_key_evo (wickr_transport_ctx_t *ctx)
 

Detailed Description

Function Documentation

◆ wickr_transport_ctx_copy()

wickr_transport_ctx_t* wickr_transport_ctx_copy ( const wickr_transport_ctx_t ctx)

Copy a transport context

Parameters
ctxthe transport context to copy
Returns
a newly allocated transport context holding a deep copy of properties from 'ctx'

◆ wickr_transport_ctx_create()

wickr_transport_ctx_t* wickr_transport_ctx_create ( const wickr_crypto_engine_t  engine,
wickr_node_t local_identity,
wickr_node_t remote_identity,
uint32_t  evo_count,
wickr_transport_callbacks_t  callbacks,
void *  user 
)

Create a transport context from components

Parameters
enginea crypto engine to be used for the underlying signature, and cipher operations
local_identitythe node information of the person creating the transport context. This should include private signature keys
remote_identitythe node information of the endpoint 'local_identity' is connecting too. This field is OPTIONAL. If this field is set, the signature keys provided inside this property will be pinned, and the 'on_identity_verify' callback will not be called during connection. The remote_identity passed in here does not need to contain an 'ephemeral_keypair' property, because it will be provided by the remote party during connection, and verified by the node / root signature keys inside the identity
evo_countthe evolution packet count to be passed to the creation of underlying 'wickr_stream_ctx_t' that are created by this transport internally, see 'wickr_stream_ctx_t' for more information
callbacksa set of function pointers the 'wickr_transport_ctx_t' will use to pass data, state change information, and identity verification prompts up to the user for processing. This is the I/O of the transport_ctx
usera pointer to be held and passed to all callbacks
Returns
a newly allocated transport context owning the properties passed in

◆ wickr_transport_ctx_destroy()

void wickr_transport_ctx_destroy ( wickr_transport_ctx_t **  ctx)

Destroy a transport context

Parameters
ctxa pointer to the transport context to destroy. All properties of '*ctx' will also be destroyed

◆ wickr_transport_ctx_force_tx_key_evo()

bool wickr_transport_ctx_force_tx_key_evo ( wickr_transport_ctx_t ctx)

Force the tx stream to perform a tx stream key evolution immediately

Parameters
ctxthe transport context evolove the tx stream key of
Returns
true if the key evolution was successful

◆ wickr_transport_ctx_get_callbacks()

const wickr_transport_callbacks_t* wickr_transport_ctx_get_callbacks ( const wickr_transport_ctx_t ctx)

Get a pointer to the current set of callbacks for a transport

Parameters
ctxthe transport context to get the callbacks of
Returns
a pointer to the current set of callbacks the transport is using

◆ wickr_transport_ctx_get_data_flow_mode()

wickr_transport_data_flow wickr_transport_ctx_get_data_flow_mode ( const wickr_transport_ctx_t ctx)

Get the current data flow mode

Parameters
ctxthe transport context to get the data flow mode of
Returns
the current data flow mode for 'ctx', see 'wickr_transport_data_flow' for more info

◆ wickr_transport_ctx_get_local_node_ptr()

const wickr_node_t* wickr_transport_ctx_get_local_node_ptr ( const wickr_transport_ctx_t ctx)

Get the local node information

Parameters
ctxthe transport context to get the local node information of
Returns
local node information or NULL if no information is available due to the state of the transport context

◆ wickr_transport_ctx_get_remote_node_ptr()

const wickr_node_t* wickr_transport_ctx_get_remote_node_ptr ( const wickr_transport_ctx_t ctx)

Get the remote node information

Parameters
ctxthe transport context to get the remote node information of
Returns
remote node information or NULL if no information is available due to the state of the transport context

◆ wickr_transport_ctx_get_rxstream_user_data()

const wickr_buffer_t* wickr_transport_ctx_get_rxstream_user_data ( const wickr_transport_ctx_t ctx)

Get the user data associated with the current rx stream's stream key

Parameters
ctxthe transport context to get the rx stream user data of
Returns
the current rx stream key's user data field, or NULL if no data is available

◆ wickr_transport_ctx_get_status()

wickr_transport_status wickr_transport_ctx_get_status ( const wickr_transport_ctx_t ctx)

Get the current status of a transport context

Parameters
ctxthe transport context to get the status of
Returns
the current status of 'ctx'

◆ wickr_transport_ctx_get_user_ctx()

const void* wickr_transport_ctx_get_user_ctx ( const wickr_transport_ctx_t ctx)

Get the current user context pointer

Parameters
ctxthe context to get the user context pointer of
Returns
the current user context pointer

◆ wickr_transport_ctx_get_user_psk()

const wickr_buffer_t* wickr_transport_ctx_get_user_psk ( const wickr_transport_ctx_t ctx)

Get the current user PSK, see 'wickr_transport_ctx_set_user_psk' for more information

Parameters
ctxthe transport context to get the psk data from
Returns
the current psk data for 'ctx'

◆ wickr_transport_ctx_process_rx_buffer()

wickr_buffer_t* wickr_transport_ctx_process_rx_buffer ( wickr_transport_ctx_t ctx,
const wickr_buffer_t buffer 
)

Process a buffer that was received from the remote via a transport layer. This may include handshake data or encrypted content

Parameters
ctxthe context to process the buffer with
bufferthe buffer to be processed by by 'ctx'
Returns
the decoded tx buffer or NULL if decryption fails. As with all other incoming packets, it will also trigger a rx callback

◆ wickr_transport_ctx_process_tx_buffer()

wickr_buffer_t* wickr_transport_ctx_process_tx_buffer ( wickr_transport_ctx_t ctx,
const wickr_buffer_t buffer 
)

Process a buffer that should be sent to the remote party

NOTE: This function requires the transport context to be in ACTIVE status, attempting to process a tx buffer in any other state will cause the transport to enter the error status. When the buffer has completed processing the encrypted payload will be passed back via the wickr_transport_tx_func callback.

Parameters
ctxthe context to process the buffer with
bufferthe buffer to be encrypted and sent over the transport
Returns
the decoded tx buffer or NULL if decryption fails. As with all other incoming packets, it will also trigger a rx callback

◆ wickr_transport_ctx_set_callbacks()

void wickr_transport_ctx_set_callbacks ( wickr_transport_ctx_t ctx,
const wickr_transport_callbacks_t callbacks 
)

Update the callbacks of a transport after it's creation

Parameters
ctxthe transport context to set the callbacks of
callbacksthe callbacks that transport should use after calling this function

◆ wickr_transport_ctx_set_data_flow_mode()

void wickr_transport_ctx_set_data_flow_mode ( wickr_transport_ctx_t ctx,
wickr_transport_data_flow  flow_mode 
)

Set the the data flow mode. This change will be applied immediatly

If the mode is READ_ONLY, attempting to write a packet will silently fail If the mode iw WRITE_ONLY, any incoming packets will be silently dropped

Parameters
ctxthe transport context to set the data flow mode of
flow_modethe flow mode you would like to enact

◆ wickr_transport_ctx_set_user_ctx()

void wickr_transport_ctx_set_user_ctx ( wickr_transport_ctx_t ctx,
void *  user 
)

Set a user context pointer

Parameters
ctxthe transport context to set the user supplied context info to
userthe pointer for the transport context to hold and be passed back in callbacks

◆ wickr_transport_ctx_start()

void wickr_transport_ctx_start ( wickr_transport_ctx_t ctx)

Start the transport 3 way handshake to establish stream cipher keys and begin secure communication. This function can also be used to reestablish a new set of cipher keys if a handshake had previously been completed.

When handshake data is generated, the 'wickr_transport_tx_func' callback will be fired so that it can be forwarded via the proper communication channel. Handshake responses can be passed back into the transport context via the 'wickr_transport_ctx_process_rx_buffer' function. The 'on_state' callback of the transport will be fired to indicate the various stages of the handshake reaching completion, or an error occuring. User data may be passed into the 'wickr_transport_ctx_process_tx_buffer' function after the transport status reaches 'TRANSPORT_STATUS_ACTIVE'. If 'remote_identity' was not set during creation, and thus no remote key information is pinned, the 'on_identity_verify' callback will be called for the application to verify the integrity of the remote's identity via cached information, or whatever other means it has.

Optional callbacks will also be called for when a pre-shared key is required for the key exchange to successfully complete, and when the tx stream is being generated to allow for customization of tx stream key generation and to update the user data field of the tx stream's key

Parameters
ctxthe transport to start the handshake on