Proposal for off-chain message signing (#26915)
docs: add proposal for off-chain message signing
This commit is contained in:
Trent Nelson
GitHub
parent
f8a94209bd
commit
2decc5275c
|
|
@ -0,0 +1,138 @@
|
||||||
|
# Off-chain message signing
|
||||||
|
## Motivation
|
||||||
|
|
||||||
|
There is ecosystem demand for a method of signing non-transaction messages with
|
||||||
|
a Solana wallet. Typically this is some kind of "proof of wallet ownership" for
|
||||||
|
entry into a whitelisted system.
|
||||||
|
|
||||||
|
Some inspiration can be gleaned from relevant portions of Ethereum's
|
||||||
|
[EIP-712](https://eips.ethereum.org/EIPS/eip-712)
|
||||||
|
|
||||||
|
## Considerations
|
||||||
|
|
||||||
|
* Security
|
||||||
|
* Off-chain message signatures should not be valid transaction message signatures
|
||||||
|
* Future-proofing
|
||||||
|
* Versioning
|
||||||
|
* Co-exist with versioned transaction messages and extended length transactions
|
||||||
|
* Compatibility
|
||||||
|
* Hardware wallet signing
|
||||||
|
* Localization
|
||||||
|
|
||||||
|
## Message Preamble
|
||||||
|
|
||||||
|
| Field | Start offset | Length (bytes) | Description
|
||||||
|
| :---- | :----------: | :------------: | :----------
|
||||||
|
| Signing Domain | 0x00 | 16 | \[[1](#signing-domain-specifier)\]
|
||||||
|
| Header version | 0x10 | 1 | \[[2](#header-version)\]
|
||||||
|
| Application domain | 0x11 | 32 | \[[3](#application-domain)\]
|
||||||
|
| Message format | 0x31 | 1 | \[[4](#message-format)\]
|
||||||
|
| Signer count | 0x32 | 1 | Number of signers committing to the message. An 8-bit, unsigned integer. **MUST NOT** be zero.
|
||||||
|
| Signers | 0x33 | `SIGNER_COUNT` * 32 | `SIGNER_COUNT` ed25519 public keys of signers
|
||||||
|
| Message length | 0x33 + `SIGNER_CNT` * 32 | 2 | Length of message in bytes. A 16-bit, unsigned, little-endian integer. **MUST NOT** be zero.
|
||||||
|
|
||||||
|
### Signing Domain Specifier
|
||||||
|
|
||||||
|
The signing domain specifier is a prefix byte string used to give similar structure
|
||||||
|
to all off-chain message signatures. We assign its value to be:
|
||||||
|
```
|
||||||
|
b"\xffsolana offchain"
|
||||||
|
```
|
||||||
|
The first byte, `\xff`, was chosen for the following reasons
|
||||||
|
1. It corresponds to a value that is illegal as the first byte in a transaction
|
||||||
|
`MessageHeader`.
|
||||||
|
1. It avoids unintentional misuse in languages with C-like, null-terminated strings.
|
||||||
|
|
||||||
|
The remaining bytes, `b"solana offchain"`, were chosen to be descriptive and
|
||||||
|
reasonably long, but are otherwise arbitrary.
|
||||||
|
|
||||||
|
This field **SHOULD NOT** be displayed to users
|
||||||
|
|
||||||
|
### Header
|
||||||
|
|
||||||
|
#### Header version
|
||||||
|
|
||||||
|
The header version is represented as an 8-bit unsigned integer. Only the version
|
||||||
|
0 header format is specfied in this document
|
||||||
|
|
||||||
|
This field **SHOULD NOT** be displayed to users
|
||||||
|
|
||||||
|
#### Application domain
|
||||||
|
|
||||||
|
A 32-byte array identifying the application requesting off-chain message signing.
|
||||||
|
This may be any arbitrary bytes. For instance the on-chain address of a program,
|
||||||
|
DAO instance, Candy Machine, etc.
|
||||||
|
|
||||||
|
This field **SHOULD** be displayed to users as a base58-encoded ASCII string rather
|
||||||
|
than interpretted otherwise.
|
||||||
|
|
||||||
|
#### Message Format
|
||||||
|
|
||||||
|
Version `0` headers specify three message formats allowing for trade-offs between
|
||||||
|
compatibility and composition of messages.
|
||||||
|
|
||||||
|
| ID | Encoding | Maximum Length \* | Hardware Wallet Support |
|
||||||
|
| :-: | :-------------------: | :---------------: | :---------------------: |
|
||||||
|
| 0 | Restricted ASCII \*\* | 1232 | Yes |
|
||||||
|
| 1 | UTF-8 | 1232 | Blind sign only |
|
||||||
|
| 2 | UTF-8 | 65535 | No |
|
||||||
|
|
||||||
|
\* Combined length of the [message preamble](#message-preamble) and message body<br/>
|
||||||
|
\*\* Those characters for which [`isprint(3)`](https://linux.die.net/man/3/isprint)
|
||||||
|
returns true. That is, `0x20..=0x7e`.
|
||||||
|
|
||||||
|
Both the message encoding and maximum message length **MUST** be enforced by
|
||||||
|
signer and verifier.
|
||||||
|
|
||||||
|
Formats `0` and `1` are motivated by hardware wallet support where both RAM
|
||||||
|
to store the payload and font character support are limited.
|
||||||
|
|
||||||
|
This field **SHOULD NOT** be displayed to users
|
||||||
|
|
||||||
|
## Signing
|
||||||
|
|
||||||
|
Solana off-chain messages **MUST** only be signed using the ed25519 digital
|
||||||
|
signature scheme. Before signing, the message **MUST** be strictly checked to
|
||||||
|
conform to the associated preamble. The message body is then appended to the
|
||||||
|
[message preamble](#message-preamble). Finally the result is ed25519 signed.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
Upon successful ed25519 verification of _all_ attached signatures, the message
|
||||||
|
**MUST** be strictly checked to conform to the [message preamble](#message-preamble).
|
||||||
|
A message that does not conform to its preamble is invalid, regardless of the
|
||||||
|
validity of any signatures.
|
||||||
|
|
||||||
|
## Envelope
|
||||||
|
|
||||||
|
When passing around signed off-chain messages a common format is helpful. The
|
||||||
|
recommended binary representation is as follows:
|
||||||
|
|
||||||
|
| Field | Start offset | Length (bytes) | Description
|
||||||
|
| :---- | :----------: | :------------: | :----------
|
||||||
|
| Signature Count \* | 0x00 | 1 | Number of signatures. An 8-bit, unsigned integer
|
||||||
|
| Signatures | 0x01 | `SIG_COUNT` * 64 | `SIG_COUNT` ed25519 signatures
|
||||||
|
| Message Preamble | 0x01 + `SIG_COUNT` * 64 | `PREAMBLE_LEN` | The [message preamble](#message-preamble)
|
||||||
|
| Message Body | 0x01 + `SIG_COUNT * 64 + `PREAMBLE_LEN` | `MESSAGE_LEN` | The message content
|
||||||
|
|
||||||
|
The signature count **MUST** match the value of signers count from the message
|
||||||
|
preamble.
|
||||||
|
|
||||||
|
Signatures **MUST** be ordered to match their corresponding public keys as
|
||||||
|
specified in the message preamble.
|
||||||
|
|
||||||
|
## Runtime Considerations
|
||||||
|
|
||||||
|
To prevent social attacks by which the signer is tricked into signing a transaction,
|
||||||
|
the runtime **MUST NOT** accept signed off-chain messages as transactions under any
|
||||||
|
circumstances. The first byte of the [signing domain specifier](#signing-domain-specifier)
|
||||||
|
is chosen such that it corresponds to a value (`0xff`) which is implicitly illegal
|
||||||
|
as the first byte in a transaction `MessageHeader` today. The property is implicit
|
||||||
|
because the top bit in the first byte of a `MessageHeader` being set signals a
|
||||||
|
versioned transaction, but only a value of
|
||||||
|
[zero is supported](https://github.com/solana-labs/solana/blob/b6ae6c1fe17e4b64c5051c651ca2585e4f55468c/sdk/program/src/message/versions/mod.rs#L269-L281)
|
||||||
|
at this time. The runtime will need to be modified to reserve 127 as an illegal
|
||||||
|
version number, making this property explicit.
|
||||||
|
|
||||||
|
### Implementation
|
||||||
|
|
||||||
|
The runtime changes described above have been implemented in PR [#29807](https://github.com/solana-labs/solana/pull/29807)
|
||||||
Loading…
Reference in New Issue