| Internet-Draft | PILS | July 2025 |
| Schanzenbach & ch3 | Expires 29 January 2026 | [Page] |
This document contains the GNUnet peer lifecycle service specification.¶
This document defines the normative wire format of peer identity lifecycle protocols, cryptographic routines and security considerations for use by implementers.¶
This specification was developed outside the IETF and does not have IETF consensus. It is published here to inform readers about the function of GNUnet peer identity lifecycles, guide future implementations, and ensure interoperability among implementations including with the pre-existing GNUnet implementation.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 29 January 2026.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
Consider the following scenario: You use your GNUnet peer day-to-day from home. One day, you decide to take a trip. With your device, and GNUnet peer. Let's assume you take that trip by plane to Oceania. It may be dangerous for you, depending on your activities and occupation at home, if your GNUnet peer would reconnect to the network when you arrive on Oceania and advertise your Peer ID because it would be linkable to the your peer's activities back home.¶
More generally, we would like some degree of Peer unlinkability, depending on the context in which we run our peer. Ideally, the Peer ID changes when the context changes.¶
Changing PeerID requires further considerations than simply unlinkability. For example it may seem prudent to use dedicated, randomly generated public key per address. The reason why this is a bad idea is hidden in requirements from higher layers: Having the peer handle multiple peer identities for each endpoint address will cause the connectivity on the DHT overlay to deteriorate. The same physical node in the network may be reachable on N different endpoints. If each of those endpoints is associated with a random peer identity (and advertised as such) other peers may populate their routing tables with more than one of those addresses, in the worst case all N of them. However, any connection establishment to the same node in the network does not improve connectivity and resiliance of the overlay network. Likely, connectivity will degrade and if the peer is no longer reachable (churn / peer offline) more than one entry in the routing table will have to be replaced with new connections that in turn will again possibly only be connections to the same local node in the network.¶
This document details a method to deterministically derive a peer identity from the current set of endpoint addresses the peer is available at currently. This provides a reasonable tradeoff between unlinkability for certain use cases, and stability for higher layers in the GNUnet protocol stack.¶
This specification was developed outside the IETF and does not have IETF consensus. It is published here to guide implementers and ensure interoperability among implementations.¶
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The address hash is calculated over the concatenation of all address strings (URIs) using SHA-512. The addresses MUST be sorted alphanumerically. The byte 0x00 is used as a separator between URIs in the hash input. Consequently the hash may simply be calculated over the full C strings including their 0-terminator. Due to the flexibility of possible URI values this prevents any kind of odd common-prefix case in which hashes may collide.¶
Given an address hash h_addr and an initial key seed, the deterministic address-derived peer ID is calculated using HKDF ([RFC5869]) as:¶
prk = HKDF-Extract(h_addr,seed) sk = HKDF-Expand(prk, "gnunet-pils-contextual-peer-key", 32)
"." shows the argument position of the input variable from the incoming arrow.¶
FIXME: Possibly needs algorithm for Elligator to iteratively try secret keys that can be used.¶
TODO: Crypto considerations.¶
While the approach provides some privacy in certain use cases, it is not a general solution to prevent peer identity linkability. For example, if the peer is configured a permanent, static and global address it will be trivially linkable even if PILS derives different peer identities. As such, the peer identity derivation is aimed to protect common use cases for the average user where it is to be expected that no such global and static address is availalble as outlined in the introduction.¶
It may seem odd why GNUnet does not use a dedicated, randomly generated public key per address. The reason is hidden in requirements from higher layers: Having the peer handle multiple peer identities for each endpoint will cause the connectivity on the DHT overlay to deteriorate. The same physical node in the network may be reachable on N different endpoints. If each of those endpoints is associated with a random peer identity (and advertised as such) other peers may populate their routing tables with more than one of those addresses, in the worst case all N of them. However, any connection establishment to the same node in the network does not improve connectivity and resiliance of the overlay network. Likely, connectivity will degrade and if the peer is no longer reachable (churn / peer offline) more than one entry in the routing table will have to be replaced with new connections that in turn will again possibly only be connections to the same local node in the network.¶
There is one implementation conforming to this specification, written in C. The implementation is part of [GNUnet] and represents the original and reference implementation.¶
FIXME test vectors¶
The following test vectors can be used by implementations to test for conformance with this specification. Unless indicated otherwise, the test vectors are provided as hexadecimal byte arrays.¶
Addresses (sorted): gnunet+udp://6.7.8.9 gnunet+tcp://1.2.3.4 gnunet+https://example.gnu Address hash: 6c57def87391551d 2d5b16abb8072e42 dc389a3a85723fcb a26afdcaccaea027 3af57a3e0e1d8777 8099afb0e9a00995 c444927a120f0170 732d4fe0f50e3cb2 Seed key: 50d7b652a4efeadf f37396909785e595 2171a02178c8e7d4 50fa907925fafd98 Derived key: 9b8d17711be50a07 e7d984bd9c1e6d9c f5492cfb2713f8cb 42eaf251573f39d7¶