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_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)
wickr_transport_ctx_t * | wickr_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_t * | wickr_transport_ctx_get_local_identity_ptr (const wickr_transport_ctx_t *ctx)
const wickr_identity_chain_t * | wickr_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

enum 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

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

  engine | a crypto engine to be used for the underlying signature, and cipher operations
  local_identity | the identity chain information of the person creating the transport context. This should include private signature keys
  remote_identity | the 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_count | the 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
  callbacks | a 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
  user | a 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

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

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

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

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

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

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

  ctx | the context to process the buffer with
  buffer | the 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

  ctx | the context to process the buffer with
  buffer | the 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

  ctx | the transport context to set the user supplied context info to
  user | the 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

  ctx | the transport to start the handshake on