mirror of
https://github.com/vacp2p/specs.git
synced 2026-01-07 22:44:07 -05:00
Drop peer-id parameter. Only public keys
This commit is contained in:
Marco Munizaga
@@ -24,8 +24,7 @@ scheme is called `libp2p-PeerID`.
|
||||
| challenge-server | The random quoted string value the client generates to challenge the server to prove its identity |
|
||||
| challenge-client | The random quoted string value the server generates to challenge the client to prove its identity |
|
||||
| sig | A base64 encoded signature. |
|
||||
| peer-id | The Peer ID of the node that set this parameter. Encoding defined by the [Peer ID spec]. |
|
||||
| public-key | A base64 encoded value of peer's public key. The key itself is encoded per the [Peer ID spec]. |
|
||||
| public-key | A base64 encoded value of peer's public key. This MUST be the key used for the Peer's Peer ID. The key itself is encoded per the [Peer ID spec]. |
|
||||
| opaque | A value 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-cmaollected-abnf). Generally it'll be something like: `hostname="example.com", challenge-server="challenge-string"`
|
||||
@@ -39,11 +38,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 `hostname="example.com",
|
||||
challenge-client="<challenge-string>"` we would first structure the parameters as a byte
|
||||
As an example, if we wanted to sign the parameters `hostname = example.com`,
|
||||
`challenge-client = <challenge-string>`, and `client-public-key = 0xbadcofee` we would first structure the parameters as a byte
|
||||
slice containing:
|
||||
```
|
||||
libp2p-PeerID<varintprefix>challenge-client="<challenge-string>"<varintprefix>hostname="example.com"
|
||||
libp2p-PeerID<varint-len-prefix>challenge-client=<challenge-string><varint-len-prefix>hostname=example.com<varint-len-prefix>client-public-key=<raw-bytes>
|
||||
```
|
||||
|
||||
Then sign the resulting byte slice. See the test vectors below for a
|
||||
@@ -58,6 +57,13 @@ Alphabet from [RFC
|
||||
omitted. The reason this is not a multibase is to aid clients or servers who
|
||||
can not or prefer not to import a multibase dependency.
|
||||
|
||||
## Public Key Encoding
|
||||
|
||||
The authentication below exchanges the peer's public key instead of its PeerID,
|
||||
as the public key can be used to verify signatures and derive the PeerID, while
|
||||
the PeerID may not contain the public key in all cases. The Public Key is
|
||||
encoded per the [Peer ID spec] under the section "Keys" section.
|
||||
|
||||
## Mutual Client and Server Peer ID Authentication
|
||||
|
||||
The following protocol allows both the client and server to authenticate each
|
||||
@@ -67,35 +73,31 @@ protocol operates as follows:
|
||||
1. The client makes an HTTP request to an authenticated resource.
|
||||
2. The server responds with status code 401 (Unauthorized) and set the header:
|
||||
```
|
||||
WWW-Authenticate: libp2p-PeerID challenge-client="<challenge-string>", opaque="<base64-encoded-opaque-value>"
|
||||
WWW-Authenticate: libp2p-PeerID challenge-client="<challenge-string>", opaque="<opaque-value>"
|
||||
```
|
||||
The opaque parameter is opaque to client. The client MUST return the opaque
|
||||
parameter back to the server. The server MAY use the opaque parameter to
|
||||
encode state.
|
||||
3. The client makes another HTTP request to the same authenticated resource and sets the header:
|
||||
```
|
||||
Authorization: libp2p-PeerID peer-id="<string-representation-of-client-peer-id>", opaque="<opaque-from-server>", challenge-server="<challenge-string>",[ public-key="<base64-encoded-public-key-bytes>",] sig="<base64-signature-bytes>"
|
||||
Authorization: libp2p-PeerID public-key="<base64-encoded-public-key-bytes>", opaque="<opaque-from-server>", challenge-server="<challenge-string>", sig="<base64-signature-bytes>"
|
||||
```
|
||||
|
||||
The `public-key` param is optional and represents the client's public key. This is only needed when the client's public key is not included in the PeerID (e.g. not using the "identity" multihash).
|
||||
|
||||
The `sig` param represents a signature over the parameters:
|
||||
- `hostname`
|
||||
- `challenge-client`
|
||||
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
|
||||
validate the signature. If the signature is valid, the server has
|
||||
authenticated the client's Peer ID. The server SHOULD proceed to serve the HTTP request. The server MUST set the following response headers:
|
||||
authenticated the client's public key, and thus its PeerID. The server SHOULD proceed to serve the HTTP request. The server MUST set the following response headers:
|
||||
```
|
||||
Authentication-Info: libp2p-PeerID peer-id="<server-peer-id-string>", sig="<base64-signature-bytes>"[, public-key="<base64-encoded-public-key-bytes>"] bearer="<base64-encoded-opaque-blob>"
|
||||
Authentication-Info: libp2p-PeerID public-key="<base64-encoded-public-key-bytes>", sig="<base64-signature-bytes>" bearer="<base64-encoded-opaque-blob>"
|
||||
```
|
||||
|
||||
Again, the `public-key` param is optional and represents the server's public key. This is only needed when the public key is not included in the PeerID (e.g. not using the "identity" multihash).
|
||||
|
||||
The `sig` param represents a signature over the parameters:
|
||||
- `hostname`
|
||||
- `challenge-server`
|
||||
- `client-peer-id` the string representation fo the client's peer id
|
||||
- `client-public-key` the bytes of the client's public-key encoded per the [Peer ID spec].
|
||||
|
||||
The `bearer` token allows the client to make future Peer ID authenticated
|
||||
requests. The value is opaque to the client, and the server may use it to
|
||||
@@ -180,20 +182,20 @@ Included is a concrete example of running the protocol. The client uses the Peer
|
||||
|
||||
The following table lists out all parameters and intermediate values used in the walkthrough above.
|
||||
|
||||
| Parameter | value |
|
||||
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 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) | `todo` |
|
||||
| The client's signature | `todo` |
|
||||
| The client's Authorization header | `Authorization: libp2p-PeerID peer-id="12D3KooWBtg3aaRMjxwedh83aGiUkwSxDwUZkzuJcfaqUmo7R3pq", opaque="CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=", challenge-server="BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=", sig="F5OBYbbMXoIVJNWrW0UANi7rrbj4GCB6kcEceQjajLTMvC-_jpBF9MFlxiaNYXOEiPQqeo_S56YUSNinwl0ZCQ=="` |
|
||||
| What the server will sign (percent encoded) | `todo` |
|
||||
| The server's signature | `todo` |
|
||||
| The server's Authentication-Info header | `Authentication-Info: libp2p-PeerID peer-id="12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN", sig="btLFqW200aDTQqpkKetJJje7V-iDknXygFqPsfiegNsboXeYDiQ6Rqcpezz1wfr8j9h83QkN9z78cAWzKzV_AQ==", bearer="<some-opaque-value>"` |
|
||||
| Parameter | value |
|
||||
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| 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) | `todo` |
|
||||
| The client's signature | `todo` |
|
||||
| The client's Authorization header | `todo` |
|
||||
| What the server will sign (percent encoded) | `todo` |
|
||||
| The server's signature | `todo` |
|
||||
| The server's Authentication-Info header | `todo` |
|
||||
|
||||
|
||||
[Peer ID spec]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md
|
||||
|
||||
Reference in New Issue
Block a user