Skip to content

Commit

Permalink
KtorZ recommendations
Browse files Browse the repository at this point in the history
  • Loading branch information
@jmagan
jmagan committed Apr 26, 2023
1 parent c3a7c65 commit 60d0e82
Showing 1 changed file with 39 additions and 13 deletions.
52 changes: 39 additions & 13 deletions CIP-????/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,12 @@ License: CC-BY-4.0

## Abstract

The cardano wallets have the ability to sign arbitrary piece of data as we can see in the [Message signing CIP-0008](/CIP-0008/README.md). All wallets implement the method ```api.signData(addr: Address, payload: Bytes): Promise<DataSignature>``` defined in [Cardano dApp-Wallet Web Bridge CIP-0030](/CIP-0030/README.md).

An important use case for web3 sites is calling HTTP endpoints through authenticated requests signed by users' wallet private keys. In this way, the servers can performs actions using onchain and offchain data.

This CIP defines a common structure for all payloads that will be used for calling HTTP endpoints in a authenticated way. This format will provide to the wallet a clear picture of what the users is calling and it will implement security requirements to reduce possible attack vectors.

The proposed Cardano Improvement Proposal (CIP) outlines a conventional structure for data payloads that are signed by wallets, which can be used by decentralized application (dApp) servers to authenticate user requests. By leveraging the Cardano blockchain as an identity provider, dApp servers can securely and trustlessly verify user identities without relying on centralized servers or third-party services. This CIP aims to provide a standard approach for implementing wallet signature authentication in dApps, improving the security and reliability of user interactions with decentralized systems.

## Motivation

The cardano wallets have the ability to sign arbitrary piece of data as we can see in the [Message signing CIP-0008](/CIP-0008/README.md). All wallets implement the method ```api.signData(addr: Address, payload: Bytes): Promise<DataSignature>``` defined in [Cardano dApp-Wallet Web Bridge CIP-0030](/CIP-0030/README.md).

dApps generate arbritary payloads as bytes arrays. These payloads are signed and included in the protected headers of the signatures. The wallets are responsible to show that information to the user, who will proceed to sign or deny the payload. It's a common practice to encode a string or a JSON string but there isn't any standard about the way to show this data.

The current implementations for web3 applications use static strings to be signed. This is dangerous because if a bad actor could intercept the signed message then this message can be sent again and again by the bad actor. That's why is very important to produce a dynamic payload.
Expand All @@ -33,7 +30,36 @@ Another problem with the current approach is how the wallet show the information

## Specification

This specification invovles multiple parties. We split this specification in three parts: server processing, payload structure and wallet specification
This specification invovles multiple parties. We split this specification in three parts: dApp server processing, payload structure and wallet specification

```
+-----------+ +---------------+ +----------------+
| Wallet | | DApp Server | | Blockchain |
+-----------+ +---------------+ +----------------+
| | |
| | |
| 1. Create payload | |
|------------+ | |
| | | |
|<-----------+ | |
| | |
| 2. Request signature | |
|------------+ | |
| | | |
|<-----------+ | |
| | |
| 4. Send signed payload | |
|----------------------------->| |
| | |
| | 5. Verify signature |
| |------------+ |
| | | |
| |<-----------+ |
| | |
| | 6. Check blockchain (optional)|
| |------------------------------>|
| | |
```

### Requirement Levels

Expand All @@ -45,17 +71,17 @@ The payload MUST be encoded as JSON string. JSON strings are semi-estructured da

The content of the payload will be included in the protected header of the COSESign1 signature, hence the content affects directly the behaviour and security of the system. The payload MUST have the following fields:

1. The field ```url``` MUST contain the full path to the endpoint, where the payload will be processed.
1. The field ```uri``` MUST contain the full path to the endpoint, where the payload will be processed.

2. Sometimes, the endpoint ```url``` field is not enough to know its purpose. The user should perfectly know the objective of the payload which is signing. That's why, the payload MUST contain an ```action``` field with a descriptive text of the porpuse of the payload.
2. Sometimes, the endpoint ```uri``` field is not enough to know its purpose. The user should perfectly know the objective of the payload which is signing. That's why, the payload MUST contain an ```action``` field with a descriptive text of the porpuse of the payload.

3. The payload MUST include a UNIX timestamp. The ```timestamp``` field is used as a nonce and a mark for the payload expiration. This field is very imporant in case the payload is compromissed. The payloads must not be static and valid forerver.

Additional fields MAY be included in the payload. Depending on the process, it could be interesting to include some aditional fields in the protected header of the signature. For example, the email information should be included in the protected header in a registration request. In that way, this payload can be used only to register that specific email and it can not be tampering.

```JSON
{
"url": "http://example.com/signup",
"uri": "http://example.com/signup",
"action": "Sign up",
"timestamp": 1673261248,
["email": "[email protected]"] <- Optional
Expand All @@ -67,15 +93,15 @@ Additional fields MAY be included in the payload. Depending on the process, it c

The wallets can improve the overall security implementing the folliwing guidelines. We RECOMMEND to show in a structured way the payload information for shake of clarity. This information should be well understanded by the users before the payload is singed.

The ```url``` field provides information about the hostname of the application. This hostname MUST be included in the wallet allow list. If a known domain A tries to sign a payload for an unknown domain B, you will be prompted with permission popup making more obvious the cross-domain interaction. When it's possible, the wallet SHOULD warn the user if a payload is for a different domain which comes from.
The ```uri``` field provides information about the hostname of the application. This hostname MUST be included in the wallet allow list. If a known domain A tries to sign a payload for an unknown domain B, you will be prompted with permission popup making more obvious the cross-domain interaction. When it's possible, the wallet SHOULD warn the user if a payload is for a different domain which comes from.

The wallet SHOULD update the ```timestamp``` field to the current time just before the signature. This field ideally should match the moment just before the signature, hereby the server recieves the more updated payload possible.

### Server processing

The server has ultimately the responsability of processing correctly the requests. We use the content to verify the validation of the payload. The request will be processed with the following steps:

1. The server MUST check the action and the endpoint included in the request. Each route to an endpoint MUST have associated an action and a url. The first step is to check that they match with the parameterized.
1. The server MUST check the action and the endpoint included in the request. Each route to an endpoint MUST have associated an action and a uri. The first step is to check that they match with the parameterized.

2. The server MUST check the experitation of the payload. The experation SHOULD be enough to give time to the user to introduce the wallet password but it SHOULD NOT be too long, we RECOMMEND not more than 5 minutes.

Expand All @@ -87,7 +113,7 @@ Additionally the server COULD extract the payload content and pass it to the ser

This specification provides the general guidelines and necessary recommendations for performing secure authenticated web3 requests in the cardano ecosystem. It covers the two main desired characteristics for a secure payload: It must expire and it must be non-static.

Another important aspect for security is how wallets process the payload. They can improve the security using the data inside the payload to warn the users about possible maliciuos interactions. This specification emphasizes the importance of informing users clearly about the porpuse of the payloads and how wallets can use the url field to apply allow-lists and/or cross-domain policies.
Another important aspect for security is how wallets process the payload. They can improve the security using the data inside the payload to warn the users about possible maliciuos interactions. This specification emphasizes the importance of informing users clearly about the porpuse of the payloads and how wallets can use the uri field to apply allow-lists and/or cross-domain policies.

Finally, it establishes the requirements and recommendations for the server side processing. The server must also ensure the validity of the signature and the payload, as well as of its purpose in order to accomplish the authentication.

Expand Down

0 comments on commit 60d0e82

Please sign in to comment.