AtHeartEngineer/specs
1
0
Fork 0
mirror of https://github.com/vacp2p/specs.git synced 2026-01-08 23:08:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

Rename origin to hostname

Browse Source
This commit is contained in:
Marco Munizaga
2024-07-02 14:26:28 -07:00
parent f56e82d2c5
commit ccec98035e
1 changed files with 14 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
http/peer-id-auth.md
View File

@@ -20,7 +20,7 @@ scheme is called `libp2p-PeerID`.
| Param Name | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| origin | The server name used in the TLS connection (SNI). |
| hostname | The server name used in the TLS connection (SNI). |
| challenge-server | The random base64 encoded value the client generates to challenge the server to prove its identity |
| challenge-client | The random base64 encoded value the server generates to challenge the client to prove its identity |
| sig | A base64 encoded signature. |
@@ -28,7 +28,7 @@ scheme is called `libp2p-PeerID`.
| public-key | A base64 encoded value of peer's public key. The key itself is encoded per the [Peer ID spec]. |
| opaque | An base64 encoded opaque to the client blob generated by the server. If a client receives this it must return it. A server may use this to authenticate statelessly. For example, it could store the challenge-client and a expiry time. |
Params are encoded per [RFC 9110 auth-param's ABNF](https://datatracker.ietf.org/doc/html/rfc9110#name-collected-abnf). Generally it'll be something like: `origin="example.com", challenge-server=base64EncodedVal`
Params are encoded per [RFC 9110 auth-param's ABNF](https://datatracker.ietf.org/doc/html/rfc9110#name-collected-abnf). Generally it'll be something like: `hostname="example.com", challenge-server=base64EncodedVal`
## Signing
@@ -39,11 +39,11 @@ used. Refer to the [Peer ID
spec] for
specifics on the signing algorithm. The set of parameters is prefixed with the auth scheme "libp2p-PeerID"
As an example, if we wanted to sign the parameters `origin="example.com",
As an example, if we wanted to sign the parameters `hostname="example.com",
challenge-client=base64String` we would first structure the parameters as a byte
slice containing:
```
libp2p-PeerID<varintprefix>challenge-client=<base64String><varintprefix>origin="example.com"
libp2p-PeerID<varintprefix>challenge-client=<base64String><varintprefix>hostname="example.com"
```
Then sign the resulting byte slice. See the test vectors below for a
@@ -77,7 +77,7 @@ protocol operates as follows:
```
The `sig` param represents a signature over the parameters:
- `origin`
- `hostname`
- `challenge-client` in its base64 encoded form.
4. The server MUST verify the signature using the server name used in the TLS
session. The server MUST return 401 Unauthorized if the server fails to
@@ -89,7 +89,7 @@ protocol operates as follows:
Authorization: libp2p-Bearer <base64-encoded-opaque-blob>
```
The `sig` param represents a signature over the parameters:
- `origin`
- `hostname`
- `challenge-server` in its base64 encoded form.
- `client` the string representation of the client's Peer ID.
@@ -97,7 +97,7 @@ protocol operates as follows:
requests. The value is opaque to the client, and the server may use it to
store authentication state such as:
- The client's Peer ID.
- The `origin` parameter.
- The `hostname` parameter.
- The token creation date (to allow tokens to expire).
5. The client MUST verify the signature. After verification the client has
authenticated the server's peer id. The client MUST send the `libp2p-Bearer`
@@ -160,11 +160,11 @@ Included is a concrete example of running the protocol. The client uses the Peer
```
3. The client sends another request with the header:
```
Authorization: libp2p-PeerID peer-id=12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq, opaque=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=, challenge-server=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=, sig=MKoR8Shzr6VmQ675dErKh_gGGUsGaO8zXnZ8Cx8bIKiQlYBhqazUG8w4lG3_Wd5IfSz5P1HLfXtVb_fg_dsxDw==
Authorization: libp2p-PeerID peer-id=12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq, opaque=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=, challenge-server=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=, sig=F5OBYbbMXoIVJNWrW0UANi7rrbj4GCB6kcEceQjajLTMvC-_jpBF9MFlxiaNYXOEiPQqeo_S56YUSNinwl0ZCQ==
```
4. The server responds with the header:
```
Authentication-Info: libp2p-PeerID peer-id=12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN, sig=m0OkSsO9YGcqfZ_XVTbiRwTtM4ds8434D9aod22Mmo3Wm0vBvxHOd71glC-uEez6g5gjA580KkGc9DOIvP47BQ==
Authentication-Info: libp2p-PeerID peer-id=12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN, sig=btLFqW200aDTQqpkKetJJje7V-iDknXygFqPsfiegNsboXeYDiQ6Rqcpezz1wfr8j9h83QkN9z78cAWzKzV_AQ==
Authorization: libp2p-Bearer <base64-encoded-bearer-token>
```
@@ -173,26 +173,20 @@ The following table lists out all parameters and intermediate values used in the
| Parameter | value |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| origin | example.com |
| hostname | example.com |
| challenge-client | `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=` |
| challenge-server | `BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=` |
| client peer id | `12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq` |
| server's peer id | The zero key `12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN` |
| The server's opaque blob | Could be anything. In this example we'll use `CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=`. |
| What the client will sign (percent encoded) | `libp2p-PeerID=challenge-client=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=%12origin=%22example.com%22` |
| The client's signature | `MKoR8Shzr6VmQ675dErKh_gGGUsGaO8zXnZ8Cx8bIKiQlYBhqazUG8w4lG3_Wd5IfSz5P1HLfXtVb_fg_dsxDw==` |
| What the client will sign (percent encoded) | `libp2p-PeerID=challenge-client=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=%16hostname=%22example.com%22` |
| The client's signature | `F5OBYbbMXoIVJNWrW0UANi7rrbj4GCB6kcEceQjajLTMvC-_jpBF9MFlxiaNYXOEiPQqeo_S56YUSNinwl0ZCQ==` |
| The client's Authorization header | `Authorization: libp2p-PeerID peer-id=12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq, opaque=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=, challenge-server=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=, sig=MKoR8Shzr6VmQ675dErKh_gGGUsGaO8zXnZ8Cx8bIKiQlYBhqazUG8w4lG3_Wd5IfSz5P1HLfXtVb_fg_dsxDw==` |
| What the server will sign (percent encoded) | `libp2p-PeerID=challenge-server=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=%3Bclient=12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq%14origin=%22example.com%22` |
| The server's signature | `m0OkSsO9YGcqfZ_XVTbiRwTtM4ds8434D9aod22Mmo3Wm0vBvxHOd71glC-uEez6g5gjA580KkGc9DOIvP47BQ==` |
| What the server will sign (percent encoded) | `libp2p-PeerID=challenge-server=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=%3Bclient=12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq%16hostname=%22example.com%22` |
| The server's signature | `btLFqW200aDTQqpkKetJJje7V-iDknXygFqPsfiegNsboXeYDiQ6Rqcpezz1wfr8j9h83QkN9z78cAWzKzV_AQ==` |
| The server's Authentication-Info header | `Authentication-Info: libp2p-PeerID peer-id=12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN, sig=m0OkSsO9YGcqfZ_XVTbiRwTtM4ds8434D9aod22Mmo3Wm0vBvxHOd71glC-uEez6g5gjA580KkGc9DOIvP47BQ==` |
TODOS:
- [ ]: Rename origin to hostname
TODO (marco): include a couple examples of what is signed, exchanged, and
resulting signature.
[Peer ID spec]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md
[@MarcoPolo]: https://github.com/MarcoPolo