mirrors/hockeypuck
1
0
Fork 0
mirror of https://github.com/hockeypuck/hockeypuck.git synced 2025-12-17 08:55:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Page: HIP 013: In‐Band Metadata Sync Using Trust Packets
Pages
HIP 000: Hockeypuck Improvement Proposals HIP 001: [REVERTED] Regaining control over public key identity with authenticated key management HIP 002: SKS v2 protocol HIP 003: Timestamp aware merge strategy HIP 004: Third party revocation sig distribution HIP 005: Reliable personal data deletion using self signatures HIP 006: WKD support HIP 007: Recursive resolver HIP 008: Out of Band Email Ownership Proof HIP 009: Management Interface HIP 010: Internal rate limiting support HIP 011: Merge ptree into pghkp HIP 012: Define and use JSON‐LD schemas HIP 013: In‐Band Metadata Sync Using Trust Packets Home Migrating from SKS‐keyserver to Hockeypuck Semantic Versioning Policy Upgrading docker‐compose standalone deployment from 2.1 to 2.2
HIP 013: In‐Band Metadata Sync Using Trust Packets
Andrew Gallagher edited this page 2025-12-08 12:05:27 +00:00
Table of Contents

We propose an SKS-specific Trust Packet format to store and sync data that cannot be otherwise represented as part of a certificate/TPK. Such metadata would be synced between SKS peers but stripped when served to clients over HKP.

Motivation

Keyservers may wish to store and sync config and metadata such as blocklist entries, out of band proofs, index keywords, etc. While this could be done using an additional side-band protocol, it would be elegant and efficient if metadata could be transferred using the existing sks sync process.

Design

Original PGP used a trust packet body consisting of two uint8 fields denoting key/userid trust, and cached signature verification state. GnuPG extended this with four domsep bytes: three UTF-8 bytes containing “gpg”, and one uint8 field denoting the context (0=signature, 1=key, 2=userid), followed optionally by further GnuPG-specific fields. A trust packet immediately follows the "trustable" packet to which it refers, before any signatures over that packet (internally, GnuPG treats it as an extension of the preceding packet).

The SKS trust packet follows the above wire format up to and including the domsep fields, to minimise the risk of breaking a legacy parser if encountered unexpectedly.

The body of an SKS trust packet is as follows:

  • Two uint8 zero bytes (TBC, we may wish to set the top bit of the second byte to prevent GnuPG attempting to parse it)
  • Four domsep bytes:
    • Three UTF-8 application identifier bytes, containing either “sks” or “SKS”
    • One uint8 context identifier byte (same code points as GnuPG)
  • If the application identifier was “SKS”:
    • A four-octet length of the following field
    • A hashed signature subpacket area
  • An unhashed signature subpacket area consisting of the rest of the packet body

Metadata should generally be stored as notation subpackets in the user namespace, but other subpacket types may also be included if appropriate, such as embedded signatures.

The SKS trust packet comes in two forms:

  • A “quiet SKS trust packet” has a lowercase application identifier of “sks”, and is omitted from SKS digest calculations. It is therefore only synced as a side effect of another update, and is used for non-critical metadata. It can be safely served to legacy peers, as they will silently discard it.

  • A “noisy SKS trust packet” has an uppercase application identifier of “SKS”, and its contents up to the end of the hashed area are included in SKS digest calculations. If it is not present on both sides, it will therefore cause sync failure, so is used only for critical information, or where sync failure is unavoidable (e.g. with mismatched blocklists)

Noisy trust packets are particularly useful where the trust packet itself is the only available data, for example when a key has been blocked. Since there is no associated certificate data, the trust packet must contribute to the SKS hash, otherwise all entries would have the same hash and would not sync. For most use cases a quiet trust packet should be employed.

Noisy trust packets must not contain any superfluous metadata in their hashed ares, such as the generating server or application, or a timestamp. Multiple servers could independently create semantically-equivalent packets and if the hashed areas were not binary identical they would never resolve.

All trust packets may however contain such metadata in their unhashed areas.

Unlike GnuPG, which permits at most one trust packet per "trustable" packet, SKS imposes no such restriction - this allows trust packets from multiple sources to be aggregated.

Examples of interactions

Enumerable domains

A redacted certificate may contain a quiet trust packet with notations denoting search terms for which the redacted certificate should be served. This can be used to cache part of the identity string from a deleted userid, for example if a domain owner wishes to serve hard revocations in response to searches for their domain name, which would otherwise not be indexable. (see https://github.com/hockeypuck/hockeypuck/issues/338)

Keyservers configured with a list of enumerable domains will add to a quiet trust packet the domain portion of any userids that they delete due to a redacting signature. In turn, the indexer will treat these notations as additional search keywords.

Keyservers operated by the same person or organisation can be configured to add received identity cache entries if they were generated by a trusted peer, even if they do not match the current indexing policy. This should (😬) allow for updated indexing policies to be rolled out progressively without data loss.

Forbidden keys

Each forbidden key will have a record in the keys database containing one noisy trust packet. The trust packet contains a single notation to identify the primary key fingerprint of the blocked key. The context field is set to “key” but is otherwise ignored.

This “key” will be synced like any other entry in the database, but will not automatically be added to the database of a receiving server. This will in general cause a persistent sync delta, but it should be remembered that blocklist differences already cause such deltas by design, and are handled by the LRU cache.

Keyservers operated by the same person or organisation can however be configured to add blocked key entries if they were generated by a trusted peer. In such cases the delta should eventually resolve.

This replaces the earlier “table blocklist” proposal mentioned in https://github.com/hockeypuck/hockeypuck/issues/184 and https://github.com/hockeypuck/hockeypuck/issues/229

Currently, "forbidden" keys are implemented by adding them to the blocklist in the configuration and then deleting them from the database. "Frozen" keys (i.e. the current behaviour when a key is added to the blocklist but not deleted from the database) could be implemented by adding a quiet trust packet on the primary key.

Out of scope

The inclusion of trust packets in HKP submissions and responses; these will be tackled separately if necessary.

Security considerations

TBC

Compatibility

Quiet trust packets should not cause compatibility issues with peers that correctly ignore foreign trust packets, since they will be discarded on import and existing servers should therefore not include them in the SKS hash. Noisy trust packets will require a filter bump to ensure they are hashed correctly on both sides.

Neither form of trust packet is intended to be exported to clients, however clients SHOULD ignore foreign trust packets and should therefore be unaffected if a keyserver were to accidentally serve them.

Plan

Quiet trust packets can be added at any time. Each distinct use of noisy trust packets will require a filter bump.