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
handshakethe 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
enginea crypto engine to use for underlying crypto operations
local_identitythe identity chain of the current local user, must include private keys for signing
remote_identitya known identity chain of the recipient of the handshake request. This will prevent calls to identity_callback (optional)
identity_callbackif no remote_identity is specified, the learned identity of the remote party will be validated by the transport ctx using a callback
evo_countused to negotiate the key evolution protocol that will be used by either party after the handshake is over
usera 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
handshakea 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
handshakethe 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
handshakethe 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
handshakethe 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
handshakethe 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
handshakethe 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
handshakethe handshake to process the packet in
packetthe 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
resthe 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_keylocal stream key to use for the result
remote_keyremote 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
resa 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
resthe 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
resthe 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
handshakethe 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
handshakethe handshake to verify the remote identity of
is_validtell 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
handshakethe handshake to get the user provided data of
userthe new user provided data
Generated by doxygen 1.9.0