wickr-crypto-c
Data Structures | Macros | Enumerations | Functions
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_twickr_identity_create (wickr_identity_type type, wickr_buffer_t *identifier, wickr_ec_key_t *sig_key, wickr_ecdsa_result_t *signature)
 
wickr_ecdsa_result_twickr_identity_sign (const wickr_identity_t *identity, const wickr_crypto_engine_t *engine, const wickr_buffer_t *data)
 
wickr_identity_twickr_node_identity_gen (const wickr_crypto_engine_t *engine, const wickr_identity_t *root_identity, const wickr_buffer_t *identifier)
 
wickr_identity_twickr_identity_copy (const wickr_identity_t *source)
 
void wickr_identity_destroy (wickr_identity_t **identity)
 
wickr_buffer_twickr_identity_serialize (const wickr_identity_t *identity)
 
wickr_identity_twickr_identity_create_from_buffer (const wickr_buffer_t *buffer, const wickr_crypto_engine_t *engine)
 
wickr_fingerprint_twickr_identity_get_fingerprint (const wickr_identity_t *identity, wickr_crypto_engine_t engine)
 
wickr_fingerprint_twickr_identity_get_bilateral_fingerprint (const wickr_identity_t *identity, const wickr_identity_t *remote_identity, wickr_crypto_engine_t engine)
 
wickr_identity_chain_twickr_identity_chain_create (wickr_identity_t *root, wickr_identity_t *node)
 
wickr_identity_chain_twickr_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

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
sourcethe 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
rootsee 'wickr_identity_chain' property documentation
nodesee '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
chaina 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
chainthe chain to validate
enginea 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
sourcethe 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
typesee 'wickr_identity' property documentation
identifiersee 'wickr_identity' property documentation
sig_keysee 'wickr_identity' property documentation
signaturesee '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
bufferthe buffer that contains a serialized representation of an identity
enginethe 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
identitya 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
identitythe identity to get a bilateral fingerprint of
remote_identitythe other party included in the fingerprint
engineengine 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
identitythe identity to get a unique fingerprint of
enginethe 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
identitythe 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
identitythe identity to use for signing
enginea crypto engine supporting signatures using the identity's signing key
databuffer 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
enginea crypto engine supporting random Elliptic Curve Key generation
root_identitya root identity that supports generating signatures with a private signing key
identifierto 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