Tamperproof Web Immutable Secure Transaction (TWIST) introduces a new RPC method to be implemented by wallets, wallet_signedRequest, that
enables dapps to interact with wallets in a tamperproof manner via "signed requests". The
dapp associates a public key with its DNS record and uses the corresponding private key to
sign payloads sent to the wallet via wallet_signedRequest. Wallets can then use the
public key in the DNS record to validate the integrity of the payload.
This standard aims to enhance the end user's experience by granting them confidence that requests from their dapps have not been tampered with. In essence, this is similar to how HTTPS is used in the web.
Currently, the communication channel between dapps and wallets is vulnerable to man in the middle attacks. Specifically, attackers can intercept RPC requests by injecting JavaScript code in the page, via e.g. an XSS vulnerability or due to a malicious extension. Once an RPC request is intercepted, it can be modified in a number of pernicious ways, including:
Even if the user realizes that requests from the dapp may be tampered with, they have little to no recourse to mitigate the problem. Overall, the lack of a chain of trust between the dapp and the wallet hurts the ecosystem as a whole:
For these reasons, we recommend that wallets implement the wallet_signedRequest RPC method.
This method provides dapp developers with a way to explicitly ask the wallet to verify the
integrity of a payload. This is a significant improvement over the status quo, which forces
dapps to rely on implicit approaches such as argument bit packing.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
We propose to use the dapp's domain certificate of a root of trust to establish a trust chain as follow:
example[.]com/.well-known/twist.json{ id, alg, publicKey }wallet_signedRequest RPC methodAttested public keys are necessary for the chain of trust to be established. Since this is traditionally done via DNS certificates, we propose the addition of a DNS record containing the public keys. This is similar to RFC 6376's DKIM, but the use of a manifest file provides more flexibility for future improvements, as well as support for multiple algorithm and key pairs.
Similarly to standard RFC 7519's JWT practices, the wallet could eagerly cache dapp keys. However, in the absence of a revocation mechanism, a compromised key could still be used until caches have expired. To mitigate this, wallets SHOULD NOT cache dapp public keys for more than 2 hours. This practice establishes a relatively short vulnerability window, and manageable overhead for both wallet and dapp maintainers.
Example DNS record for my-crypto-dapp.invalid:
Example TWIST manifest at my-crypto-dapp[.]invalid/.well-known/twist.json:
Implementers MUST support at least the following "alg" param values, from RFC 7518 section 3.1: ES256 and EdDSA. Implementers SHOULD support PS256, RS256, ES384, ES512, PS384, PS512, RS384, and RS512.
Implementers SHOULD use SubtleCrypto, since it is available in modern browsers.
Public keys MUST be encoded using the X.509 SubjectPublicKeyInfo (SPKI) structure in DER format and represented as hex-encoded strings.
We propose a simple and extensible schema:
The parameters of wallet_signedRequest are specified by this TypeScript interface:
Here's a non-normative example of calling wallet_signedRequest using the EIP-1193 provider interface:
sender.tab.url domain
a. The wallet MUST enforce HTTPS as HTTP call would be vulnerable to DNS spoofing
b. The wallet MUST verify that the manifest is hosted on the sender.tab.url domain
c. The wallet SHOULD find the DNS TXT record to find the manifest location
d. The wallet MAY first try the /.well-known/twist.json location
e. The wallet MUST NOT follow redirects when querying the manifest location as it could lead to open redirect attacks
f. The wallet SHOULD validate the Content-Type header of the response is specifically set to application/jsonsender.tab.url domain, then proceed as usualrequest method is used, then the wallet SHOULD display a visible and actionable warning to the user
a. If the user opts to ignore the warning, then proceed as usual
b. If the user opts to cancel, then the wallet MUST cancel the callwallet_signedRequest method is used with the parameters requestPayload, signature and keyId then:
a. The wallet MAY display a visible cue indicating that this interaction is signed
b. The wallet MUST verify that the keyId exists in the TWIST manifest and find the associated key record
c. From the key record, the wallet MUST use the alg field and the publicKey field to verify requestPayload integrity by calling crypto.verify(alg, key, signature, requestPayload)
d. If the signature is invalid, the wallet MUST display a visible and actionable warning to the user
i. If the user opts to ignore the warning, then proceed to call request with the argument requestPayload
ii. If the user opts to cancel, then the wallet MUST cancel the call
e. If the signature is valid, the wallet MUST call request with the argument requestPayloadSimilarly to the padlock icon for HTTPS, wallets should display a visible indication when TWIST is configured on a domain. This will improve the UX of the end user who will immediately be able to tell that interactions between the dapp they are using and the wallet are secure, and this will encourage dapp developer to adopt TWIST, making the overall ecosystem more secure
When dealing with insecure request, either because the dapp (or an attacker) uses request on a domain where TWIST is configured, or because the signature does not match, wallets should warn the user but
not block: an eloquently worded warning will increase the transparency enough that end user may opt to cancel the interaction or proceed with the unsafe call.
The proposed implementation does not modify any of the existing functionalities offered by EIP-712 and EIP-1193. Its additive nature makes it inherently backward compatible. Its core design is modeled after existing solutions to existing problems (such as DKIM). As a result the proposed specification will be non disruptive, easy to implements for both wallets and dapps, with a predictable threat model.
While signing the requestArg payload guarantees data integrity, it does not prevent replay attacks in itself:
Effective time replay attacks as described in 1. are generally prevented by the transaction nonce.
Cross chain replay can be prevented by leveraging the EIP-712 signTypedData method.
Replay attack would still be possible on any method that is not protected by either: this affects effectively all the "readonly" methods which are of very limited value for an attacker.
For these reason, we do not recommend a specific replay protection mechanism at this time. If/when the need arise, the extensibility of the manifest will provide the necessary room to enforce a replay protection envelope (eg:JWT) for affected dapp.
The manifest itself could be attacked, defeating the purpose of TWIST. We identified the following possible attacks, and their counter measure:
'https://${sender.tab.url}/${pathFromDNSRecord}content-type header is equal to application/json to mitigate this attack vectorCopyright and related rights waived via CC0.