Avis Client Library: avis/keys.h File Reference

# avis/keys.h File Reference

## Detailed Description

Secure messaging keys.

`#include <string.h>`
`#include <avis/defs.h>`
`#include <avis/stdtypes.h>`
`#include <avis/arrays.h>`

Go to the source code of this file.

## Data Structures
struct | Key
| A key value used to secure notifications. More...
struct | Keys
| A key collection used to secure notifications. More...
## Defines
#define | EMPTY_KEYS (&_empty_keys)
| A pointer to an immutable empty Keys collection.
#define | KEY_SCHEME_SHA1_DUAL (&_KEY_SCHEME_SHA1_DUAL)
| The SHA-1 dual key scheme.
#define | KEY_SCHEME_SHA1_PRODUCER (&_KEY_SCHEME_SHA1_PRODUCER)
| The SHA-1 producer key scheme.
#define | KEY_SCHEME_SHA1_CONSUMER (&_KEY_SCHEME_SHA1_CONSUMER)
| The SHA-1 consumer key scheme.
#define | elvin_keys_create() (elvin_keys_init ((Keys *)avis_emalloc (sizeof (Keys))))
| Create an empty keys collection.
#define | elvin_keys_destroy(keys)
| Macro to destroy and NULL a keys collection.
#define | elvin_key_copy(key) (elvin_key_create_from_data ((key).data, (key).length))
| Copy a key.
## Typedefs
typedef struct KeyScheme_t * | KeyScheme
| Defines an Elvin security scheme.
## Functions
AVIS_PUBLIC Keys * | elvin_keys_init (Keys *keys)
| Initialise a keys collection to empty.
AVIS_PUBLIC Keys * | elvin_keys_copy (Keys *keys)
| Copy a key collection.
AVIS_PUBLIC void | elvin_keys_free (Keys *keys)
| Free any resources held by key collection.
AVIS_PUBLIC bool | elvin_keys_equal (Keys *keys1, Keys *keys2)
| Test if two key collections are logically equal.
AVIS_PUBLIC bool | elvin_keys_add (Keys *keys, KeyScheme scheme, Key key)
| Add a key to the collection in a given security scheme.
AVIS_PUBLIC bool | elvin_keys_add_dual_consumer (Keys *keys, KeyScheme scheme, Key key)
| Add a key to the collection as a consumer key in a given dual key security scheme.
AVIS_PUBLIC bool | elvin_keys_add_dual_producer (Keys *keys, KeyScheme scheme, Key key)
| Add a key to the collection as a producer key in a given dual key security scheme.
AVIS_PUBLIC void | elvin_key_free (Key key)
| Free the data block associated with a key.
AVIS_PUBLIC Key | elvin_key_create_from_string (const char *str)
| Create a key from a character string.
AVIS_PUBLIC Key | elvin_key_create_from_data (const uint8_t *data, size_t length)
| Create a key from a block of data.
AVIS_PUBLIC Key | elvin_key_create_public (Key private_key, KeyScheme scheme)
| Create a public key from a private key using a given scheme's hash.
AVIS_PUBLIC bool | elvin_key_equal (Key key1, Key key2)
| Test if two keys are equal.
## Variables
AVIS_PUBLIC_DATA struct KeyScheme_t | _KEY_SCHEME_SHA1_DUAL
AVIS_PUBLIC_DATA struct KeyScheme_t | _KEY_SCHEME_SHA1_PRODUCER
AVIS_PUBLIC_DATA struct KeyScheme_t | _KEY_SCHEME_SHA1_CONSUMER
AVIS_PUBLIC_DATA Keys | _empty_keys

## Define Documentation

#define elvin_key_copy | ( | key |  | ) | (elvin_key_create_from_data ((key).data, (key).length))

Copy a key.

See also:
  elvin_key_create_from_data()

#define elvin_keys_create | ( |  | ) | (elvin_keys_init ((Keys *)avis_emalloc (sizeof (Keys))))

Create an empty keys collection.

See also:
  elvin_keys_free()

  elvin_keys_destroy()

#define elvin_keys_destroy | ( | keys |  | ) |

Value:

    if ((keys) != EMPTY_KEYS && (keys) != NULL) \
      {\
        elvin_keys_free (keys); free (keys); \
      }\
      keys = NULL;\

Macro to destroy and NULL a keys collection.

Handles NULL and EMPTY_KEYS values.

See also:
  elvin_keys_free()

#define EMPTY_KEYS (&_empty_keys)

A pointer to an immutable empty Keys collection.

#define KEY_SCHEME_SHA1_CONSUMER (&_KEY_SCHEME_SHA1_CONSUMER)

The SHA-1 consumer key scheme.

See also:
  KeyScheme

#define KEY_SCHEME_SHA1_DUAL (&_KEY_SCHEME_SHA1_DUAL)

The SHA-1 dual key scheme.

See also:
  KeyScheme

#define KEY_SCHEME_SHA1_PRODUCER (&_KEY_SCHEME_SHA1_PRODUCER)

The SHA-1 producer key scheme.

See also:
  KeyScheme

## Typedef Documentation

typedef struct KeyScheme_t* KeyScheme

Defines an Elvin security scheme.

A key scheme defines a mode of sending or receiving notifications securely.

### The Producer Scheme

In the producer scheme, consumers of notifications ensure that a notification producer is known to them. The producer uses the private key, and consumers use the public key. If the producer keeps its private key secure, consumers can be assured they are receiving notifications from a trusted producer.

### The Consumer Scheme

In the consumer scheme, producers of notifications ensure that a notification consumer is known to them, i.e. the producer controls who can receive its notifications. In this scheme -- the reverse of the producer scheme -- the consumer uses the private key, and producers use the public key. If the consumer keeps its private key secure, then the producer can be assured that only the trusted consumer can receive its notifications.

### The Dual Scheme

The dual scheme combines both the producer and consumer schemes, so that both ends can send and receive securely. Typically both ends exchange public keys, and each end then emits notifications with both its private key and the public key(s) of its intended consumer(s) attached. Similarly, each end would subscribe using its private key and the public key(s) of its intended producer(s).

### Supported Schemes

Avis currently supports just the SHA-1 secure hash as defined in version 4.0 of the Elvin protocol. As such, three schemes are available: KEY_SCHEME_SHA1_DUAL, KEY_SCHEME_SHA1_CONSUMER and KEY_SCHEME_SHA1_PRODUCER.

## Function Documentation

AVIS_PUBLIC Key elvin_key_create_from_data | ( | const uint8_t * | data,
|  | size_t | length |
| ) |  |  |

Create a key from a block of data.

Parameters:

  | data | The data block.
  | length | The length of the data block.

See also:
  elvin_key_create_from_string()

  elvin_key_create_public()

  elvin_key_free()

AVIS_PUBLIC Key elvin_key_create_from_string | ( | const char * | str | ) |

Create a key from a character string.

Parameters:

  | str | The string to use as the data block.

See also:
  elvin_key_create_from_data()

  elvin_key_free()

AVIS_PUBLIC Key elvin_key_create_public | ( | Key | private_key,
|  | KeyScheme | scheme |
| ) |  |  |

Create a public key from a private key using a given scheme's hash.

Parameters:

  | private_key | The private key block.
  | scheme | The security scheme to use.

Returns:
  The public key. public_key.data = hash (private_key.data)

See also:
  elvin_key_create_from_data()

  elvin_key_free()

AVIS_PUBLIC bool elvin_key_equal | ( | Key | key1,
|  | Key | key2 |
| ) |  |  |

Test if two keys are equal.

AVIS_PUBLIC void elvin_key_free | ( | Key | key | ) |

Free the data block associated with a key.

See also:
  elvin_key_create_from_string()

  elvin_key_create_from_data()

AVIS_PUBLIC bool elvin_keys_add | ( | Keys * | keys,
|  | KeyScheme | scheme,
|  | Key | key |
| ) |  |  |

Add a key to the collection in a given security scheme.

Parameters:

  | keys | The keys to add to.
  | scheme | the security scheme to associate the key with.
  | key | The key to add. The key becomes owned by the collection and will be freed when the collection is.

Returns:
  True if the key was added, false if the collection was not modified (the key was already in the collection).

See also:
  elvin_keys_add_dual_consumer()

  elvin_keys_add_dual_producer()

AVIS_PUBLIC bool elvin_keys_add_dual_consumer | ( | Keys * | keys,
|  | KeyScheme | scheme,
|  | Key | key |
| ) |  |  |

Add a key to the collection as a consumer key in a given dual key security scheme.

Parameters:

  | keys | The keys to add to.
  | scheme | the security scheme to associate the key with. This must be a dual scheme (e.g. KEY_SCHEME_SHA1_DUAL).
  | key | The key to add. The key becomes owned by the collection and will be freed when the collection is.

Returns:
  True if the key was added, false if the collection was not modified (the key was already in the collection, or the scheme is not a dual key scheme).

See also:
  elvin_keys_add()

  elvin_keys_add_dual_producer()

AVIS_PUBLIC bool elvin_keys_add_dual_producer | ( | Keys * | keys,
|  | KeyScheme | scheme,
|  | Key | key |
| ) |  |  |

Add a key to the collection as a producer key in a given dual key security scheme.

Parameters:

  | keys | The keys to add to.
  | scheme | the security scheme to associate the key with. This must be a dual scheme (e.g. KEY_SCHEME_SHA1_DUAL).
  | key | The key to add. The key becomes owned by the collection and will be freed when the collection is.

Returns:
  True if the key was added, false if the collection was not modified (the key was already in the collection, or the scheme is not a dual key scheme).

See also:
  elvin_keys_add()

  elvin_keys_add_dual_consumer()

AVIS_PUBLIC Keys* elvin_keys_copy | ( | Keys * | keys | ) |

Copy a key collection.

Parameters:

  | keys | The keys to copy.

Returns:
  An independent copy of the source key collection.

See also:
  elvin_keys_free()

  elvin_key_copy()

AVIS_PUBLIC bool elvin_keys_equal | ( | Keys * | keys1,
|  | Keys * | keys2 |
| ) |  |  |

Test if two key collections are logically equal.

AVIS_PUBLIC void elvin_keys_free | ( | Keys * | keys | ) |

Free any resources held by key collection.

This includes any key data blocks referenced.

See also:
  Keys

  elvin_keys_init()

AVIS_PUBLIC Keys* elvin_keys_init | ( | Keys * | keys | ) |

Initialise a keys collection to empty.

See also:
  elvin_keys_create()

## Variable Documentation

AVIS_PUBLIC_DATA Keys _empty_keys

AVIS_PUBLIC_DATA struct KeyScheme_t _KEY_SCHEME_SHA1_CONSUMER

AVIS_PUBLIC_DATA struct KeyScheme_t _KEY_SCHEME_SHA1_DUAL

AVIS_PUBLIC_DATA struct KeyScheme_t _KEY_SCHEME_SHA1_PRODUCER