Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@ronny-mysten
ronny-mysten committed Oct 18, 2023
1 parent cb6b8e1 commit c3f330f
Show file tree
Hide file tree
Showing 22 changed files with 3,166 additions and 460 deletions.
81 changes: 1 addition & 80 deletions docs/content/concepts/cryptography/smart-contracts/signing.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,83 +2,4 @@
title: Signing
---

Sui is designed with cryptographic agility in mind. The system supports multiple cryptography algorithms and primitives and can switch between them rapidly. Not only can you choose best-of-breed cryptography for the system, you can implement the latest algorithms as they become available.

Sui defines its cryptography primitives, such as public key, signature, aggregated signature, and hash functions, under one unified type alias or enum wrapper that is shared across the entire repository. Making changes to these primitives affects all of an application's components. Developers can quickly update application cryptography and be assured of uniform security.

## User signature

When you submit a signed transaction, you're submitting a serialized signature and serialized transaction data. The serialized transaction data is the BCS serialized bytes of the struct `TransactionData` and the serialized signature is defined as a concatenation of bytes of `flag || sig || pk`.

The `flag` is a 1-byte representation corresponding to the signature scheme that the signer chooses. The signing scheme and its corresponding flag are defined in the following table:

| Scheme | Flag |
|---|---|
| Pure Ed25519 | 0x00 |
| ECDSA Secp256k1 | 0x01 |
| ECDSA Secp256r1 | 0x02 |
| MultiSig | 0x03 |

The `sig` bytes are the compressed bytes representation of the signature instead of DER encoding. The expected size and format are itemized in the following table:

| Scheme | Signature |
|---|---|
| Pure Ed25519 | Compressed, 64 bytes |
| ECDSA Secp256k1 | Non-recoverable, compressed, 64 bytes |
| ECDSA Secp256r1 | Non-recoverable, compressed, 64 bytes |
| MultiSig | BCS serialized all signatures, size varies |

The `pk` bytes are the bytes representation of the public key corresponding to the signature.

| Scheme | Public key |
|---|---|
| Pure Ed25519 | Compressed, 32 bytes |
| ECDSA Secp256k1 | Compressed, 33 bytes |
| ECDSA Secp256r1 | Compressed, 33 bytes |
| MultiSig | BCS serialized all participating public keys, size varies |

## Signature requirements

The signature must commit to the hash of the intent message of the transaction data, which is constructed by appending the 3-byte intent before the BCS serialized transaction data. To learn more on what is an intent and how to construct an intent message, see [Sui Intent Signing](../transaction-auth/intent-signing.mdx).

When invoking the signing API, you must first hash the intent message of the transaction data to 32 bytes using Blake2b. This external hashing is distinct from the hashing performed inside the signing API. To be compatible with existing standards and hardware secure modules (HSMs), the signing algorithms perform additional hashing internally. For ECDSA Secp256k1 and Secp256r1, you must use SHA-2 SHA256 as the internal hash function. For pure Ed25519, you must use SHA-512.

An accepted ECDSA secp256k1 and secp256r1 signature must follow:

1. The internal hash used by ECDSA must be SHA256 [SHA-2](https://en.wikipedia.org/wiki/SHA-2) hash of the transaction data. Sui uses SHA256 because it is supported by [Apple](https://developer.apple.com/forums/thread/89619), HSMs, and [cloud](https://developer.apple.com/forums/thread/89619), and it is widely adopted by [Bitcoin](https://en.bitcoin.it/wiki/Elliptic_Curve_Digital_Signature_Algorithm).
1. The signature must be of length 64 bytes in the form of `[r, s]` where the first 32 bytes are `r`, the second 32 bytes are `s`.
1. The `r` value can be between `0x1` and `0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364140` (inclusive).
1. The `s` value must be in the lower half of the curve order. If the signature is too high, convert it to a lower `s` according to [BIP-0062](https://github.com/bitcoin/bips/blob/master/bip-0062.mediawiki#low-s-values-in-signatures) with the corresponding curve orders using `order - s`. For secp256k1, the curve order is `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141`. For secp256r1, the curve order is `0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551` defined in [Standards for Efficient Cryptography](https://secg.org/SEC2-Ver-1.0.pdf).
1. Ideally, the signature must be generated with deterministic nonce according to [RFC6979](https://www.rfc-editor.org/rfc/rfc6979).

An accepted pure Ed25519 signature must follow:
1. The signature must be produced according to [RFC 8032](https://www.rfc-editor.org/rfc/rfc8032.html#section-5.1.6). The internal hash used is SHA-512.
1. The signature must be valid according to [ZIP215](https://github.com/zcash/zips/blob/main/zip-0215.rst).

See a concrete example for offline signing using CLI in the [Offline Signing](../transaction-auth/offline-signing.mdx) topic.

## Authority signature

The Authority on Sui (collection of validators) holds three distinctive keypairs:

1. [Protocol key pair](#protocol-pair)
1. [Account key pair](#account-pair)
1. [Network key pair](#network-pair)

### Protocol key pair {#protocol-pair}

The protocol key pair provides authority signatures on user-signed transactions if they are verified. When a stake of the authorities that provide signatures on user transactions passes the required two-thirds threshold, Sui executes the transaction. Sui uses the BLS12381 scheme for its fast verification on aggregated signatures for a given number of authorities. In particular, Sui uses the minSig BLS mode, where each individual public key is 96 bytes, while the signature is 48 bytes. The latter is important as typically validators register their keys once at the beginning of each epoch and then they continuously sign transactions; thus, we optimize on minimum signature size.

As with the BLS scheme, you can aggregate independent signatures resulting in a single BLS signature payload. Sui also accompanies the aggregated signature with a bitmap to denote which of the validators signed. This effectively reduces the authorities' signature size from (2f + 1) × BLS_sig size to just one BLS_sig payload, which in turn has significant network cost benefits resulting in compressed transaction certificates independently on the validators set size.

To counter potential rogue key attacks on BLS12381 aggregated signatures, proof of knowledge of the secret key (KOSK) is used during authority registration. When an authority requests to be added to the validator set, a proof of possession is submitted and verified. See [Intent Signing](../transaction-auth/intent-signing.mdx) on how to create a proof of possession. Unlike most standards, the Sui proof of knowledge scheme commits to the address as well, which offers an extra protection against adversarial reuse of a validator's BLS key from another malicious validator.

### Account key pair {#account-pair}

The account that the authority uses to receive payments on staking rewards is secured by the account key pair. Sui uses pure Ed25519 as the signing scheme.

### Network key pair {#network-pair}

The private key is used to perform the TLS handshake required by QUIC for Narwhal primary and its worker network interface. The public key is used for validator peer ID. Pure Ed25519 is used as the signing scheme.

See more authority key toolings in [Validator Tool](https://github.com/MystenLabs/sui/blob/f8b5ad9aaecc3c4b30a060ec5e00bdad9ba75a93/nre/validator_tool.md).
Placeholder
Binary file added ...ntent/concepts/cryptography/transaction-auth/images/sui_multisig_structures.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 65 additions & 9 deletions docs/content/concepts/cryptography/transaction-auth/keys-addresses.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,76 @@
title: Keys and Adresses
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Scelerisque fermentum dui faucibus in ornare. Ut tristique et egestas quis ipsum suspendisse. Ac placerat vestibulum lectus mauris ultrices eros. Lorem ipsum dolor sit amet. Justo nec ultrices dui sapien eget mi proin sed libero. Nunc lobortis mattis aliquam faucibus. Nec ultrices dui sapien eget mi proin sed. Tellus elementum sagittis vitae et. Tellus at urna condimentum mattis pellentesque id nibh tortor. Sit amet venenatis urna cursus. Imperdiet sed euismod nisi porta lorem mollis aliquam ut. Malesuada fames ac turpis egestas maecenas pharetra convallis posuere.
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs';

## Vel orci
Sui Wallet adheres to widely accepted wallet specifications in the cryptocurrency industry, including BIP-32 (and its variation, SLIP-0010) and its variation SLIP-0010, BIP-44, and BIP-39, to facilitate key management for users. At present, Sui supports pure Ed25519, ECDSA Secp256k1, ECDSA Secp256r1, and MultiSig for signed transactions.

Vel orci porta non pulvinar neque laoreet suspendisse interdum. Gravida rutrum quisque non tellus orci ac. Odio ut sem nulla pharetra diam. Ipsum consequat nisl vel pretium lectus quam id. Vitae justo eget magna fermentum iaculis eu non diam. Est ultricies integer quis auctor elit sed vulputate mi. Vulputate enim nulla aliquet porttitor lacus luctus accumsan. Aliquet risus feugiat in ante metus dictum at tempor. Pulvinar mattis nunc sed blandit libero volutpat sed cras ornare. In fermentum et sollicitudin ac orci phasellus egestas. Morbi tristique senectus et netus et malesuada fames. Eros in cursus turpis massa tincidunt dui ut ornare. Id porta nibh venenatis cras sed felis eget. Sem et tortor consequat id porta nibh. Tempus egestas sed sed risus pretium quam. Vitae tempus quam pellentesque nec nam aliquam. Scelerisque varius morbi enim nunc faucibus a pellentesque. Ut pharetra sit amet aliquam id diam maecenas.
Follow the relevant link for more information on each wallet specification:

## Nunc mi ipsum
- [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
- [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
- [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
- [SLIP-0010](https://github.com/satoshilabs/slips/blob/master/slip-0010)

Nunc mi ipsum faucibus vitae aliquet nec ullamcorper sit. Id venenatis a condimentum vitae. Porta lorem mollis aliquam ut. Ornare suspendisse sed nisi lacus sed. Purus ut faucibus pulvinar elementum integer enim. Egestas integer eget aliquet nibh praesent tristique magna sit. Massa tempor nec feugiat nisl pretium fusce id velit. Integer malesuada nunc vel risus commodo viverra maecenas accumsan. Mi proin sed libero enim. Nunc sed id semper risus in. Pretium vulputate sapien nec sagittis aliquam malesuada. Duis tristique sollicitudin nibh sit amet. Tincidunt praesent semper feugiat nibh sed pulvinar proin gravida hendrerit. Purus gravida quis blandit turpis cursus in hac habitasse. Lacus sed viverra tellus in hac habitasse platea dictumst vestibulum. A scelerisque purus semper eget duis at tellus at. Vitae tempus quam pellentesque nec nam. Id eu nisl nunc mi ipsum faucibus vitae aliquet.
## Key derivation scheme

## Dis parturient montes
Sui follows SLIP-0010 for managing wallets that support the Ed25519 (EdDSA) signing scheme.

Dis parturient montes nascetur ridiculus. Aliquam malesuada bibendum arcu vitae elementum curabitur vitae nunc sed. Adipiscing elit pellentesque habitant morbi. Enim diam vulputate ut pharetra. Feugiat pretium nibh ipsum consequat. Ullamcorper morbi tincidunt ornare massa. Malesuada fames ac turpis egestas integer eget aliquet nibh. Ac turpis egestas integer eget aliquet nibh. Consequat mauris nunc congue nisi. Vitae semper quis lectus nulla at volutpat diam ut. Risus quis varius quam quisque id diam vel. Massa tempor nec feugiat nisl pretium fusce. Fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Mollis aliquam ut porttitor leo a diam sollicitudin tempor id.
For managing wallets that support the Ed25519 (EdDSA) signing scheme, Sui follows SLIP-0010, which enforces wallets to always derive child private keys from parent private keys using the hardened key path.

## Augue mauris
Sui follows BIP-32 for managing wallets that support the ECDSA Secp256k1 and ECDSA Secp256r1 signing scheme.

Augue mauris augue neque gravida in fermentum et sollicitudin ac. Augue eget arcu dictum varius. Maecenas volutpat blandit aliquam etiam erat velit scelerisque. Mi ipsum faucibus vitae aliquet nec. Eros donec ac odio tempor orci. Tellus molestie nunc non blandit massa enim nec dui nunc. Nullam vehicula ipsum a arcu cursus vitae congue mauris. Curabitur gravida arcu ac tortor dignissim convallis aenean et. Varius sit amet mattis vulputate enim nulla aliquet porttitor. Amet purus gravida quis blandit turpis. Non sodales neque sodales ut etiam sit. Fermentum iaculis eu non diam phasellus vestibulum lorem. Cras adipiscing enim eu turpis egestas. Ac feugiat sed lectus vestibulum mattis ullamcorper velit. Elit duis tristique sollicitudin nibh.
BIP-32 defines the hierarchical deterministic wallet structure to logically associate a set of keys. Grouping keys in this manner reduces the overhead of keeping track of a large number of private keys for a user. This method also lets custodians issue distinct managed addresses for each user account under one source of control. Using BIP-32 decouples the private key derivation from the public key derivation, enabling the watch-only wallet use case, where a chain of public keys and its addresses can be derived, while the private key can be kept offline for signing.

## Key derivation path

BIP-44 further defines the five levels of the derivation path with their exact meanings:
`m / purpose' / coin_type' / account' / change / address_index`. In this structure, the slashes indicate new levels, or children, in the hierarchy.

The `purpose` level is generally set to 44, corresponding to the BIP number. In Sui, however, the purpose level distinguishes different signing schemes: 44 is set for Ed25519, 54 for ECDSA Secp256k1 and 74 for Secp256r1. While it is non-standard to set the purpose level to a value that is not 44, it is common to use the purpose field to distinguish different signing schemes. BIP-49 and BIP-84, for example, are used to identify script types in Bitcoin. Sui chose 54 to indicate ECDSA Secp256k1 because there is no existing BIP under 54, avoiding confusion with any Bitcoin standard.

The `coin_type` value is managed with a repository of all other cryptocurrencies. Both signature schemes use Sui's registered coin_type, 784 (SUI on a telephone keypad).

The `account` level is usually used for logically separating user accounts and creating specific account categories.

It is generally accepted that, while account-based currencies define only the first three levels, UTXO-based currencies add change and address level definitions. Because Sui's object-oriented data model is neither UTXO nor account-based (it in fact combines both), it employs all five levels for maximum compatibility.

| Scheme | Path | Comments |
| --------------- | -------------------------------------------- | ---------------------------------------------- |
| Ed25519 | `m/44'/784'/{account}'/{change}'/{address}'` | Each level of the derivation path is hardened. |
| ECDSA Secp256k1 | `m/54'/784'/{account}'/{change}/{address}` | The first three levels are hardened. |
| ECDSA Secp256r1 | `m/74'/784'/{account}'/{change}/{address}` | The first three levels are hardened. |

## Mnemonics support

After Sui defines the deterministic way to derive the master key from a seed, BIP-39 is introduced to make the seed more human-readable and memorizable using mnemonics. Sui accepts 12, 15, 18, 21, and 24 words from the BIP-39 word list that is properly checksummed, corresponding to 128, 160, 192, 224, and 256 bits of entropy. Sui Wallet and SDKs provide a flexible interface to sign transactions with various signing schemes.

## Address format

For deriving a 32-byte Sui address, Sui hashes the signature scheme flag 1-byte concatenated with public key bytes using the [BLAKE2b](https://www.blake2.net/) (256 bits output) hashing function. Sui address currently supports pure Ed25519, Secp256k1, Secp256r1, and MultiSig with corresponding flag bytes of 0x00, 0x01, 0x02, and 0x03, respectively.

## Example

Sui Wallet and SDKs provide a flexible interface to sign transactions with various signing schemes.

<Tabs>
<TabItem value="typescript" label="TypeScript">

```typescript
const keypair = Ed25519Keypair.deriveKeypair(TEST_MNEMONIC, `m/44'/784'/0'/0'/0'`);
const address = keypair.getPublicKey().toSuiAddress();
```

</TabItem>
<TabItem value="cli" label="CLI">

```shell
sui keytool import "TEST_MNEMONIC" ed25519 "m/44'/784'/0'/0'/0'"
sui client new-address ed25519 "m/44'/784'/0'/0'/0'"
```

</TabItem>
</Tabs>

See more test vectors for [pure Ed25519](https://github.com/MystenLabs/sui/blob/f3b5fdd73da64a0df65fb4323471512b0f57ec4d/sdk/typescript/test/unit/cryptography/ed25519-keypair.test.ts) or [ECDSA Secp256k1](https://github.com/MystenLabs/sui/blob/199f06d25ce85f0270a1a5a0396156bb2b83122c/sdk/typescript/test/unit/cryptography/secp256k1-keypair.test.ts).
Loading

0 comments on commit c3f330f

Please sign in to comment.