gnunet_pils_service.h File Reference

#include "gnunet_util_lib.h"
#include "gnunet_hello_uri_lib.h"

Include dependency graph for gnunet_pils_service.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	GNUNET_PILS_SignResultCallback) (void *cls, const struct GNUNET_PeerIdentity *pid, const struct GNUNET_CRYPTO_EddsaSignature *sig)
	A handler/callback to be called for signatures. More...
typedef void(*	GNUNET_PILS_SignAddrResultCallback) (void *cls, void *result, size_t result_size)
	A handler/callback to be called for signatures on addresses. More...
typedef void(*	GNUNET_PILS_DecapsResultCallback) (void *cls, const struct GNUNET_ShortHashCode *key)
	A handler/callback to be called for decaps. More...
typedef void(*	GNUNET_PILS_PidChangeCallback) (void *cls, const struct GNUNET_HELLO_Parser *parser, const struct GNUNET_HashCode *hash)
	A handler/callback to be called on the change of the peer id. More...

Functions
struct GNUNET_PILS_Handle *	GNUNET_PILS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, GNUNET_PILS_PidChangeCallback pid_change_cb, void *cls)
	Connect to the PILS service. More...
void	GNUNET_PILS_disconnect (struct GNUNET_PILS_Handle *handle)
	Disconnect from the PILS service. More...
struct GNUNET_PILS_Operation *	GNUNET_PILS_sign_by_peer_identity (struct GNUNET_PILS_Handle *handle, const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose, GNUNET_PILS_SignResultCallback cb, void *cb_cls)
	Sign data with the peer id. More...
struct GNUNET_PILS_Operation *	GNUNET_PILS_kem_decaps (struct GNUNET_PILS_Handle *handle, const struct GNUNET_CRYPTO_HpkeEncapsulation *c, GNUNET_PILS_DecapsResultCallback cb, void *cb_cls)
	Decaps an encapsulated key with our private key. More...
void	GNUNET_PILS_feed_addresses (struct GNUNET_PILS_Handle *handle, const struct GNUNET_HELLO_Builder *addresses_builder)
	Feed a set of addresses to pils so that it will generate a new peer id based on the given set of addresses. More...
void	GNUNET_HELLO_builder_hash_addresses (const struct GNUNET_HELLO_Builder *builder, struct GNUNET_HashCode *address_hash)
	Hash address in buidler. More...
void	GNUNET_PILS_derive_pid (size_t seed_key_bytes, const uint8_t seed_key[seed_key_bytes], const struct GNUNET_HashCode *addrs_hash, struct GNUNET_CRYPTO_EddsaPrivateKey *outkey)
	Generate the peer id from the addresses hash and the initial secret key. More...
struct GNUNET_PILS_Operation *	GNUNET_PILS_sign_hello (struct GNUNET_PILS_Handle *handle, const struct GNUNET_HELLO_Builder *builder, struct GNUNET_TIME_Absolute et, GNUNET_PILS_SignResultCallback cb, void *cb_cls)
	Create HELLO signature. More...
void	GNUNET_PILS_cancel (struct GNUNET_PILS_Operation *op)
	Cancel request. More...

Detailed Description

Author

ch3

Peer Identity Lifecycle Service; the API for managing Peer Identities

This api gives access to the PILS service.

The service maintains the peer identity. On address change it generates a new identity and informs subscribed components. It also signs data with the identity on request.

Note: Currently the signatures are actually made in the api. TODO is it fine this way?

Definition in file gnunet_pils_service.h.

Typedef Documentation

GNUNET_PILS_SignResultCallback

typedef void(* GNUNET_PILS_SignResultCallback) (void *cls, const struct GNUNET_PeerIdentity *pid, const struct GNUNET_CRYPTO_EddsaSignature *sig)

A handler/callback to be called for signatures.

The peer identity may have been changed by PILS in the meantime, so the identity that was used to sign is returned here.

Parameters

cls	The closure given to #GNUNET_PILS_sign
pid	the peer identity that produced the signature
sig	the signature, NULL on error

Definition at line 62 of file gnunet_pils_service.h.

GNUNET_PILS_SignAddrResultCallback

typedef void(* GNUNET_PILS_SignAddrResultCallback) (void *cls, void *result, size_t result_size)

A handler/callback to be called for signatures on addresses.

Parameters

cls	The closure given to #GNUNET_PILS_sign
result	allocated address record
result_size	size of result

Definition at line 74 of file gnunet_pils_service.h.

GNUNET_PILS_DecapsResultCallback

typedef void(* GNUNET_PILS_DecapsResultCallback) (void *cls, const struct GNUNET_ShortHashCode *key)

A handler/callback to be called for decaps.

Parameters

cls	The closure given to GNUNET_PILS_kem_decaps
key	The decapsulated key

Definition at line 85 of file gnunet_pils_service.h.

GNUNET_PILS_PidChangeCallback

typedef void(* GNUNET_PILS_PidChangeCallback) (void *cls, const struct GNUNET_HELLO_Parser *parser, const struct GNUNET_HashCode *hash)

A handler/callback to be called on the change of the peer id.

Parameters

cls	The closure given to GNUNET_PILS_connect
parser	a parsed HELLO block that represents the new PID
hash	The hash of addresses the peer id is based on. This hash is also returned by #GNUNET_PILS_feed_address.

Definition at line 97 of file gnunet_pils_service.h.

Function Documentation

GNUNET_PILS_connect()

struct GNUNET_PILS_Handle * GNUNET_PILS_connect	(	const struct GNUNET_CONFIGURATION_Handle *	cfg,
		GNUNET_PILS_PidChangeCallback	pid_change_cb,
		void *	cls
	)

Connect to the PILS service.

Parameters

cfg	configuration to use
pid_change_cb	handler/callback called once the peer id changes
cls	closure for pid_change_cb

Returns

Handle to the PILS service

Definition at line 367 of file pils_api.c.

{
  struct GNUNET_PILS_Handle *h;
 
  h = GNUNET_new (struct GNUNET_PILS_Handle);
  h->cfg = cfg;
  h->pid_change_cb = pid_change_cb;
  h->pid_change_cb_cls = cls;
  h->reconnect_delay = GNUNET_TIME_UNIT_ZERO;
  reconnect (h);
  return h;
}

References cfg, GNUNET_ARM_Handle::cfg, GNUNET_new, GNUNET_TIME_UNIT_ZERO, h, pid_change_cb(), and reconnect().

Referenced by GCH_init(), GSC_KX_init(), and run().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_disconnect()

void GNUNET_PILS_disconnect

(

struct GNUNET_PILS_Handle *

handle

)

Disconnect from the PILS service.

Parameters

handle

handle to the PILS service (was returned by GNUNET_PILS_connect)

Definition at line 390 of file pils_api.c.

{
  struct GNUNET_PILS_Operation *op;
 
  GNUNET_assert (NULL != handle);
  LOG (GNUNET_ERROR_TYPE_DEBUG,
       "Disonnecting from peer identity lifecycle service.\n");
  if (NULL != handle->reconnect_task)
  {
    GNUNET_SCHEDULER_cancel (handle->reconnect_task);
    handle->reconnect_task = NULL;
  }
  if (NULL != handle->mq)
  {
    GNUNET_MQ_destroy (handle->mq);
    handle->mq = NULL;
  }
  LOG (GNUNET_ERROR_TYPE_DEBUG, "Cleaning up\n");
  while (NULL != (op = handle->op_head))
  {
    GNUNET_CONTAINER_DLL_remove (handle->op_head, handle->op_tail, op);
    GNUNET_free (op);
  }
  GNUNET_free (handle);
}

References GNUNET_assert, GNUNET_CONTAINER_DLL_remove, GNUNET_ERROR_TYPE_DEBUG, GNUNET_free, GNUNET_MQ_destroy(), GNUNET_SCHEDULER_cancel(), handle, LOG, GNUNET_VPN_Handle::mq, and op.

Referenced by cleaning_task(), do_shutdown(), GCH_shutdown(), GSC_KX_done(), and shutdown_task().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_sign_by_peer_identity()

struct GNUNET_PILS_Operation * GNUNET_PILS_sign_by_peer_identity	(	struct GNUNET_PILS_Handle *	handle,
		const struct GNUNET_CRYPTO_EccSignaturePurpose *	purpose,
		GNUNET_PILS_SignResultCallback	cb,
		void *	cb_cls
	)

Sign data with the peer id.

TODO not sure whether this was the intended design from last meeting - this is currently following the design of GNUNET_CRYPTO_sign_by_peer_identity

In particular we currently transfer the secret key from the service to the api so we can sign in-place and have no ipc-overhead. Is this fine?

Parameters

handle	handle to the PILS service
purpose	what to sign (size, purpose and data) TODO improve wording - look at GNUNET_CRYPTO_eddsa_sign
cb	signature result callback
cb_cls	closure for the cb

Returns

handle to the operation, NULL on error

Parameters

handle	handle to the PILS service
purpose	what to sign (size, purpose and data)
cb	callback to call once the signature is ready
cb_cls	closure to cb

Returns

handle to the operation, NULL on error

Definition at line 428 of file pils_api.c.

{
  struct GNUNET_PILS_Operation *op;
  struct SignRequestMessage *msg;
 
  op = GNUNET_new (struct GNUNET_PILS_Operation);
  op->env = GNUNET_MQ_msg_extra (msg,
                                 ntohl (purpose->size),
                                 GNUNET_MESSAGE_TYPE_PILS_SIGN_REQUEST);
  op->h = handle;
  op->sign_cb = cb;
  op->sign_cb_cls = cb_cls;
  msg->rid = htonl (handle->op_id_counter++);
  op->op_id = ntohl (msg->rid);
  memcpy (&msg[1], purpose, ntohl (purpose->size));
  GNUNET_CONTAINER_DLL_insert (handle->op_head,
                               handle->op_tail,
                               op);
  // FIXME resend?
  GNUNET_MQ_send (handle->mq, op->env);
  op->env = NULL;
  return op;
}

References GNUNET_PILS_Operation::env, GNUNET_CONTAINER_DLL_insert, GNUNET_MESSAGE_TYPE_PILS_SIGN_REQUEST, GNUNET_MQ_msg_extra, GNUNET_MQ_send(), GNUNET_new, GNUNET_PILS_Operation::h, handle, GNUNET_VPN_Handle::mq, msg, op, GNUNET_PILS_Operation::op_id, GNUNET_PILS_Operation::sign_cb, GNUNET_PILS_Operation::sign_cb_cls, and GNUNET_CRYPTO_EccSignaturePurpose::size.

Referenced by forward_dv_learn(), GNUNET_PILS_sign_hello(), handle_validation_challenge(), pils_sign_address(), sign_ephemeral(), start_dv_learn(), and transmit_task_cb().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_kem_decaps()

struct GNUNET_PILS_Operation * GNUNET_PILS_kem_decaps	(	struct GNUNET_PILS_Handle *	handle,
		const struct GNUNET_CRYPTO_HpkeEncapsulation *	c,
		GNUNET_PILS_DecapsResultCallback	cb,
		void *	cb_cls
	)

Decaps an encapsulated key with our private key.

TODO whether it's fine to use the private key in this way needs to be discussed. If not, another key (which has been signed with this id) needs to be used for en-/decapsulating.

Parameters

handle	handle to the PILS service
c	the encapsulated key
cb	the callback to call with the decapsulated key
cb_cls	callback closure

Returns

handle to the operation, NULL on error

Parameters

handle	handle to the PILS service
c	the encapsulated key
prk	where to write the key material HKDF-Extract(c||aX)=HKDF-Extract(c||x(aG))

Returns

handle to the operation, NULL on error

Definition at line 468 of file pils_api.c.

{
  struct GNUNET_PILS_Operation *op;
  struct DecapsMessage *msg;
 
  op = GNUNET_new (struct GNUNET_PILS_Operation);
  op->env = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_PILS_KEM_DECAPS);
  msg->c = *c;
  op->h = handle;
  op->decaps_cb = cb;
  op->decaps_cb_cls = cb_cls;
  msg->rid = htonl (handle->op_id_counter++);
  op->op_id = ntohl (msg->rid);
  GNUNET_CONTAINER_DLL_insert (handle->op_head,
                               handle->op_tail,
                               op);
  // FIXME resend?
  GNUNET_MQ_send (handle->mq, op->env);
  op->env = NULL;
  return op;
}

References DecapsMessage::c, GNUNET_PILS_Operation::decaps_cb, GNUNET_PILS_Operation::decaps_cb_cls, GNUNET_PILS_Operation::env, GNUNET_CONTAINER_DLL_insert, GNUNET_MESSAGE_TYPE_PILS_KEM_DECAPS, GNUNET_MQ_msg, GNUNET_MQ_send(), GNUNET_new, GNUNET_PILS_Operation::h, handle, GNUNET_VPN_Handle::mq, msg, op, and GNUNET_PILS_Operation::op_id.

Referenced by handle_dv_box(), handle_initiator_hello(), and handle_responder_hello().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_feed_addresses()

void GNUNET_PILS_feed_addresses	(	struct GNUNET_PILS_Handle *	handle,
		const struct GNUNET_HELLO_Builder *	addresses_builder
	)

Feed a set of addresses to pils so that it will generate a new peer id based on the given set of addresses.

THIS IS ONLY TO BE CALLED FROM CORE!

The address representation will be canonicalized/sorted by pils before the new peer id is generated.

Parameters

handle	the handle to the PILS service
addresses_builder	addresses to feed as builder

Definition at line 542 of file pils_api.c.

{
  struct FeedAddressesMessage *msg;
  struct GNUNET_MQ_Envelope *env;
  size_t block_bytes;
 
  block_bytes = GNUNET_HELLO_get_builder_to_block_size (builder);
  // TODO check whether the new hash and the 'current' hash are the same -
  //      nothing to do in that case (directly return the peer id?)
  env = GNUNET_MQ_msg_extra (msg,
                             block_bytes,
                             GNUNET_MESSAGE_TYPE_PILS_FEED_ADDRESSES);
  msg->block_len = htonl (block_bytes);
  GNUNET_HELLO_builder_to_block (
    builder,
    NULL,
    NULL,
    GNUNET_TIME_relative_to_absolute (GNUNET_TIME_UNIT_ZERO),
    (char*) &msg[1]);
  GNUNET_MQ_send (handle->mq, env);
}

References builder, env, GNUNET_HELLO_builder_to_block(), GNUNET_HELLO_get_builder_to_block_size(), GNUNET_MESSAGE_TYPE_PILS_FEED_ADDRESSES, GNUNET_MQ_msg_extra, GNUNET_MQ_send(), GNUNET_TIME_relative_to_absolute(), GNUNET_TIME_UNIT_ZERO, handle, GNUNET_VPN_Handle::mq, and msg.

Referenced by feed_addresses_to_pils().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_derive_pid()

void GNUNET_PILS_derive_pid	(	size_t	seed_key_bytes,
		const uint8_t	seed_key[seed_key_bytes],
		const struct GNUNET_HashCode *	addrs_hash,
		struct GNUNET_CRYPTO_EddsaPrivateKey *	outkey
	)

Generate the peer id from the addresses hash and the initial secret key.

Parameters

	seed_key_bytes	length of the seed key in bytes
	seed_key	the initial secret key
	addrs_hash	the address to use for derivation
[out]	outkey	the (private) peer identity key

Since we should have initial keying material of good quality here, this is effectively a PRF called on the address hash with a uniform random key.

We now expand the PRK to the key size we actually require. FIXME: IF we want to use elligator, we need to find a private key that can actually be used as such. For that, we may want to add a coutner to the initial secret key to the above PRF.

Definition at line 507 of file pils_api.c.

{
  struct GNUNET_ShortHashCode prk;
 
  GNUNET_assert (GNUNET_OK ==
                 GNUNET_CRYPTO_hkdf_extract (&prk,
                                             addrs_hash,
                                             sizeof *addrs_hash,
                                             seed_key,
                                             seed_key_bytes));
  GNUNET_CRYPTO_hkdf_expand (outkey,
                             sizeof *outkey,
                             &prk,
                             "gnunet-pils-ephemeral-peer-key",
                             strlen ("gnunet-pils-ephemeral-peer-key"),
                             NULL, 0);
}

References GNUNET_assert, GNUNET_CRYPTO_hkdf_expand(), GNUNET_CRYPTO_hkdf_extract(), GNUNET_OK, and seed_key.

Referenced by do_generate_pid(), pid_change_cb(), and run().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_sign_hello()

struct GNUNET_PILS_Operation * GNUNET_PILS_sign_hello	(	struct GNUNET_PILS_Handle *	handle,
		const struct GNUNET_HELLO_Builder *	builder,
		struct GNUNET_TIME_Absolute	et,
		GNUNET_PILS_SignResultCallback	cb,
		void *	cb_cls
	)

Create HELLO signature.

Parameters

handle	hande to the pils service
builder	the builder to use
et	expiration time to sign
cb	callback to call with the signature
cb_cls	closure to cb

Definition at line 576 of file pils_api.c.

{
  struct PilsHelloSignaturePurpose hsp = {
    .purpose.size = htonl (sizeof (hsp)),
    .purpose.purpose = htonl (GNUNET_SIGNATURE_PURPOSE_HELLO),
    .expiration_time = GNUNET_TIME_absolute_hton (et)
  };
  GNUNET_HELLO_builder_hash_addresses (builder,
                                       &hsp.h_addrs);
  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
              "Address hash is %s\n",
              GNUNET_h2s_full (&hsp.h_addrs));
  return GNUNET_PILS_sign_by_peer_identity (handle,
                                            &hsp.purpose,
                                            cb,
                                            cb_cls);
}

References builder, GNUNET_ERROR_TYPE_DEBUG, GNUNET_h2s_full(), GNUNET_HELLO_builder_hash_addresses(), GNUNET_log, GNUNET_PILS_sign_by_peer_identity(), GNUNET_SIGNATURE_PURPOSE_HELLO, GNUNET_TIME_absolute_hton(), PilsHelloSignaturePurpose::h_addrs, handle, PilsHelloSignaturePurpose::purpose, and GNUNET_CRYPTO_EccSignaturePurpose::size.

Referenced by peerstore_store_own_cb(), and pid_changed_cb().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_PILS_cancel()

void GNUNET_PILS_cancel

(

struct GNUNET_PILS_Operation *

op

)

Cancel request.

Parameters

op	cancel PILS operation

Definition at line 495 of file pils_api.c.

{
  struct GNUNET_PILS_Handle *h = op->h;
 
  GNUNET_CONTAINER_DLL_remove (h->op_head, h->op_tail, op);
  if (NULL != op->env)
    GNUNET_MQ_discard (op->env);
  GNUNET_free (op);
}

References GNUNET_PILS_Operation::env, GNUNET_CONTAINER_DLL_remove, GNUNET_free, GNUNET_MQ_discard(), h, GNUNET_PILS_Operation::h, and op.

Referenced by do_shutdown(), GCH_shutdown(), GSC_KX_done(), and shutdown_task().

Here is the call graph for this function:

Here is the caller graph for this function: