Merge pull request #8476 from cosmos/aaronc/6513-textual-json-proto

feat: Add SignDocJSON for proto JSON signing

docs/core/proto-docs.md

@@ -606,6 +606,7 @@
     - [ModeInfo.Multi](#cosmos.tx.v1beta1.ModeInfo.Multi)
     - [ModeInfo.Single](#cosmos.tx.v1beta1.ModeInfo.Single)
     - [SignDoc](#cosmos.tx.v1beta1.SignDoc)
+    - [SignDocJSON](#cosmos.tx.v1beta1.SignDocJSON)
     - [SignerInfo](#cosmos.tx.v1beta1.SignerInfo)
     - [Tx](#cosmos.tx.v1beta1.Tx)
     - [TxBody](#cosmos.tx.v1beta1.TxBody)
@@ -8543,10 +8544,11 @@ SignMode represents a signing mode with its own security guarantees.
 
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| SIGN_MODE_UNSPECIFIED | 0 | SIGN_MODE_UNSPECIFIED specifies an unknown signing mode and will be rejected |
-| SIGN_MODE_DIRECT | 1 | SIGN_MODE_DIRECT specifies a signing mode which uses SignDoc and is verified with raw bytes from Tx |
-| SIGN_MODE_TEXTUAL | 2 | SIGN_MODE_TEXTUAL is a future signing mode that will verify some human-readable textual representation on top of the binary representation from SIGN_MODE_DIRECT |
-| SIGN_MODE_LEGACY_AMINO_JSON | 127 | SIGN_MODE_LEGACY_AMINO_JSON is a backwards compatibility mode which uses Amino JSON and will be removed in the future |
+| SIGN_MODE_UNSPECIFIED | 0 | SIGN_MODE_UNSPECIFIED specifies an unknown signing mode and will be rejected. |
+| SIGN_MODE_DIRECT | 1 | SIGN_MODE_DIRECT specifies a signing mode which uses SignDoc and is verified with raw bytes from Tx. |
+| SIGN_MODE_TEXTUAL | 2 | SIGN_MODE_TEXTUAL is a future signing mode that will verify some human-readable textual representation on top of the binary representation from SIGN_MODE_DIRECT. It is currently not supported. |
+| SIGN_MODE_DIRECT_JSON | 3 | SIGN_MODE_DIRECT_JSON specifies a signing mode which uses SignDocJSON. It is verified using a canonical JSON representation of the bytes used in SIGN_MODE_DIRECT. |
+| SIGN_MODE_LEGACY_AMINO_JSON | 127 | SIGN_MODE_LEGACY_AMINO_JSON is a backwards compatibility mode which uses Amino JSON and will be removed in the future. |
 
 
  <!-- end enums -->
@@ -8668,6 +8670,28 @@ SignDoc is the type used for generating sign bytes for SIGN_MODE_DIRECT.
 
 
 
+<a name="cosmos.tx.v1beta1.SignDocJSON"></a>
+
+### SignDocJSON
+SignDocJSON is the type used for generating sign bytes for
+SIGN_MODE_DIRECT_JSON. It is designed to be serialized as proto3 JSON
+following the rules defined here:
+https://github.com/regen-network/canonical-proto3/blob/master/README.md#json.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `body` | [TxBody](#cosmos.tx.v1beta1.TxBody) |  | body is the processable content of the transaction |
+| `auth_info` | [AuthInfo](#cosmos.tx.v1beta1.AuthInfo) |  | auth_info is the authorization related content of the transaction, specifically signers, signer modes and fee |
+| `chain_id` | [string](#string) |  | chain_id is the identifier of the chain this transaction targets. It prevents signed transactions from being used on another chain by an attacker |
+| `account_number` | [uint64](#uint64) |  | account_number is the account number of the signing account in state |
+| `sign_doc_sha256_hash` | [bytes](#bytes) |  | sign_doc_sha256_hash is the SHA-256 hash of SignDoc. It is included here to reduce the malleability attack surface of SIGN_MODE_DIRECT_JSON vs SIGN_MODE_DIRECT to zero. Basically this means that any discrepancy between protobuf bytes over the wire and protobuf bytes that are signed cannot be exploited. This information is obviously redundant with information already in SignDocJSON, but is included as a security check for scenarios where this information may have inadvertently been excluded. We include the hash of SignDoc rather than the full SignDoc bytes to reduce the size of SignDocJSON for scenarios where large payloads could cause problems for hardware wallets. |
+
+
+
+
+
+
 <a name="cosmos.tx.v1beta1.SignerInfo"></a>
 
 ### SignerInfo

proto/cosmos/tx/signing/v1beta1/signing.proto

@@ -9,20 +9,25 @@ option go_package = "github.com/cosmos/cosmos-sdk/types/tx/signing";
 // SignMode represents a signing mode with its own security guarantees.
 enum SignMode {
   // SIGN_MODE_UNSPECIFIED specifies an unknown signing mode and will be
-  // rejected
+  // rejected.
   SIGN_MODE_UNSPECIFIED = 0;
 
   // SIGN_MODE_DIRECT specifies a signing mode which uses SignDoc and is
-  // verified with raw bytes from Tx
+  // verified with raw bytes from Tx.
   SIGN_MODE_DIRECT = 1;
 
   // SIGN_MODE_TEXTUAL is a future signing mode that will verify some
   // human-readable textual representation on top of the binary representation
-  // from SIGN_MODE_DIRECT
+  // from SIGN_MODE_DIRECT. It is currently not supported.
   SIGN_MODE_TEXTUAL = 2;
 
+  // SIGN_MODE_DIRECT_JSON specifies a signing mode which uses SignDocJSON. It
+  // is verified using a canonical JSON representation of the bytes used in
+  // SIGN_MODE_DIRECT.
+  SIGN_MODE_DIRECT_JSON = 3;
+
   // SIGN_MODE_LEGACY_AMINO_JSON is a backwards compatibility mode which uses
-  // Amino JSON and will be removed in the future
+  // Amino JSON and will be removed in the future.
   SIGN_MODE_LEGACY_AMINO_JSON = 127;
 }
 

proto/cosmos/tx/v1beta1/tx.proto

@@ -63,6 +63,39 @@ message SignDoc {
   uint64 account_number = 4;
 }
 
+// SignDocJSON is the type used for generating sign bytes for
+// SIGN_MODE_DIRECT_JSON. It is designed to be serialized as proto3 JSON
+// following the rules defined here:
+// https://github.com/regen-network/canonical-proto3/blob/master/README.md#json.
+message SignDocJSON {
+  // body is the processable content of the transaction
+  TxBody body = 1;
+
+  // auth_info is the authorization related content of the transaction,
+  // specifically signers, signer modes and fee
+  AuthInfo auth_info = 2;
+
+  // chain_id is the identifier of the chain this transaction targets.
+  // It prevents signed transactions from being used on another chain by an
+  // attacker
+  string chain_id = 3;
+
+  // account_number is the account number of the signing account in state
+  uint64 account_number = 4;
+
+  // sign_doc_sha256_hash is the SHA-256 hash of SignDoc. It is included here to
+  // reduce the malleability attack surface of SIGN_MODE_DIRECT_JSON vs
+  // SIGN_MODE_DIRECT to zero. Basically this means that any discrepancy between
+  // protobuf bytes over the wire and protobuf bytes that are signed cannot be
+  // exploited. This information is obviously redundant with information already
+  // in SignDocJSON, but is included as a security check for scenarios where
+  // this information may have inadvertently been excluded. We include the hash
+  // of SignDoc rather than the full SignDoc bytes to reduce the size of
+  // SignDocJSON for scenarios where large payloads could cause problems for
+  // hardware wallets.
+  bytes sign_doc_sha256_hash = 5;
+}
+
 // TxBody is the body of a transaction that all signers sign over.
 message TxBody {
   // messages is a list of messages to be executed. The required signers of