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_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