Skip to content

Commit

Permalink
*: Rename p2p-circuit-inner to p2p-circuit-security
Browse files Browse the repository at this point in the history
  • Loading branch information
mxinden committed Oct 4, 2021
1 parent 6d8004e commit 3c1487a
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 16 deletions.
7 changes: 2 additions & 5 deletions addressing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -393,13 +393,10 @@ connection involves 3 security protocol upgrades:
3. Upgrading the relayed connection from the source to the destination.

The security protocol is specified by appending
`/p2p-circuit-inner/<relayed-connection-security-protocol>` to the full
`/p2p-circuit-security/<relayed-connection-security-protocol>` to the full
address.

<!-- TODO: Is `p2p-circuit-inner` the ideal name? Up for alternative
suggestions. -->

Example: `<relay-mulitaddr>/p2p-circuit/<destination-multiaddr>/p2p-circuit-inner/tls`
Example: `<relay-mulitaddr>/p2p-circuit/<destination-multiaddr>/p2p-circuit-security/tls`

Note: One might be tempted to not specify (3) and simply use the security
protocol in (2). This would break if the security protocol used for (2) can
Expand Down
22 changes: 11 additions & 11 deletions relay/circuit-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,34 +301,34 @@ be encapsulated in the multiaddr (see [The multiaddr security component
section](../addressing/README.md#the-multiaddr-security-component)). A relayed
connection is not an exception. A target advertises the support for a security
protocol for relayed connections by appending
`/p2p-circuit-inner/<security-protocol>` to its relayed multiaddresses. An
`/p2p-circuit-security/<security-protocol>` to its relayed multiaddresses. An
initiator may include any set of relayed multiaddr in the `peer` field of
`HopMessage` on type `CONNECT` in which all addresses end with the same
`/p2p-circuit-inner/<security-protocol>`. The initiator is thus signaling to the
`/p2p-circuit-security/<security-protocol>`. The initiator is thus signaling to the
target which security protocol, out of all advertised security protocols
by the target, the initiator chose to use on the relayed connection.

As an example, let's say the target listens for incoming relayed connections via
relay `R1` and relay `R2`. In addition it supports both TLS Noise as security
protocols. It would then advertise the following relayed multiaddresses:

- `<relay-R1-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-inner/tls`
- `<relay-R1-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-inner/noise`
- `<relay-R2-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-inner/tls`
- `<relay-R2-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-inner/noise`
- `<relay-R1-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-security/tls`
- `<relay-R1-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-security/noise`
- `<relay-R2-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-security/tls`
- `<relay-R2-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-security/noise`

Once the initiator received the above multiaddresses and decides to initiate a
relayed connection to the target, it needs to decide whether it wants to secure
the relayed connection via TLS or Noise. Say it decides for Noise it would then
include the multiaddresses below in it `HopMessage` with type `Connect` in the
`peer` field:

- `<relay-R1-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-inner/noise`
- `<relay-R2-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-inner/noise`
- `<relay-R1-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-security/noise`
- `<relay-R2-multiaddr>/p2p-circuit/p2p/QmTarget/p2p-circuit-security/noise`

Note that all addresses sent by the initiator in the `peer` field MUST share the
same security protocol for the relayed connection
(`/p2p-circuit-inner/<security-protocol>`).
(`/p2p-circuit-security/<security-protocol>`).

### Stop Protocol

Expand Down Expand Up @@ -371,15 +371,15 @@ Common failure status codes are:
#### Security protocol selection for the relayed connection

A target may advertise support for different security protocols by advertising
multiple multiaddresses with different `/p2p-circuit-inner/<security-protocol>`
multiple multiaddresses with different `/p2p-circuit-security/<security-protocol>`
suffixes. A target needs some mechanism to determine which of the advertised
security protocols the initiator intends to use to secure an incoming relayed
connection. The target can use the addresses included in the `target` field of
the `StopMessage` to determine which security protocol the initiator chose to
secure the relayed connection.

Note that all addresses sent by the initiator MUST share the same security
protocol for the relayed connection (`/p2p-circuit-inner/<security-protocol>`).
protocol for the relayed connection (`/p2p-circuit-security/<security-protocol>`).
Thus a target MUST abort the connection attempt (i.e. reset the stream) if it
receives a `CONNECT` with varying security protocols for the relay connection.

Expand Down

0 comments on commit 3c1487a

Please sign in to comment.