Skip to content

Commit

Permalink
Wordsmithing
Browse files Browse the repository at this point in the history
  • Loading branch information
@MarcoPolo
MarcoPolo committed Aug 27, 2024
1 parent a1091a4 commit d5ec85a
Showing 1 changed file with 31 additions and 24 deletions.
55 changes: 31 additions & 24 deletions http/peer-id-auth.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ scheme is called `libp2p-PeerID`.

## Parameters

| Param Name | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hostname | The server name used in the TLS connection (SNI). |
| 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]. |
| opaque | An base64 encoded 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. |
| Param Name | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| hostname | The server name used in the TLS connection (SNI). |
| 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]. |
| 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"`

Expand Down Expand Up @@ -74,10 +74,10 @@ protocol operates as follows:
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>"[,encoded-public-key="<base64-encoded-public-key-bytes>" ], sig="<base64-signature-bytes>"
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>"
```

The `encoded-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 `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`
Expand All @@ -87,34 +87,41 @@ protocol operates as follows:
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:
```
Authentication-Info: libp2p-PeerID peer-id="<server-peer-id-string>", sig="<base64-signature-bytes>", libp2p-Bearer <base64-encoded-opaque-blob>
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>"
```

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-pubkey` the bytes of the client's public key
- `client-peer-id` the string representation fo the client's peer id

The `libp2p-Bearer` token allows the client to make future Peer ID authenticated
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
store authentication state such as:
- The client's Peer ID.
- 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`
authenticated the server's Peer ID. The client SHOULD send the `bearer`
token for Peer ID authenticated requests.

## libp2p Bearer token
## libp2p bearer token

The libp2p Bearer token is a token given to the client from the server that
The libp2p bearer token is a token given to the client from the server that
allows the client (the bearer) to make Peer ID authenticated requests to the
server. Once the client receives this token after the Mutual Authentication
protocol, the client should save it and use it for future authenticated
requests.
server. Once the client receives this token, they SHOULD save it and use it
for future authenticated requests.

The server SHOULD return a 401 Unauthorized and follow the above Mutual
authentication protocol when it wants the client to request a new libp2p Bearer
token.
authentication protocol when it wants the client to request a new libp2p
bearer token.

To use the bearer token, the client MUST set the Authorization header as follows:
```
Authorization: libp2p-PeerID bearer="<base64-encoded-opaque-blob>"
```

## Authentication URI Endpoint

Expand Down Expand Up @@ -167,7 +174,7 @@ Included is a concrete example of running the protocol. The client uses the Peer
```
4. The server responds with the header:
```
Authentication-Info: libp2p-PeerID peer-id="12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN", sig="btLFqW200aDTQqpkKetJJje7V-iDknXygFqPsfiegNsboXeYDiQ6Rqcpezz1wfr8j9h83QkN9z78cAWzKzV_AQ==", libp2p-Bearer <base64-encoded-bearer-token>
Authentication-Info: libp2p-PeerID peer-id="12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN", sig="btLFqW200aDTQqpkKetJJje7V-iDknXygFqPsfiegNsboXeYDiQ6Rqcpezz1wfr8j9h83QkN9z78cAWzKzV_AQ==", bearer="<base64-encoded-bearer-token>"
```


Expand All @@ -186,7 +193,7 @@ The following table lists out all parameters and intermediate values used in the
| 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==", libp2p-Bearer <some-opaque-value>` |
| The server's Authentication-Info header | `Authentication-Info: libp2p-PeerID peer-id="12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN", sig="btLFqW200aDTQqpkKetJJje7V-iDknXygFqPsfiegNsboXeYDiQ6Rqcpezz1wfr8j9h83QkN9z78cAWzKzV_AQ==", bearer="<some-opaque-value>"` |


[Peer ID spec]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md
Expand Down

0 comments on commit d5ec85a

Please sign in to comment.