From 2def0de06f39d672d76b4243b01ed51e4ab0ab33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20Jas=CC=8Cko?= Date: Sun, 4 Feb 2024 18:42:16 +0100 Subject: [PATCH] chore(connect): Add doc and more tests --- .../connect/methods/cardanoSignMessage.md | 100 +++++++++++++++ .../e2e/__fixtures__/cardanoSignMessage.ts | 117 ++++++++++++++++-- packages/connect/src/types/api/index.ts | 1 + 3 files changed, 205 insertions(+), 13 deletions(-) create mode 100644 docs/packages/connect/methods/cardanoSignMessage.md diff --git a/docs/packages/connect/methods/cardanoSignMessage.md b/docs/packages/connect/methods/cardanoSignMessage.md new file mode 100644 index 000000000000..fbc79226ac17 --- /dev/null +++ b/docs/packages/connect/methods/cardanoSignMessage.md @@ -0,0 +1,100 @@ +## Cardano: Sign message + +Asks device to sign given message. User is presented with the first few bytes of the message and the hash of the whole message. User is asked to confirm details on Trezor. + +```javascript +const result = await TrezorConnect.cardanoSignMessage(params); +``` + +### Params + +[Optional common params](commonParams.md) + +[CardanoSignMessage type](https://github.com/trezor/trezor-suite/blob/develop/packages/connect/src/types/api/cardano/index.ts) + +- `signingPath` - _required_ `string | Array` minimum length is `5`. [read more](../path.md) +- `payload` - _required_ `string` message bytes in hex. +- `hashPayload` - _required_ `boolean` if true, device will hash the payload before signing. Must be enabled if payload exceeds 1024 bytes. +- `displayAscii` - _required_ `boolean` if true, device will decode payload as ASCII. +- `networkId` - _optional_ `number` network identifier. Required if `addressParameters` are set. +- `protocolMagic` - _optional_ `number` protocol magic. Required if `addressParameters` are set. +- `addressParameters` - _optional_ `CardanoAddressParameters` object. [read more](./cardanoGetAddress.md#address-parameters) Used to derive address for message header. If not set then the key hash given by `signingPath` will be used instead. +- `derivationType` — _optional_ `CardanoDerivationType` enum. determines used derivation type. Default is set to ICARUS_TREZOR=2 + +### Displaying payload + +If `hashPayload` is `true`, the device will display just the first 56 bytes of the payload. Otherwise 1024 bytes are displayed. + +The payload is decoded as a hex string if `displayAscii` is set to `false`. Otherwise it is decoded as an ASCII string, which succeeds only given the following conditions are met: + +- The payload is a valid ASCII string. +- It must be clear to the user what the contents of the payload are, specifically there is: + - At least one character + - No control characters + - No leading, trailing nor multiple consecutive spaces + +### Example + +Sign hash of "Hello Trezor!": + +```javascript +TrezorConnect.cardanoSignMessage({ + signingPath: "m/1852'/1815'/0'/0/0", + payload: '48656c6c6f205472657a6f7221', // "Hello Trezor!" in hex + hashPayload: true, + displayAscii: true, +}); +``` + +Sign hash of "Hello Trezor!" using address parameters for header: + +```javascript +TrezorConnect.cardanoSignMessage({ + signingPath: "m/1852'/1815'/0'/0/0", + payload: '48656c6c6f205472657a6f7221', // "Hello Trezor!" in hex + hashPayload: true, + displayAscii: true, + networkId: 1, + protocolMagic: 764824073, + addressParameters: { + addressType: 0, + path: "m/1852'/1815'/0'/0/0", + stakingPath: "m/1852'/1815'/0'/2/0", + }, +}); +``` + +### Result + +[CardanoSignedMessage type](https://github.com/trezor/trezor-suite/blob/develop/packages/connect/src/types/api/cardano/index.ts) + +```javascript +{ + success: true, + payload: { + signature: string, + payload: string, + headers: { + protected: { + 1: -8, // EdDSA algorithm + address: string, + }, + unprotected: { + hashed: boolean, + version: number, + } + } + } +} +``` + +Error + +```javascript +{ + success: false, + payload: { + error: string // error message + } +} +``` diff --git a/packages/connect/e2e/__fixtures__/cardanoSignMessage.ts b/packages/connect/e2e/__fixtures__/cardanoSignMessage.ts index e870f3ee2bed..46907705e14c 100644 --- a/packages/connect/e2e/__fixtures__/cardanoSignMessage.ts +++ b/packages/connect/e2e/__fixtures__/cardanoSignMessage.ts @@ -7,6 +7,27 @@ const legacyResults = { }, }; +const headerUnhashed = (address: string) => ({ + protected: { + 1: ALGORITHM_IDS.EdDSA, + address, + }, + unprotected: { + hashed: false, + version: 1, + }, +}); + +const headerHashed = (address: string) => { + const header = headerUnhashed(address); + header.unprotected.hashed = true; + return header; +}; + +/** "HelloTrezor!" repeated 86 times (=1032 bytes) in hex */ +const HELLO_TREZOR_86 = + '48656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f7221'; + export default { method: 'cardanoSignMessage', setup: { @@ -14,28 +35,98 @@ export default { }, tests: [ { - description: 'Sign short ASCII payload hash', + description: 'Sign short ASCII payload', params: { signingPath: "m/1852'/1815'/0'/0/0", - payload: '54657374', - hashPayload: true, + payload: '54657374', // "Test" hex + hashPayload: false, displayAscii: true, }, result: { payload: '54657374', signature: - 'cde9451e081f325ed9991b5c20f22c7220526f97e646abee71b8fe232e475b8b06a98df28fdec911e81a050d47c0fcbe3b629d38fc12730fb74ab0a5f56f7f05', - headers: { - protected: { - 1: ALGORITHM_IDS.EdDSA, - address: '80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa', - }, - unprotected: { - hashed: true, - version: 1, - }, + '1c2c7612840654a56d61b58df36f41a4b47ad4034140ea369269c143f2732b2702c42fa753a8c52a9b662ba02944e43ec95c59cb892bf01cdd4a7f1c9397490c', + headers: headerUnhashed('80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa'), + }, + legacyResults: [legacyResults.beforeMessageSigning], + }, + { + description: 'Sign short ASCII payload with address parameters', + params: { + signingPath: "m/1852'/1815'/0'/0/0", + payload: '54657374', // "Test" hex + hashPayload: false, + displayAscii: true, + networkId: 1, + protocolMagic: 764824073, + addressParameters: { + addressType: 0, + path: "m/1852'/1815'/0'/0/0", + stakingPath: "m/1852'/1815'/0'/2/0", // websocket_error_message: BridgeException - trezord: debug/release/debug4 failed with code 400: session not found }, }, + result: { + payload: '54657374', + signature: + '31ddc8531e70f9be45af9812ab466749e2ed63d5be626956f3341867f518c29ad669380766a9e5ceefe9f099211809831892cbd3161ca4c935e1b574f59fb406', + headers: headerUnhashed( + '0180f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa122a946b9ad3d2ddf029d3a828f0468aece76895f15c9efbd69b4277', + ), + }, + legacyResults: [legacyResults.beforeMessageSigning], + }, + { + description: 'Sign short non-ASCII payload', + params: { + signingPath: "m/1852'/1815'/0'/0/0", + payload: 'ff', + hashPayload: false, + displayAscii: false, + }, + result: { + payload: 'ff', + signature: + '003a3631d6c7509c2ebfbeb955c7f6a6b214c4283c2cbc10fc7eda6f2237881c7b219e4b28f3004d50cf528ad325b2d4f10425003096f80db58fc160365d920d', + headers: headerUnhashed('80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa'), + }, + legacyResults: [legacyResults.beforeMessageSigning], + }, + { + description: 'Sign long ASCII payload hash', + params: { + signingPath: "m/1852'/1815'/0'/0/0", + payload: HELLO_TREZOR_86, + hashPayload: true, + displayAscii: true, + }, + result: { + payload: HELLO_TREZOR_86, + signature: + '39dba8107fb840b0aeff3f45eaddf9612cd4fd640a18cbe28ea2448b8ba2fea99b67cd9662a46cc7a70e1ad0d6399008d5fad9d67ddb437a623b594bf93b8e0f', + headers: headerHashed('80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa'), + }, + legacyResults: [legacyResults.beforeMessageSigning], + }, + { + description: 'Sign long ASCII payload without hashing', + params: { + signingPath: "m/1852'/1815'/0'/0/0", + payload: HELLO_TREZOR_86, + hashPayload: false, + displayAscii: true, + }, + result: false, + legacyResults: [legacyResults.beforeMessageSigning], + }, + { + description: 'Display ambigous-looking " " ASCII payload', + params: { + signingPath: "m/1852'/1815'/0'/0/0", + payload: '20', // " " (single space) hex + hashPayload: false, + displayAscii: true, + }, + result: false, legacyResults: [legacyResults.beforeMessageSigning], }, ], diff --git a/packages/connect/src/types/api/index.ts b/packages/connect/src/types/api/index.ts index 26421bba997a..4ea5cba89c22 100644 --- a/packages/connect/src/types/api/index.ts +++ b/packages/connect/src/types/api/index.ts @@ -167,6 +167,7 @@ export interface TrezorConnect { cardanoComposeTransaction: typeof cardanoComposeTransaction; + // https://github.com/trezor/trezor-suite/blob/develop/docs/packages/connect/methods/cardanoSignMessage.md cardanoSignMessage: typeof cardanoSignMessage; // https://github.com/trezor/trezor-suite/blob/develop/docs/packages/connect/methods/changePin.md