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


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