---

key.h File Reference

Key knowledge base management. More...

#include "gale/misc.h"
#include "oop.h"

Typedefs
typedef void*	gale_key_call (oop_source *oop,struct gale_key *key,void *user)
	Callback for gale_key_search() and gale_key_generate(). More...
typedef void	gale_key_hook ( struct gale_time now,oop_source *oop, struct gale_key *key,int do_private, struct gale_key_request *handle, void *user,void **cache)
	Callback for key search strategy drivers. More...
Enumerations
enum	{   search_private = 1,   search_slow = 2,   search_all = 3,   search_harder = 4 }
Functions
struct gale_key*	gale_key_handle (struct gale_text name)
	Get a key handle. More...
struct gale_key*	gale_key_parent (struct gale_key *)
	Get a key's parent. More...
struct gale_text	gale_key_name (struct gale_key *)
	Get a key's name. More...
const struct gale_key_assertion*	gale_key_private (struct gale_key *)
	Report the assertion currently active for a particular private key, if any. More...
const struct gale_key_assertion*	gale_key_public ( struct gale_key *, struct gale_time)
	Report the assertion currently active for a particular public key, if any. More...
struct gale_key_assertion*	gale_key_assert ( struct gale_data,struct gale_text,struct gale_time,int trust)
	Supply some raw key data to the system. More...
struct gale_key_assertion*	gale_key_assert_group ( struct gale_group,struct gale_text,struct gale_time,int trust)
	Supply some slightly cooked key data. More...
void	gale_key_retract (struct gale_key_assertion *,int trust)
	Retract a previous assertion. More...
int	gale_key_trusted (const struct gale_key_assertion *)
	Is an assertion implicitly trusted? More...
struct gale_key*	gale_key_owner (const struct gale_key_assertion *)
	What is the key associated with an assertion? More...
const struct gale_key_assertion*	gale_key_signed ( const struct gale_key_assertion *)
	Is a public key signed? More...
struct gale_group	gale_key_data (const struct gale_key_assertion *)
	Get a key's data. More...
struct gale_data	gale_key_raw (const struct gale_key_assertion *)
	Get the original, raw data associated with a key. More...
struct gale_text	gale_key_from (const struct gale_key_assertion *)
	Get text describing where a key came from. More...
struct gale_time	gale_key_time (const struct gale_key_assertion *)
	Get the most recent timestamp given for a key. More...
void	gale_key_search (oop_source *source, struct gale_key *,int flags, gale_key_call *,void *user)
	Search for key data. More...
void	gale_key_generate (oop_source *source, struct gale_key *,struct gale_group, gale_key_call *,void *user)
	Generate a new key. More...
void	gale_key_add_hook (gale_key_hook *,void *user)
	Add a search strategy hook that will be called when looking for keys. More...
void	gale_key_hook_done (oop_source *, struct gale_key *,struct gale_key_request *)
	Notify the system that search is complete. More...

---

Detailed Description

Key knowledge base management.

---

Typedef Documentation

typedef void* gale_key_call(oop_source *oop,struct gale_key *key,void *user)

Callback for gale_key_search() and gale_key_generate(). Parameters: key   Key handle for which search was initiated. user   User-specified opaque pointer. Returns: Liboop continuation code (usually OOP_CONTINUE).

typedef void gale_key_hook( struct gale_time now,oop_source *oop, struct gale_key *key,int do_private, struct gale_key_request *handle, void *user,void **cache)

Callback for key search strategy drivers. Parameters: now   The current time (to avoid redundant calls to gale_time_now()). oop   Liboop event source to use. key   Key handle for which search was initiated. do_private   Zero if we're only interested in public key data. handle   Request handle for use with gale_key_hook_done(). user   User-specified opaque pointer. Warning: Make sure to call gale_key_hook_done() when the callback is finished with its search. See also: gale_key_add_hook(), gale_key_hook_done().

---

Function Documentation

void gale_key_add_hook ( gale_key_hook * hook, void * user )

Add a search strategy hook that will be called when looking for keys. The hook function should call gale_key_hook_done() when it is finished processing. Parameters: hook   Callback to invoke whenever the system is looking for a key. user   User-specified opaque pointer to pass to the callback.

struct gale_key_assertion * gale_key_assert ( struct gale_data, struct gale_text, struct gale_time, int trust )

Supply some raw key data to the system. Parameters: source   Raw key bits. from   Text describing where the key came from. is_trusted   Nonzero iff the key comes from a trusted source and doesn't require external validation. Returns: Assertion handle. See also: gale_key_assert_group(), gale_key_retract()

struct gale_key_assertion * gale_key_assert_group ( struct gale_group, struct gale_text, struct gale_time, int trust )

Supply some slightly cooked key data. Parameters: source   Key data. from   Text describing where the key came from. is_trusted   Nonzero iff the key comes from a trusted source and doesn't require external validation. Returns: Assertion handle. See also: gale_key_assert(), gale_key_retract()

struct gale_group gale_key_data ( const struct gale_key_assertion * assert )

Get a key's data. Parameters: assert   Assertion handle from gale_key_public() or gale_key_private().

struct gale_text gale_key_from ( const struct gale_key_assertion * assert )

Get text describing where a key came from. Parameters: assert   Assertion handle from gale_key_public() or gale_key_private().

void gale_key_generate ( oop_source * source, struct gale_key * key, struct gale_group, gale_key_call * call, void * user )

Generate a new key. Parameters: source   Liboop event source to use. key   Key handle from gale_key_handle(). data   Key data to use, usually from gale_crypto_generate(). call   Callback to invoke when generation is complete. user   User-specified opaque pointer to pass to the callback.

struct gale_key * gale_key_handle ( struct gale_text name )

Get a key handle. Parameters: name   Name of the key. Returns: Key handle.

void gale_key_hook_done ( oop_source * source, struct gale_key * key, struct gale_key_request * handle )

Notify the system that search is complete. Called from a gale_key_hook function when the callback is done. Parameters: source   Liboop event source to use. key   Key handle, as passed to gale_key_hook. handle   Request handle, as passed to gale_key_hook.

struct gale_text gale_key_name ( struct gale_key * key )

Get a key's name. Parameters: key   Handle from gale_key_handle() or gale_key_parent(). Returns: Key's name, as passed to gale_key_handle().

struct gale_key * gale_key_owner ( const struct gale_key_assertion * assert )

What is the key associated with an assertion? Parameters: assert   Assertion handle from gale_key_assert(). Returns: The key associated with the assertion, or NULL if none.

struct gale_key * gale_key_parent ( struct gale_key * key )

Get a key's parent. Parameters: key   Handle from gale_key_handle(). Returns: Handle of the key's parent, or NULL if the key is ROOT.

const struct gale_key_assertion * gale_key_private ( struct gale_key * key )

Report the assertion currently active for a particular private key, if any. Parameters: key   The key handle from gale_key_handle(). Returns: The valid assertion handle, or NULL if none exist. Warning: Active assertions for a particular key may change as time passes and new data is integrated. You should generally keep around only gale_key references, not gale_key_assertion references. See also: gale_key_assert(), gale_key_public()

const struct gale_key_assertion * gale_key_public ( struct gale_key * key, struct gale_time )

Report the assertion currently active for a particular public key, if any. Parameters: key   The key handle from gale_key_handle(). time   The time to use for time-dependent validity checks. Usually gale_time_now(). Returns: The valid assertion handle, or NULL if none exist. Warning: Active assertions for a particular key may change as time passes, keys expire and new data is integrated. You should generally keep around only gale_key references, not gale_key_assertion references. See also: gale_key_assert(), gale_key_private()

struct gale_data gale_key_raw ( const struct gale_key_assertion * assert )

Get the original, raw data associated with a key. Parameters: assert   Assertion handle from gale_key_public() or gale_key_private().

void gale_key_retract ( struct gale_key_assertion * ass, int is_trusted )

Retract a previous assertion. Parameters: assert   Assertion handle from gale_key_assert(). is_trusted   The same value passed to gale_key_assert(). See also: gale_key_assert()

void gale_key_search ( oop_source * source, struct gale_key * key, int flags, gale_key_call * call, void * user )

Search for key data. Parameters: source   Liboop event source to use. key   Key handle from gale_key_handle(). flags   Control flags, normally search_all. call   Callback to invoke when the search is complete. user   User-specified opaque pointer to pass to the callback.

const struct gale_key_assertion * gale_key_signed ( const struct gale_key_assertion * assert )

Is a public key signed? Parameters: assert   Assertion handle from gale_key_public(). Returns: The assertion which signed this one, or NULL if none.

struct gale_time gale_key_time ( const struct gale_key_assertion * assert )

Get the most recent timestamp given for a key. Parameters: assert   Assertion handle from gale_key_public() or gale_key_private().

int gale_key_trusted ( const struct gale_key_assertion * assert )

Is an assertion implicitly trusted? Parameters: assert   Assertion handle from gale_key_public(). Returns: Nonzero iff the assertion was entered with is_trusted == 1.

---