EIP-712 Hashing and signing of typed structured data (Typed structured data hashing and signing)

Final · Security & privacy · EIP status Final · created 2017-09-12

A standard for securely hashing and signing structured data rather than plain byte strings. It lets wallets show the content being signed in a human-readable form.

Why it is needed

Signing a message off the blockchain and using that signature on-chain is becoming increasingly common because it saves gas and reduces the number of transactions. But there is a problem with what the user sees at the moment of signing. In the existing approach, the message to be signed was displayed only as a meaningless hexadecimal string, leaving the user with no way to confirm what they were actually agreeing to. Also, the task of converting structured data into a hash is itself tricky, and if each app builds its own method and makes a mistake, it breaks the security properties of the system. This standard defines a proven, common method for encoding data together with its structural information, so that the content being signed can be shown to users and the accidents caused by each app inventing its own cryptographic technique can be prevented.

What changes

Today

After EIP-712

Who is affected

In depth

Extending the set of signable messages and encoding

The set of signable messages is extended from transactions and byte strings (𝕋 ∪ 𝔹⁸ⁿ) to structured data 𝕊. Structured data is encoded as "\x19\x01" ‖ domainSeparator ‖ hashStruct(message). The encoding is injective because the first byte always differs across the three cases (an RLP encoded transaction never starts with \x19). This encoding follows ERC-191, with version byte 0x01, version specific data as the 32 byte domainSeparator, and the data to be signed as the 32 byte hashStruct(message). The reason it does not start directly with domainSeparator or typeHash is that, although difficult, it is conceivable that a typeHash could be crafted to become a valid prefix of an RLP encoded transaction.

Type system: atomic, dynamic, and reference types

A struct type has a valid identifier name and zero or more member variables. Atomic types are bytes1 through bytes32, uint8 through uint256, int8 through int256, bool, and address. There are no aliases such as uint or int, and fixed point types are not supported. Dynamic types are bytes and string. Reference types are arrays (fixed size Type[n] or dynamic Type[]) and structs. Recursive struct types are also supported. 𝕊 is the set of all instances of these struct types.

hashStruct, typeHash, and encodeType

hashStruct(s) = keccak256(typeHash ‖ encodeData(s)), and typeHash = keccak256(encodeType(typeOf(s))). Since typeHash is constant for each struct type, it does not need to be computed at runtime and can be kept as a compile time constant in Solidity. encodeType concatenates the name and member list, such as Mail(address from,address to,string contents). If other structs are referenced, the referenced struct types are collected, sorted alphabetically, and appended afterward. Because typeHash is placed up front, encodeData only needs to be injective within the same type. The reason a 256 bit hash is used is that bytes4 lacks sufficient collision resistance, and using a longer hash costs almost nothing at runtime.

encodeData: per value encoding rules

A struct instance is encoded by concatenating its member values in the order given in the type, with each value exactly 32 bytes. Boolean false and true are encoded as the uint256 values 0 and 1, addresses as uint160, and integers as 256 bit sign extended big endian values. bytes1 through bytes31 are right padded with zeros to bytes32. The dynamic types bytes and string are encoded as the keccak256 hash of their contents. Arrays are encoded as the keccak256 hash of the concatenation of the encodeData of their contents, so the encoding of SomeType[5] is the same as a struct with 5 SomeType members. Struct values are encoded recursively as hashStruct(value), and the encoding is undefined for cyclic data. This design is easy to implement using Solidity's abi.encode and allows in place computation in EVM memory. Tight packing and ABIv2 encoding were both rejected: the former requires complex packing instructions, and the latter allows multiple valid encodings for the same data, failing the determinism requirement.

domainSeparator: the domain separation mechanism

domainSeparator = hashStruct(eip712Domain). The EIP712Domain struct selects only the fields relevant to the given domain from: string name (the dapp or protocol name), string version (the major version of the signing domain), uint256 chainId (the EIP-155 chain ID), address verifyingContract (the address of the contract that will verify the signature), and bytes32 salt (a last resort disambiguating salt). If the chain ID differs from the current chain, the user agent should reject the signature, and verifyingContract may be used to prevent phishing. Fields follow the order given above, and missing fields are skipped. The domain separator ensures that signatures do not collide even when different dapps use an identical structure such as Transfer(address from,address to,uint256 amount), and it can also be used within the same dapp to distinguish signatures intended for different purposes over the same struct instance.

The eth_signTypedData RPC and Web3 API

Adds a new eth_signTypedData JSON-RPC method similar to eth_sign. The parameters are the address of the signing account (20 bytes) and the TypedData. TypedData is a JSON object requiring all four fields: types (must include EIP712Domain), primaryType, domain, and message. The return value is a 65 byte hex signature just like eth_sign, where bytes 0 to 32 are r, bytes 32 to 64 are s, and the last byte is v, with v including the EIP-155 chain ID. The signing address must be unlocked. A personal_signTypedData method that also takes the account password as the last argument should be provided, and Web3.js version 1 adds the web3.eth.signTypedData and web3.eth.personal.signTypedData methods.

Security considerations: replay and front-running are the application's responsibility

This standard covers only message signing and verification and does not include replay protection. An application that authorizes an action such as a token exchange via a signed message must behave correctly when it sees the same signed message twice, for example by rejecting repeated messages or making the authorized action idempotent; the implementation method varies by application and is out of scope for the standard. Applications must also be safe against front-running attacks, where an attacker intercepts a signature and submits it to the contract before its intended use. Separately, using keccak256(someInstance) on a struct instance in existing Solidity hashes the instance's memory address, and any dapp relying on that behavior should be considered dangerously broken.

Original EIP · ← EIPs