wickr_identity

Data Structures
struct	wickr_identity
	A signing identity on the Wickr system. More...
struct	wickr_identity_chain
	Represents a root -> node relationship as well as it's signature status. More...

Macros
#define	IDENTIFIER_LEN   32
#define	MAX_IDENTIFIER_LEN   128

Enumerations
enum	wickr_identity_chain_status { IDENTITY_CHAIN_STATUS_UNKNOWN , IDENTITY_CHAIN_STATUS_VALID , IDENTITY_CHAIN_STATUS_INVALID }

Functions
wickr_identity_t *	wickr_identity_create (wickr_identity_type type, wickr_buffer_t *identifier, wickr_ec_key_t *sig_key, wickr_ecdsa_result_t *signature)
wickr_ecdsa_result_t *	wickr_identity_sign (const wickr_identity_t *identity, const wickr_crypto_engine_t *engine, const wickr_buffer_t *data)
wickr_identity_t *	wickr_node_identity_gen (const wickr_crypto_engine_t *engine, const wickr_identity_t *root_identity, const wickr_buffer_t *identifier)
wickr_identity_t *	wickr_identity_copy (const wickr_identity_t *source)
void	wickr_identity_destroy (wickr_identity_t **identity)
wickr_buffer_t *	wickr_identity_serialize (const wickr_identity_t *identity)
wickr_identity_t *	wickr_identity_create_from_buffer (const wickr_buffer_t *buffer, const wickr_crypto_engine_t *engine)
wickr_fingerprint_t *	wickr_identity_get_fingerprint (const wickr_identity_t *identity, wickr_crypto_engine_t engine)
wickr_fingerprint_t *	wickr_identity_get_bilateral_fingerprint (const wickr_identity_t *identity, const wickr_identity_t *remote_identity, wickr_crypto_engine_t engine)
wickr_identity_chain_t *	wickr_identity_chain_create (wickr_identity_t *root, wickr_identity_t *node)
wickr_identity_chain_t *	wickr_identity_chain_copy (const wickr_identity_chain_t *source)
bool	wickr_identity_chain_validate (wickr_identity_chain_t *chain, const wickr_crypto_engine_t *engine)
void	wickr_identity_chain_destroy (wickr_identity_chain_t **chain)

Detailed Description

Macro Definition Documentation

IDENTIFIER_LEN

#define IDENTIFIER_LEN   32

By default identifiers are 32 bytes on the Wickr system, however this library will allow for any identifier with length less than MAX_IDENTIFIER_LEN

MAX_IDENTIFIER_LEN

#define MAX_IDENTIFIER_LEN   128

Maximum length for an identifier

Enumeration Type Documentation

wickr_identity_chain_status

enum wickr_identity_chain_status

Identity chain status

UNKNOWN - Signature validation has never been attempted on the chain VALID - Signature validation has been attempted and has passed on the chain INVALID - Signature validation has been attempted and has failed on chain

Function Documentation

wickr_identity_chain_copy()

wickr_identity_chain_t* wickr_identity_chain_copy

(

const wickr_identity_chain_t *

source

)

Copy an identity chain

Parameters

source

the identity chain to copy

Returns

a newly allocated identity chain holding a deep copy of the properties of 'source'

wickr_identity_chain_create()

wickr_identity_chain_t* wickr_identity_chain_create	(	wickr_identity_t *	root,
		wickr_identity_t *	node
	)

Create an identity chain from components

Parameters

root	see 'wickr_identity_chain' property documentation
node	see 'wickr_identity_chain' property documentation

Returns

a newly allocated identity chain that takes ownership of the passed inputs

wickr_identity_chain_destroy()

void wickr_identity_chain_destroy

(

wickr_identity_chain_t **

chain

)

Destroy an identity chain

Parameters

chain

a pointer to the identity chain to destroy. All properties of '*chain' will also be destroyed

wickr_identity_chain_validate()

bool wickr_identity_chain_validate	(	wickr_identity_chain_t *	chain,
		const wickr_crypto_engine_t *	engine
	)

Verify the validity of an identity chain

Parameters

chain	the chain to validate
engine	a crypto engine that supports verifying signatures

Returns

true if the 'signature' of the 'node' property of 'chain' can be properly verified with the public 'sig_key' from the 'root' property of 'chain'

wickr_identity_copy()

wickr_identity_t* wickr_identity_copy

(

const wickr_identity_t *

source

)

Copy an identity

Parameters

source

the identity to copy

Returns

a newly allocated identity holding a deep copy of the properties of 'source'

wickr_identity_create()

wickr_identity_t* wickr_identity_create	(	wickr_identity_type	type,
		wickr_buffer_t *	identifier,
		wickr_ec_key_t *	sig_key,
		wickr_ecdsa_result_t *	signature
	)

Create an identity from components

Parameters

type	see 'wickr_identity' property documentation
identifier	see 'wickr_identity' property documentation
sig_key	see 'wickr_identity' property documentation
signature	see 'wickr_identity' property documentation

Returns

a newly allocated identity that takes ownership of the passed inputs

wickr_identity_create_from_buffer()

wickr_identity_t* wickr_identity_create_from_buffer	(	const wickr_buffer_t *	buffer,
		const wickr_crypto_engine_t *	engine
	)

Create an identity from a buffer that was created with 'wickr_identity_serialize'

Parameters

buffer	the buffer that contains a serialized representation of an identity
engine	the crypto engine to use to import the key components of the identity

Returns

deserialized identity or null if the deserialization fails

wickr_identity_destroy()

void wickr_identity_destroy

(

wickr_identity_t **

identity

)

Destroy an identity

Parameters

identity

a pointer to the identity to destroy. All properties of '*identity' will also be destroyed

wickr_identity_get_bilateral_fingerprint()

wickr_fingerprint_t* wickr_identity_get_bilateral_fingerprint	(	const wickr_identity_t *	identity,
		const wickr_identity_t *	remote_identity,
		wickr_crypto_engine_t	engine
	)

A fingerprint that is unique between identity and remote_identity

Parameters

identity	the identity to get a bilateral fingerprint of
remote_identity	the other party included in the fingerprint
engine	engine the crypto engine to use for underlying hash operations

Returns

a bilateral fingerprint of (identity,remote_identity) or (remote_identity,identity) calculated using SHA512(fingerprint(identity) || fingerprint(remote_identity)).

wickr_identity_get_fingerprint()

wickr_fingerprint_t* wickr_identity_get_fingerprint	(	const wickr_identity_t *	identity,
		wickr_crypto_engine_t	engine
	)

A unique fingerprint representing the identifier and public signing key of this identity. See 'fingerprint.h'

Parameters

identity	the identity to get a unique fingerprint of
engine	the crypto engine to use for underlying hash operations

Returns

a unique fingerprint currently calculated as SHA512(identifier || sig_pub->pub_data)

wickr_identity_serialize()

wickr_buffer_t* wickr_identity_serialize

(

const wickr_identity_t *

identity

)

Serialize an identity to bytes

Parameters

identity

the identity to serialize

Returns

a buffer containing a serialized representation of 'identity' or null if serialization fails

wickr_identity_sign()

wickr_ecdsa_result_t* wickr_identity_sign	(	const wickr_identity_t *	identity,
		const wickr_crypto_engine_t *	engine,
		const wickr_buffer_t *	data
	)

Sign provided data using an identity signing key

Parameters

identity	the identity to use for signing
engine	a crypto engine supporting signatures using the identity's signing key
data	buffer to sign

Returns

an ECDSA result containing a signature of 'data' using the 'sig_key' property of 'identity'. NULL if the provided identity does not contain a private signing key

wickr_node_identity_gen()

wickr_identity_t* wickr_node_identity_gen	(	const wickr_crypto_engine_t *	engine,
		const wickr_identity_t *	root_identity,
		const wickr_buffer_t *	identifier
	)

Generate a new random node identity, given a root identity

Parameters

engine	a crypto engine supporting random Elliptic Curve Key generation
root_identity	a root identity that supports generating signatures with a private signing key
identifier	to use for new node identity, if NULL a random identifier of IDENTIFIER_LEN bytes will be used

Returns

a newly allocated node identity signing by root identity 'root_identity'. The 'identifier' property of the node is generated at random to be 'IDENTIFIER_LEN' in length (currently 32 bytes). NULL if root_identity is not a root, or it does not contain a private signing key