Trusted peers

This page shows how to use the trusted-peer list for its two jobs: limiting who can connect, and allowing forwarding.

One list, two uses

/etc/ricochet/config.yaml

security:
  trusted_peers:
    - 12D3KooWExampleAlice...
    - 12D3KooWExampleGateway...

security.trusted_peers is a list of peer IDs. Every entry must be a valid peer ID, or the server refuses to start. On its own the list does nothing; two feature flags consult it:

Flag	Default	What the list means
features.enable_authentication	off	The peers allowed to connect at all
features.enable_forwarding	off (on in the high-capacity preset)	The peers allowed to submit mail on another sender’s behalf

There is no command-line flag for either; set them in the file.

A private server

With enable_authentication on, only the listed peers can connect:

/etc/ricochet/config.yaml

features:
  enable_authentication: true
security:
  trusted_peers:
    - 12D3KooWExampleAlice...
    - 12D3KooWExampleBob...

The check runs right after the Noise handshake, the first moment the remote peer’s identity is proven. An untrusted peer costs one handshake and is disconnected before it can open any stream.

Only inbound connections are checked. The server’s own outbound dials (to bootstrap peers, for DHT lookups, for push notifications) are allowed, since the server chose to make them.

Turning authentication on with an empty list is a startup error, since it would refuse everyone:

invalid config: enable_authentication requires at least one entry in trusted_peers

No preset turns authentication on.

What a private server still does

Authentication controls who connects, not what the server does on the network. A private server still runs its DHT, GossipSub and, unless you turn it off, the relay service, but only for the peers it lets in and the ones it dials. If the server should not relay for anyone, set features.enable_relay_service: false as well. See NAT traversal & relay.

Every client and other server that needs to reach a private server must be on the list. ricochet-bench generates a fresh identity for each worker on every run, so it cannot run against a server with authentication on. See Benchmarking.

Forwarding

Normally the server refuses a message whose sender is not the peer on the connection. With enable_forwarding on, a listed peer may submit messages on behalf of other senders, for example a gateway relaying mail it received elsewhere:

/etc/ricochet/config.yaml

features:
  enable_forwarding: true
security:
  trusted_peers:
    - 12D3KooWExampleGateway...

A forwarded message is:

• accepted only from a listed peer; anyone else gets a refusal saying the forwarder is not trusted;
• marked forwarded, with its hop count increased by one;
• refused once its hop count exceeds 10, so a loop between forwarders ends;
• charged to the forwarder, not the original sender, for any rate limit.

The server cannot verify the original sender of a forwarded message. That is why only trusted peers may forward.

With forwarding on and the list empty, nobody can forward, and the server logs at startup:

enable_forwarding is on but trusted_peers is empty; no peer may forward

Find a peer’s ID

A peer’s ID is the 12D3KooW... string its software prints or logs. For another Ricochet server, it is in the startup line Ricochet server ... running. Peer ID: .... For a client built with pkg/client, it is the client’s PeerID().

Check it works

• With authentication on, the server logs authentication enabled: inbound connections limited to trusted peers with the number of trusted peers.
• A refused peer is logged at DEBUG as refused untrusted peer with its peer ID and address. Start with --development to see these lines.
• A forwarded message is logged at DEBUG as forwarded message routed to local MDA, with the forwarder, sender, recipient and hop count.

Troubleshooting

• trusted_peers entry "..." is not a peer ID: the entry is mistyped or is a full multiaddr. List the bare peer ID, without /p2p/.
• A listed client still cannot connect: check that its peer ID is exactly the one in the list. A client that regenerates its key on every start gets a new peer ID each time.
• Forwarded submissions are refused: check that enable_forwarding is on, the forwarder is listed, and the message’s hop count has not reached the limit.