wickr-crypto-c
Data Structures | Enumerations | 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...
 

Enumerations

enum  wickr_transport_error {
  TRANSPORT_ERROR_NONE, TRANSPORT_ERROR_HANDSHAKE_FAILED, TRANSPORT_ERROR_CREATE_HANDSHAKE_FAILED, TRANSPORT_ERROR_START_HANDSHAKE_FAILED,
  TRANSPORT_ERROR_PROCESS_HANDSHAKE_FAILED, TRANSPORT_ERROR_HANDSHAKE_VOLLEY_FAILED, TRANSPORT_ERROR_BAD_START_STATUS, TRANSPORT_ERROR_BAD_RX_STATE,
  TRANSPORT_ERROR_BAD_TX_STATE, TRANSPORT_ERROR_PACKET_ENCODE_FAILED, TRANSPORT_ERROR_PACKET_DECODE_FAILED, TRANSPORT_ERROR_PACKET_SERIALIZATION_FAILED,
  TRANSPORT_ERROR_INVALID_RXDATA
}
 

Functions

wickr_transport_ctx_twickr_transport_ctx_create (const wickr_crypto_engine_t engine, wickr_identity_chain_t *local_identity, wickr_identity_chain_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)
 
void wickr_transport_ctx_process_tx_buffer (wickr_transport_ctx_t *ctx, const wickr_buffer_t *buffer)
 
void wickr_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_identity_chain_twickr_transport_ctx_get_local_identity_ptr (const wickr_transport_ctx_t *ctx)
 
const wickr_identity_chain_twickr_transport_ctx_get_remote_identity_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)
 
wickr_transport_error wickr_transport_ctx_get_last_error (const wickr_transport_ctx_t *ctx)
 

Detailed Description

Enumeration Type Documentation

◆ wickr_transport_error

Wickr Transport Context Errors

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_identity_chain_t local_identity,
wickr_identity_chain_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 identity chain information of the person creating the transport context. This should include private signature keys
remote_identitythe identity chain 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_get_last_error()

wickr_transport_error wickr_transport_ctx_get_last_error ( const wickr_transport_ctx_t ctx)

Get the most recent error from the context,set whenever the status of the context changes to TRANSPORT_STATUS_ERROR

Parameters
ctxthe transport context to get the most recent error of
Returns
the most recent error inside the transport context

◆ wickr_transport_ctx_get_local_identity_ptr()

const wickr_identity_chain_t* wickr_transport_ctx_get_local_identity_ptr ( const wickr_transport_ctx_t ctx)

Get the local node information

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

◆ wickr_transport_ctx_get_remote_identity_ptr()

const wickr_identity_chain_t* wickr_transport_ctx_get_remote_identity_ptr ( const wickr_transport_ctx_t ctx)

Get the remote node information

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

◆ 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_process_rx_buffer()

void 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'

◆ wickr_transport_ctx_process_tx_buffer()

void 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

◆ 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 handshake to establish stream cipher keys and begin secure communication

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.

Parameters
ctxthe transport to start the handshake on