wickr-crypto-c

Data Structures | Enumerations | Functions
Wickr_transport_handshake

## Data Structures
struct | wickr_transport_handshake
| Transport handshake to manage the state of a handshake within the context of a wickr transport context. More...

## Enumerations
enum | wickr_transport_handshake_status { TRANSPORT_HANDSHAKE_STATUS_UNKNOWN , TRANSPORT_HANDSHAKE_STATUS_IN_PROGRESS , TRANSPORT_HANDSHAKE_STATUS_PENDING_VERIFICATION , TRANSPORT_HANDSHAKE_STATUS_PENDING_FINALIZATION , TRANSPORT_HANDSHAKE_STATUS_COMPLETE , TRANSPORT_HANDSHAKE_STATUS_FAILED }

## Functions
wickr_transport_handshake_res_t * | wickr_transport_handshake_res_create (wickr_stream_key_t *local_key, wickr_stream_key_t *remote_key)
wickr_transport_handshake_res_t * | wickr_transport_handshake_res_copy (const wickr_transport_handshake_res_t *res)
void | wickr_transport_handshake_res_destroy (wickr_transport_handshake_res_t **res)
const wickr_stream_key_t * | wickr_transport_handshake_res_get_local_key (const wickr_transport_handshake_res_t *res)
const wickr_stream_key_t * | wickr_transport_handshake_res_get_remote_key (const wickr_transport_handshake_res_t *res)
wickr_transport_handshake_t * | wickr_transport_handshake_create (wickr_crypto_engine_t engine, wickr_identity_chain_t *local_identity, wickr_identity_chain_t *remote_identity, wickr_transport_handshake_identity_callback identity_callback, uint32_t evo_count, void *user)
wickr_transport_handshake_t * | wickr_transport_handshake_copy (const wickr_transport_handshake_t *handshake)
void | wickr_transport_handshake_destroy (wickr_transport_handshake_t **handshake)
wickr_transport_packet_t * | wickr_transport_handshake_start (wickr_transport_handshake_t *handshake)
wickr_transport_packet_t * | wickr_transport_handshake_process (wickr_transport_handshake_t *handshake, const wickr_transport_packet_t *packet)
wickr_transport_packet_t * | wickr_transport_handshake_verify_identity (const wickr_transport_handshake_t *handshake, bool is_valid)
wickr_transport_handshake_res_t * | wickr_transport_handshake_finalize (wickr_transport_handshake_t *handshake)
wickr_transport_handshake_status | wickr_transport_handshake_get_status (const wickr_transport_handshake_t *handshake)
const wickr_identity_chain_t * | wickr_transport_handshake_get_local_identity (const wickr_transport_handshake_t *handshake)
const wickr_identity_chain_t * | wickr_transport_handshake_get_remote_identity (const wickr_transport_handshake_t *handshake)
const void * | wickr_transport_handshake_get_user_data (const wickr_transport_handshake_t *handshake)
void | wickr_transport_set_user_data (wickr_transport_handshake_t *handshake, void *user)

## Detailed Description

## Enumeration Type Documentation

## ◆ wickr_transport_handshake_status

enum wickr_transport_handshake_status

Current status of a transport handshake

## Function Documentation

## ◆ wickr_transport_handshake_copy()

wickr_transport_handshake_t* wickr_transport_handshake_copy | ( | const wickr_transport_handshake_t * | handshake | ) |

Make a deep copy of a transport handshake result

Parameters

  handshake | the handshake to make a copy of

Returns
  a newly allocated transport handshake holding a deep copy of the properties of 'handshake'

## ◆ wickr_transport_handshake_create()

wickr_transport_handshake_t* wickr_transport_handshake_create | ( | wickr_crypto_engine_t | engine,
|  | wickr_identity_chain_t * | local_identity,
|  | wickr_identity_chain_t * | remote_identity,
|  | wickr_transport_handshake_identity_callback | identity_callback,
|  | uint32_t | evo_count,
|  | void * | user
| ) |  |

Create a new transport handshake. Will retain ownership of all pointer inputs will be owned except for `user`

Parameters

  engine | a crypto engine to use for underlying crypto operations
  local_identity | the identity chain of the current local user, must include private keys for signing
  remote_identity | a known identity chain of the recipient of the handshake request. This will prevent calls to `identity_callback` (optional)
  identity_callback | if no `remote_identity` is specified, the learned identity of the remote party will be validated by the transport ctx using a callback
  evo_count | used to negotiate the key evolution protocol that will be used by either party after the handshake is over
  user | a pointer to user data that can be held for use in the identity callback

Returns
  a newly allocated transport handshake or NULL if non-optional values are improperly set

## ◆ wickr_transport_handshake_destroy()

void wickr_transport_handshake_destroy | ( | wickr_transport_handshake_t ** | handshake | ) |

Destroy a transport handshake

Parameters

  handshake | a pointer to the transport handshake to destroy. All properties of `*handshake` will also be destroyed

## ◆ wickr_transport_handshake_finalize()

wickr_transport_handshake_res_t* wickr_transport_handshake_finalize | ( | wickr_transport_handshake_t * | handshake | ) |

Finalize a handshake to complete it (can only be called when the handshake is in the TRANSPORT_HANDSHAKE_STATUS_PENDING_FINALIZATION state) A handshake can only be finalized once, at which point it's status will change to TRANSPORT_HANDSHAKE_STATUS_COMPLETE and no other operations are valid

Parameters

  handshake | the handshake to finalize

Returns
  the result of the handshake on success, or NULL on failure

## ◆ wickr_transport_handshake_get_local_identity()

const wickr_identity_chain_t* wickr_transport_handshake_get_local_identity | ( | const wickr_transport_handshake_t * | handshake | ) |

Get the local identity chain of a handshake

Parameters

  handshake | the handshake to get the local identity chain of

Returns
  the current status of the handshake

## ◆ wickr_transport_handshake_get_remote_identity()

const wickr_identity_chain_t* wickr_transport_handshake_get_remote_identity | ( | const wickr_transport_handshake_t * | handshake | ) |

Get the remote identity chain of a handshake

Parameters

  handshake | the handshake to get the remote identity chain of

Returns
  the current status of the handshake

## ◆ wickr_transport_handshake_get_status()

wickr_transport_handshake_status wickr_transport_handshake_get_status | ( | const wickr_transport_handshake_t * | handshake | ) |

Get the current status of a handshake

Parameters

  handshake | the handshake to get the status of

Returns
  the current status of the handshake

## ◆ wickr_transport_handshake_get_user_data()

const void* wickr_transport_handshake_get_user_data | ( | const wickr_transport_handshake_t * | handshake | ) |

Get the current user provided data of a handshake

Parameters

  handshake | the handshake to get the user provided data of

Returns
  the current user provided data of the handshake

## ◆ wickr_transport_handshake_process()

wickr_transport_packet_t* wickr_transport_handshake_process | ( | wickr_transport_handshake_t * | handshake,
|  | const wickr_transport_packet_t * | packet
| ) |  |

Process an inbound transport packet for a handshake. This function cause the handshake to move to the failure state on error. If a handshake is starting by receiving a packet rather than starting, this will be the first function called after being constructed

Parameters

  handshake | the handshake to process the packet in
  packet | the packet to process with `handshake`

Returns
  a return packet to send back to the sender of `packet`. NULL on error or no further packet response required. Call wickr_transport_handshake_get_status to differentiate

## ◆ wickr_transport_handshake_res_copy()

wickr_transport_handshake_res_t* wickr_transport_handshake_res_copy | ( | const wickr_transport_handshake_res_t * | res | ) |

Make a deep copy of a transport handshake result

Parameters

  res | the handshake result to make a copy of

Returns
  a newly allocated transport handshake result set holding a deep copy of the properties of 'res'

## ◆ wickr_transport_handshake_res_create()

wickr_transport_handshake_res_t* wickr_transport_handshake_res_create | ( | wickr_stream_key_t * | local_key,
|  | wickr_stream_key_t * | remote_key
| ) |  |

Create a new transport handshake result from parameters

Parameters

  local_key | local stream key to use for the result
  remote_key | remote stream key to use for the result

Returns
  a newly allocated `wickr_transport_handshake_res_t` using `local_key` and `remote_key`. Takes ownership of the passed inputs

## ◆ wickr_transport_handshake_res_destroy()

void wickr_transport_handshake_res_destroy | ( | wickr_transport_handshake_res_t ** | res | ) |

Destroy a transport handshake result

Parameters

  res | a pointer to the transport handshake result set to destroy. All properties of `*res` will also be destroyed

## ◆ wickr_transport_handshake_res_get_local_key()

const wickr_stream_key_t* wickr_transport_handshake_res_get_local_key | ( | const wickr_transport_handshake_res_t * | res | ) |

Get a pointer to the handshake result's local key

Parameters

  res | the transport handshake to get the local key of

Returns
  a reference to the handshake result's local key

## ◆ wickr_transport_handshake_res_get_remote_key()

const wickr_stream_key_t* wickr_transport_handshake_res_get_remote_key | ( | const wickr_transport_handshake_res_t * | res | ) |

Get a pointer to the handshake result's remote key

Parameters

  res | the transport handshake to get the remote key of

Returns
  a reference to the handshake result's remote key

## ◆ wickr_transport_handshake_start()

wickr_transport_packet_t* wickr_transport_handshake_start | ( | wickr_transport_handshake_t * | handshake | ) |

Start the handshake process. Calling this function will change the status of the handshake to `TRANSPORT_HANDSHAKE_STATUS_IN_PROGRESS`. This function can only be called if the handshake is currently in the TRANSPORT_HANDSHAKE_STATUS_UNKNOWN state (saw no other activity)

Parameters

  handshake | the transport handshake to start

Returns
  the transport packet to relay back to transport_ctx to send to the remote party. Returns NULL on failure, along with setting the transport status to TRANSPORT_HANDSHAKE_STATUS_FAILED

## ◆ wickr_transport_handshake_verify_identity()

wickr_transport_packet_t* wickr_transport_handshake_verify_identity | ( | const wickr_transport_handshake_t * | handshake,
|  | bool | is_valid
| ) |  |

Tell the handshake if a remote identity is valid or not to move on from the TRANSPORT_HANDSHAKE_STATUS_PENDING_VERIFICATION state

Parameters

  handshake | the handshake to verify the remote identity of
  is_valid | tell the handshake if the remote identity is valid or not

Returns
  a return packet to send back to the remote side (if needed). NULL on `is_valid` being false, no further communication required or other error Call wickr_transport_handshake_get_status to differentiate

## ◆ wickr_transport_set_user_data()

void wickr_transport_set_user_data | ( | wickr_transport_handshake_t * | handshake,
|  | void * | user
| ) |  |

Set the current user provided data of a handshake

Parameters

  handshake | the handshake to get the user provided data of
  user | the new user provided data