From 2f48bbdd6d361e9c2f537b021658e31089e9e648 Mon Sep 17 00:00:00 2001 From: Richard Hua Date: Thu, 30 Nov 2023 10:22:34 +1100 Subject: [PATCH 01/11] Add context on ethereum wallets --- xmtp_mls/IDENTITY.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/xmtp_mls/IDENTITY.md b/xmtp_mls/IDENTITY.md index 918c3da96..4209fa39e 100644 --- a/xmtp_mls/IDENTITY.md +++ b/xmtp_mls/IDENTITY.md @@ -8,13 +8,13 @@ Amal's account (Ethereum wallet address) ├── Converse app (mobile phone) │ └── Installation key bundle 1 │ -├── Coinbase Wallet (mobile phone) +├── Coinbase Wallet app (mobile phone) │ └── Installation key bundle 2 │ -├── Lenster (tablet) +├── Lenster app (tablet) │ └── Installation key bundle 3 │ -└── Coinbase Wallet (tablet) +└── Coinbase Wallet app (tablet) └── Installation key bundle 4 ``` @@ -24,6 +24,14 @@ Using per-installation keys provides the following benefits: - The user may enumerate the installations that have messaging access to their account. - The user may revoke keys on a per-installation level. +**Ethereum wallet** + +Today, an Ethereum wallet consists of a [secp256k1 keypair](https://ethereum.org/en/developers/docs/accounts/#account-creation), and is identified by a a public address, which is the hex-encoding of the last 20 bytes of the Keccak-256 hash of the public key, prepended by `0x`. The user is expected to have a pre-existing Ethereum wallet prior to onboarding with XMTP. + +The owner of a wallet may sign arbitrary text with the wallet. Most wallet software requires explicit [user acceptance](https://docs.metamask.io/wallet/how-to/sign-data/#use-personal_sign) of the signature text. The signature text is formatted according to version `0x45` of [ERC-191](https://eips.ethereum.org/EIPS/eip-191), and is signed via a recoverable ECDSA signature. + +There is currently no way to rotate the keys associated with an Ethereum wallet. In the event that a wallet is compromised, the user must create a new wallet. + **Installation provisioning** Every new app installation gains messaging access as follows: From 93b80560fca81ca03b4bf23b4fb0aa610b05e1e5 Mon Sep 17 00:00:00 2001 From: Richard Hua Date: Thu, 30 Nov 2023 11:09:52 +1100 Subject: [PATCH 02/11] Add installation_public_key to credential, clean up time representation, clean up details --- xmtp_mls/IDENTITY.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/xmtp_mls/IDENTITY.md b/xmtp_mls/IDENTITY.md index 4209fa39e..78bd739bc 100644 --- a/xmtp_mls/IDENTITY.md +++ b/xmtp_mls/IDENTITY.md @@ -28,39 +28,43 @@ Using per-installation keys provides the following benefits: Today, an Ethereum wallet consists of a [secp256k1 keypair](https://ethereum.org/en/developers/docs/accounts/#account-creation), and is identified by a a public address, which is the hex-encoding of the last 20 bytes of the Keccak-256 hash of the public key, prepended by `0x`. The user is expected to have a pre-existing Ethereum wallet prior to onboarding with XMTP. -The owner of a wallet may sign arbitrary text with the wallet. Most wallet software requires explicit [user acceptance](https://docs.metamask.io/wallet/how-to/sign-data/#use-personal_sign) of the signature text. The signature text is formatted according to version `0x45` of [ERC-191](https://eips.ethereum.org/EIPS/eip-191), and is signed via a recoverable ECDSA signature. +The owner of a wallet may sign arbitrary text with the wallet. Most wallet software requires explicit [user acceptance](https://docs.metamask.io/wallet/how-to/sign-data/#use-personal_sign) of the signature text. The signature text is formatted according to version `0x45` of [EIP-191](https://eips.ethereum.org/EIPS/eip-191), and is signed via a recoverable ECDSA signature. There is currently no way to rotate the keys associated with an Ethereum wallet. In the event that a wallet is compromised, the user must create a new wallet. **Installation provisioning** -Every new app installation gains messaging access as follows: +XMTP installations hold a long-lived Ed25519 key-pair (the 'installation key') that is identified via the Ethereum addressing format. The public installation key is used as the `signature_key` in all MLS leaf nodes, and is associated with the account's wallet via a wallet-signed credential. Every new app installation gains messaging access as follows: -1. A new Ed25519 signature key pair is generated and stored on the device, representing the installation's identity. -2. The app prompts the user to sign the public key with their Ethereum wallet, establishing an association between the installation's identity and the user’s account. Example text: +1. The new Ed25519 key pair (installation key) is generated and stored on the device. +2. The app prompts the user to sign the public key with their Ethereum wallet, establishing an association between the installation's identity and the user’s account. The user is expected to inspect the text and reject the signing request if the data is invalid, for example if the `current time` is incorrect. Text format: ``` XMTP: Grant Messaging Access - Current Time: - Installation Key: + Current Time: + Installation ID: ``` -3. The following data is protobuf-serialized to form the MLS Credential. The credential can be presented alongside the installation key to prove an association with an account: +3. The following data is protobuf-serialized to form the MLS Credential: ``` - MlsCredential { - Eip191Association { - association_text_version: i32, - signature: bytes, - wallet_address: string, - creation_time_ns: i64, - } - } + struct { + association_text_version: i32, + signature: bytes, + creation_iso8601_time: string, + wallet_address: string, + } Eip191Association; + + + struct { + installation_public_key: bytes, + eip191_association: Eip191Association + } MlsCredential; ``` -4. A last resort KeyPackage (signed by the installation key per the MLS spec) is generated and stored on the device. -5. The app publishes the public signing key, credential, and last resort key package to the server, which stores it under the account. Other apps may query for this information to understand that the installation is on the network, associated with the account, and how to contact it. +4. A last resort KeyPackage (containing the credential and signed by the installation key per the [MLS spec](https://www.rfc-editor.org/rfc/rfc9420.html#name-key-packages)) is generated and stored on the device. +5. The app publishes the last resort key package to the server. Other apps may query for this information to understand that the installation is on the network, associated with the account, and how to contact it. **Installation management** From df2023f7161c66769f504f0f0b0b07d96081ac0c Mon Sep 17 00:00:00 2001 From: Richard Hua Date: Thu, 30 Nov 2023 11:57:17 +1100 Subject: [PATCH 03/11] Add context around labels --- xmtp_mls/IDENTITY.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/xmtp_mls/IDENTITY.md b/xmtp_mls/IDENTITY.md index 78bd739bc..2a0744e3a 100644 --- a/xmtp_mls/IDENTITY.md +++ b/xmtp_mls/IDENTITY.md @@ -24,20 +24,31 @@ Using per-installation keys provides the following benefits: - The user may enumerate the installations that have messaging access to their account. - The user may revoke keys on a per-installation level. -**Ethereum wallet** +## Ethereum wallet -Today, an Ethereum wallet consists of a [secp256k1 keypair](https://ethereum.org/en/developers/docs/accounts/#account-creation), and is identified by a a public address, which is the hex-encoding of the last 20 bytes of the Keccak-256 hash of the public key, prepended by `0x`. The user is expected to have a pre-existing Ethereum wallet prior to onboarding with XMTP. +Today, an Ethereum wallet consists of a secp256k1 keypair, and is identified by a a public address, which is the hex-encoding of the last 20 bytes of the Keccak-256 hash of the public key, prepended by `0x`. The user is expected to have a pre-existing Ethereum wallet prior to onboarding with XMTP. -The owner of a wallet may sign arbitrary text with the wallet. Most wallet software requires explicit [user acceptance](https://docs.metamask.io/wallet/how-to/sign-data/#use-personal_sign) of the signature text. The signature text is formatted according to version `0x45` of [EIP-191](https://eips.ethereum.org/EIPS/eip-191), and is signed via a recoverable ECDSA signature. +The wallet keys can be used to sign arbitrary text, with most wallet software requiring explicit [user acceptance](https://docs.metamask.io/wallet/how-to/sign-data/#use-personal_sign) of the signature text. The signature text is formatted according to version `0x45` of [EIP-191](https://eips.ethereum.org/EIPS/eip-191), and is signed via a recoverable ECDSA signature. + +Wallet signature requests originating from XMTP will additionally prepend context to the EIP-191 `message` field to prevent collisions between signatures in different contexts: + +``` +XMTP: