From 45971c06e67618963d0ccdcef547f0e91f23fb00 Mon Sep 17 00:00:00 2001 From: gabrielkerekes Date: Mon, 14 Jun 2021 14:05:04 +0200 Subject: [PATCH 1/5] CIP-0021: Restrictions on transactions signed by hardware wallets --- CIP-0021/CIP-0021.md | 115 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 CIP-0021/CIP-0021.md diff --git a/CIP-0021/CIP-0021.md b/CIP-0021/CIP-0021.md new file mode 100644 index 0000000000..67ab85a515 --- /dev/null +++ b/CIP-0021/CIP-0021.md @@ -0,0 +1,115 @@ +--- +CIP: 0021 +Title: Restrictions on transactions signed by hardware wallets +Authors: Gabriel Kerekes , Rafael Korbas , Jan Mazak +Status: Draft +Type: Standards +Created: 2021-06-15 +License: CC-BY-4.0 +--- + +## Abstract + +This CIP describes all the restrictions applicable to Cardano transactions which need to be signed by hardware wallets. + +## Motivation + +Due to certain limitations of HW wallets, especially very small memory and a limited set of data types supported by Ledger, HW wallets are not able to process all valid transactions which are supported by Cardano nodes. + +The limitations also result in an inability of HW wallets to see the whole transaction at once. Transaction data are streamed into HW wallets in small chunks and they compute a rolling hash of the transaction body which is signed at the end. Consequently, a HW wallet only provides witness signatures, and the transaction body which was signed has to be reconstructed by the client. We thus need a common transaction serialization format which will allow no ambiguity. In addition, the format must define ordering of map keys in such a way that it’s possible to check for duplicate keys by HW wallets. + +Several of the restrictions also stem from security or UX concerns, e.g. the forbidden combination of pool registration certificates and withdrawals in a single transaction (see reasoning below). + +To ensure interoperability, SW wallets and other tools working with HW wallets should only use transactions which conform to the following rules. + +## Specification + +### Canonical CBOR serialization format + +Transactions must be serialized in line with suggestions from [Section 3.9 of CBOR specification RFC](https://datatracker.ietf.org/doc/html/rfc7049#section-3.9). In particular: + +- Integers must be as small as possible. +- The expression of lengths in major types 2 through 5 must be as short as possible. +- The keys in every map must be sorted from lowest value to highest. +- Indefinite-length items must be made into definite-length items. + +See the RFC for details. + +### Transaction body + +Full support for some elements is not implemented yet (especially those related to scripts), but that is likely to change in the near future. The following restrictions are, however, unlikely to ever be lifted. + +**Unsupported entries** + +The transaction body entry `6 : update` must not be included. + +**Integers** + +While the Cardano CDDL specification usually does not limit the size of integers, HW wallets only support `int64` for signed integers and `uint64` for unsigned integers. Any integer value must fit in the appropriate type. + +**Numbers of transaction elements** + +The numbers of inputs, outputs, certificates, withdrawals, tokens in an asset group, and other similar transaction elements must not exceed `UINT16_MAX`, i.e. 65535. + +**Multiassets** + +Since multiassets (`policy_id` and `asset_name`) are represented as maps, both need to be sorted in accordance with the specified canonical CBOR format. Also, an output or the mint field must not contain duplicate `policy_id`s and a policy must not contain duplicate `asset_name`s. + +**Certificates** + +Certificates of type `genesis_key_delegation` and `move_instantaneous_rewards_cert` are not supported and must not be included. + +If a transaction contains a pool registration certificate, then it must not contain: + +- any other certificate; +- any withdrawal; +- mint entry. + +It is allowed to arbitrarily combine other supported certificate types, but all the certificates included in a transaction must have the same type of stake credential i.e. either 0 - `addr_keyhash` or 1 - `scripthash`. The stake credential type must also be consistent with the type used for withdrawals. + +**Withdrawals** + +Since withdrawals are represented as a map of reward accounts, withdrawals also need to be sorted in accordance with the specified canonical CBOR format. A transaction must not contain duplicate withdrawals. All withdrawals included in a transaction must have the same type of stake credential i.e. either 0 - `addr_keyhash` or 1 - `scripthash`. The stake credential type must also be consistent with the type used for certificates. + +### Transaction witnesses + +There are two limits on the number of witnesses: + +- an absolute limit of `UINT16_MAX`, i.e. 65535; +- a relative limit dependent on the transaction body (essentially one witness per each input, each withdrawal and each certificate in a typical transaction). + +## Reasoning + +### Canonical CBOR serialization format + +As HW wallets don't return the whole serialized transaction, a common CBOR serialization is needed so that software wallets and other tools interacting with HW wallets are be able to deterministically reproduce the transaction body built and signed by the HW wallet. + +The specified canonical CBOR format is consistent with how certain other data are serialized (e.g. Plutus script data in Alonzo) and allows the use of standard CBOR libraries out of the box. + +### Transaction body + +**Multiassets** + +Allowing duplicate `policy_id`s (or `asset_name`s) might lead to inconsistencies between what is displayed to the user and how nodes and other tools might interpret the duplicate keys, i.e. all policies (or asset names) would be shown to the user, but nodes and other tools might eventually interpret only a single one of them. + +**Certificates** + +Combining withdrawals and pool registration certificates isn't allowed because both are signed by staking keys by pool owners. If it was allowed to have both in a transaction then the witness provided by a pool owner might inadvertently serve as a witness for a withdrawal for the owner's account. + +**Withdrawals** + +Similarly to multiassets, allowing duplicate withdrawals might lead to inconsistencies between what is displayed to the user and how nodes and other tools might interpret the duplicate keys. + +### Transaction witnesses + +The relative limit is imposed to avoid leaking signatures the user is not aware of - for ordinary transactions, witnesses are not shown. It does not apply to script witnesses which are always shown on the screen. + +However, since a HW wallet only deals with the transaction body and not the whole transaction, it is possible to make several calls to a HW wallet and collect more witnesses than these limits allow (the user has to click through the transaction more than once in such a case). + +## Backwards compatibility + +Most of the restrictions are already implemented in HW wallets except the canonical CBOR serialization. Tools interacting with HW wallets might need to be updated in order to continue being compatible with HW wallets when the canonical CBOR serialization format is enforced in HW wallets. + +## Copyright + +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode) From 81d23947c95008dd4b9e0dd6d7c46e56ba18f722 Mon Sep 17 00:00:00 2001 From: gabrielkerekes Date: Mon, 16 Aug 2021 13:50:21 +0200 Subject: [PATCH 2/5] fixup! CIP-0021: Restrictions on transactions signed by hardware wallets --- CIP-0021/CIP-0021.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/CIP-0021/CIP-0021.md b/CIP-0021/CIP-0021.md index 67ab85a515..bdd83d1438 100644 --- a/CIP-0021/CIP-0021.md +++ b/CIP-0021/CIP-0021.md @@ -51,6 +51,14 @@ While the Cardano CDDL specification usually does not limit the size of integers The numbers of inputs, outputs, certificates, withdrawals, tokens in an asset group, and other similar transaction elements must not exceed `UINT16_MAX`, i.e. 65535. +**Optional empty lists and maps** + +Unless mentioned otherwise in this CIP, optional empty lists and maps must not be included as part of the transaction body or its elements. + +**Outputs** + +Outputs containing no multi-asset tokens must be serialized as a simple tuple, i.e. `[address, coin]` instead of `[address, [coin, {}]]`. + **Multiassets** Since multiassets (`policy_id` and `asset_name`) are represented as maps, both need to be sorted in accordance with the specified canonical CBOR format. Also, an output or the mint field must not contain duplicate `policy_id`s and a policy must not contain duplicate `asset_name`s. @@ -71,6 +79,18 @@ It is allowed to arbitrarily combine other supported certificate types, but all Since withdrawals are represented as a map of reward accounts, withdrawals also need to be sorted in accordance with the specified canonical CBOR format. A transaction must not contain duplicate withdrawals. All withdrawals included in a transaction must have the same type of stake credential i.e. either 0 - `addr_keyhash` or 1 - `scripthash`. The stake credential type must also be consistent with the type used for certificates. +**Auxiliary data** + +HW wallets do not serialize auxiliary data because of their complex structure. They only include the given auxiliary data hash in the transaction body. The only exception is Catalyst voting registration because it requires a signature computed by the HW wallet. + +In this exceptional case, auxiliary data must be encoded in their "tuple" format: + +``` +[ transaction_metadata: { * transaction_metadatum_label => transaction_metadatum }, auxiliary_scripts: [ * native_script ]] +``` + +The `auxiliary_scripts` must be an array of length 0. + ### Transaction witnesses There are two limits on the number of witnesses: @@ -100,6 +120,10 @@ Combining withdrawals and pool registration certificates isn't allowed because b Similarly to multiassets, allowing duplicate withdrawals might lead to inconsistencies between what is displayed to the user and how nodes and other tools might interpret the duplicate keys. +**Auxiliary data** + +The specified auxiliary data format was chosen in order to be compatible with other Cardano tools, which mostly use this serialization format. + ### Transaction witnesses The relative limit is imposed to avoid leaking signatures the user is not aware of - for ordinary transactions, witnesses are not shown. It does not apply to script witnesses which are always shown on the screen. From 0d287f800481a3ca4cec23caf1a09b0b8f3ef0a4 Mon Sep 17 00:00:00 2001 From: gabrielkerekes Date: Fri, 20 Aug 2021 09:44:49 +0200 Subject: [PATCH 3/5] fixup! CIP-0021: Restrictions on transactions signed by hardware wallets --- CIP-0021/CIP-0021.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/CIP-0021/CIP-0021.md b/CIP-0021/CIP-0021.md index bdd83d1438..644ffc9e74 100644 --- a/CIP-0021/CIP-0021.md +++ b/CIP-0021/CIP-0021.md @@ -14,7 +14,7 @@ This CIP describes all the restrictions applicable to Cardano transactions which ## Motivation -Due to certain limitations of HW wallets, especially very small memory and a limited set of data types supported by Ledger, HW wallets are not able to process all valid transactions which are supported by Cardano nodes. +Due to certain limitations of hardware (abbrev. HW) wallets, especially very small memory and a limited set of data types supported by Ledger, HW wallets are not able to process all valid transactions which are supported by Cardano nodes. The limitations also result in an inability of HW wallets to see the whole transaction at once. Transaction data are streamed into HW wallets in small chunks and they compute a rolling hash of the transaction body which is signed at the end. Consequently, a HW wallet only provides witness signatures, and the transaction body which was signed has to be reconstructed by the client. We thus need a common transaction serialization format which will allow no ambiguity. In addition, the format must define ordering of map keys in such a way that it’s possible to check for duplicate keys by HW wallets. @@ -49,7 +49,17 @@ While the Cardano CDDL specification usually does not limit the size of integers **Numbers of transaction elements** -The numbers of inputs, outputs, certificates, withdrawals, tokens in an asset group, and other similar transaction elements must not exceed `UINT16_MAX`, i.e. 65535. +The number of the following transaction elements individually must not exceed `UINT16_MAX`, i.e. 65535: + +- inputs in transaction body +- outputs in transaction body +- asset groups (policy IDs) in an output +- tokens (asset names) in an asset group +- certificates in transaction body +- pool owners in a pool registration certificate +- pool relays in a pool registration certificate +- withdrawals in transaction body +- the total number of witnesses **Optional empty lists and maps** From 74bb782218e68f713cba7735c4de5a522ee8216a Mon Sep 17 00:00:00 2001 From: gabrielkerekes Date: Wed, 25 Aug 2021 17:27:52 +0200 Subject: [PATCH 4/5] fixup! CIP-0021: Restrictions on transactions signed by hardware wallets --- CIP-0021/CIP-0021.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/CIP-0021/CIP-0021.md b/CIP-0021/CIP-0021.md index 644ffc9e74..1e0803f25c 100644 --- a/CIP-0021/CIP-0021.md +++ b/CIP-0021/CIP-0021.md @@ -1,6 +1,6 @@ --- CIP: 0021 -Title: Restrictions on transactions signed by hardware wallets +Title: Transaction requirements for interoperability with hardware wallets Authors: Gabriel Kerekes , Rafael Korbas , Jan Mazak Status: Draft Type: Standards @@ -101,13 +101,6 @@ In this exceptional case, auxiliary data must be encoded in their "tuple" format The `auxiliary_scripts` must be an array of length 0. -### Transaction witnesses - -There are two limits on the number of witnesses: - -- an absolute limit of `UINT16_MAX`, i.e. 65535; -- a relative limit dependent on the transaction body (essentially one witness per each input, each withdrawal and each certificate in a typical transaction). - ## Reasoning ### Canonical CBOR serialization format @@ -134,12 +127,6 @@ Similarly to multiassets, allowing duplicate withdrawals might lead to inconsist The specified auxiliary data format was chosen in order to be compatible with other Cardano tools, which mostly use this serialization format. -### Transaction witnesses - -The relative limit is imposed to avoid leaking signatures the user is not aware of - for ordinary transactions, witnesses are not shown. It does not apply to script witnesses which are always shown on the screen. - -However, since a HW wallet only deals with the transaction body and not the whole transaction, it is possible to make several calls to a HW wallet and collect more witnesses than these limits allow (the user has to click through the transaction more than once in such a case). - ## Backwards compatibility Most of the restrictions are already implemented in HW wallets except the canonical CBOR serialization. Tools interacting with HW wallets might need to be updated in order to continue being compatible with HW wallets when the canonical CBOR serialization format is enforced in HW wallets. From f3d1b042404afac9cb2e444aac53b741a0429812 Mon Sep 17 00:00:00 2001 From: gabrielkerekes Date: Tue, 14 Sep 2021 08:57:02 +0200 Subject: [PATCH 5/5] fixup! CIP-0021: Restrictions on transactions signed by hardware wallets --- CIP-0021/CIP-0021.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0021/CIP-0021.md b/CIP-0021/CIP-0021.md index 1e0803f25c..b41efc4030 100644 --- a/CIP-0021/CIP-0021.md +++ b/CIP-0021/CIP-0021.md @@ -45,7 +45,7 @@ The transaction body entry `6 : update` must not be included. **Integers** -While the Cardano CDDL specification usually does not limit the size of integers, HW wallets only support `int64` for signed integers and `uint64` for unsigned integers. Any integer value must fit in the appropriate type. +HW wallets support at most `int64` for signed integers and `uint64` for unsigned integers i.e. larger integers are not supported overall. Additionally, any integer value must fit in the appropriate type. **Numbers of transaction elements**