projects/doc: add new for eth_wallet and format

DemesneGH · Nov 27, 2024 · 3bca04b · 3bca04b
1 parent 4c86df3
commit 3bca04b
Show file tree

Hide file tree

Showing 3 changed files with 273 additions and 86 deletions.
diff --git a/projects/README.md b/projects/README.md
@@ -1,47 +1,44 @@
-# Projects in Multiple Scenarios  
-
-Trusted Execution Environments (TEEs) play a vital role in providing critical  
-security solutions across various scenarios. The Teaclave TrustZone SDK  
-empowers developers to implement robust use cases such as Web3 private key  
-protection, authentication, and more.  
-
-The `projects/` directory showcases real-world scenarios and essential  
-primitives designed to help developers build secure applications tailored to  
-their needs.  
-
-Currently, we have released a Web3-focused scenario, with plans to expand the  
-project and introduce more use cases in the future.  
-
-## Available Scenarios  
-
-- **Web3**:  
-  Available in `projects/web3/`, this scenario offers utilities for Web3  
-  development, such as key custodians and decentralized identifiers (DIDs). It  
-  currently includes a basic Ethereum wallet that demonstrates how to securely 
-  create a wallet and sign transactions using wallet-derived keys within the 
-  TEE.  
-
-## Upcoming Scenarios  
-
-- **X509 Certificate Signing & Verification**:  
-  This scenario provides foundational Public Key Infrastructure (PKI)  
-  primitives for securely issuing self-signed certificates and verifying  
-  externally provided leaf certificates using a trusted certificate store.  
-  The Trusted Application (TA) inside the TEE handles secure key pair  
-  generation and certificate issuance, facilitating identity verification for  
-  secure communications. This primitive is particularly valuable for  
-  establishing trusted communication channels between nodes or devices.  
-
-- **Remote Attestation**:  
-  This foundational primitive enables remote attestation of a Trusted  
-  Application (TA) to ensure it is running within a Trusted Execution  
-  Environment (TEE). It utilizes TLS and X509 PKI to establish a secure  
-  communication channel.  
-
-- **Multi-Factor Authentication (MFA)**:  
-  This example demonstrates how to implement MFA by securely provisioning the  
-  public keys of trusted MFA devices (e.g., a user’s cellphone) within the  
-  Trusted Application (TA). When high-risk operations like key usage or  
-  transaction signing require user confirmation, the TA securely verifies  
-  user-provided details via the trusted MFA device, eliminating reliance on  
-  third-party services.  
+# Projects in Multiple Scenarios
+
+Trusted Execution Environments (TEEs) play a vital role in providing critical
+security solutions across various scenarios. The Teaclave TrustZone SDK empowers
+developers to implement robust use cases such as Web3 private key protection,
+authentication, and more.
+
+The `projects/` directory showcases real-world scenarios and essential
+primitives designed to help developers build secure applications tailored to
+their needs.
+
+Currently, we have released a Web3-focused scenario, with plans to expand the
+project and introduce more use cases in the future.
+
+## Available Scenarios
+
+- **Web3**: Available in `projects/web3/`, this scenario offers utilities for
+  Web3 development, such as key custodians and decentralized identifiers (DIDs).
+  It currently includes a basic Ethereum wallet that demonstrates how to
+  securely create a wallet and sign transactions using wallet-derived keys
+  within the TEE.
+
+## Upcoming Scenarios
+
+- **X509 Certificate Signing & Verification**: This scenario provides
+  foundational Public Key Infrastructure (PKI) primitives for securely issuing
+  self-signed certificates and verifying externally provided leaf certificates
+  using a trusted certificate store. The Trusted Application (TA) inside the TEE
+  handles secure key pair generation and certificate issuance, facilitating
+  identity verification for secure communications. This primitive is
+  particularly valuable for establishing trusted communication channels between
+  nodes or devices.
+
+- **Remote Attestation**: This foundational primitive enables remote attestation
+  of a Trusted Application (TA) to ensure it is running within a Trusted
+  Execution Environment (TEE). It utilizes TLS and X509 PKI to establish a
+  secure communication channel.
+
+- **Multi-Factor Authentication (MFA)**: This example demonstrates how to
+  implement MFA by securely provisioning the public keys of trusted MFA devices
+  (e.g., a user’s cellphone) within the Trusted Application (TA). When high-risk
+  operations like key usage or transaction signing require user confirmation,
+  the TA securely verifies user-provided details via the trusted MFA device,
+  eliminating reliance on third-party services.
diff --git a/projects/web3/README.md b/projects/web3/README.md
@@ -1,39 +1,41 @@
-# Reference Implementation Examples for Web3 Trusted Applications  
-
-Teaclave TrustZone SDK allows developers to create Trusted Applications  
-(TAs) in Rust, offering a memory-safe and secure environment. Many examples  
-in this repository are ported from OP-TEE C examples. With Rust's ecosystem  
-and support for Rust-std in Teaclave TrustZone SDK, developers can build  
-secure TAs to protect confidential information.  
-
-In Web3, private key protection is vital for securing on-chain identities and  
-assets. TAs safeguard the entire lifecycle of Web3 credentials used in wallets  
-or validator key protection. In DePIN, TAs enable secure device attestation,  
-helping to prevent Sybil attacks.  
-
-This directory contains a collection of reference implementations of TAs,  
-specifically tailored for Web3 use cases. These examples demonstrate how  
-to use Rust within TrustZone to support basic Web3 use cases. We will  
-gradually open-source each of them as reference implementation examples  
-for Web3 TAs. Web3 builders can leverage these examples to integrate secure  
-functionalities into their projects, particularly in environments where OP-TEE  
-and TrustZone technologies are employed.  
-
-## Basic Web3 Wallet  
-**AVAILABLE** in [eth-wallet/](./eth-wallet)  
-
-A wallet abstraction featuring key functionalities like secure key management  
-and transaction signing. The key management includes secure seed generation,  
-mnemonic derivation, and safe key storage within external TEE-protected  
-environments. For transaction signing, we demonstrate how to securely sign  
-an Ethereum transaction using wallet-derived keys inside the TEE, ensuring  
-the private keys never leave the trusted environment.  
-
-## Decentralized Identifier (DID)  
-**To Be Released**  
-
-This example will illustrate how to integrate Decentralized Identifiers (DIDs)  
-into TAs. DIDs enable self-sovereign identity by proving ownership without  
-relying on central authorities. Secure key management for creating and  
-operating DIDs ensures reliable device identification, mitigating the risk of  
-fake devices in DePIN.  
+# Reference Implementation Examples for Web3 Trusted Applications
+
+Teaclave TrustZone SDK allows developers to create Trusted Applications (TAs) in
+Rust, offering a memory-safe and secure environment. Many examples in this
+repository are ported from OP-TEE C examples. With Rust's ecosystem and support
+for Rust-std in Teaclave TrustZone SDK, developers can build secure TAs to
+protect confidential information.
+
+In Web3, private key protection is vital for securing on-chain identities and
+assets. TAs safeguard the entire lifecycle of Web3 credentials used in wallets
+or validator key protection. In DePIN, TAs enable secure device attestation,
+helping to prevent Sybil attacks.
+
+This directory contains a collection of reference implementations of TAs,
+specifically tailored for Web3 use cases. These examples demonstrate how to use
+Rust within TrustZone to support basic Web3 use cases. We will gradually
+open-source each of them as reference implementation examples for Web3 TAs. Web3
+builders can leverage these examples to integrate secure functionalities into
+their projects, particularly in environments where OP-TEE and TrustZone
+technologies are employed.
+
+## Basic Web3 Wallet
+
+**AVAILABLE** in [eth-wallet/](./eth-wallet)
+
+A wallet abstraction featuring key functionalities like secure key management
+and transaction signing. The key management includes secure seed generation,
+mnemonic derivation, and safe key storage within external TEE-protected
+environments. For transaction signing, we demonstrate how to securely sign an
+Ethereum transaction using wallet-derived keys inside the TEE, ensuring the
+private keys never leave the trusted environment.
+
+## Decentralized Identifier (DID)
+
+**To Be Released**
+
+This example will illustrate how to integrate Decentralized Identifiers (DIDs)
+into TAs. DIDs enable self-sovereign identity by proving ownership without
+relying on central authorities. Secure key management for creating and operating
+DIDs ensures reliable device identification, mitigating the risk of fake devices
+in DePIN.
diff --git a/projects/web3/eth_wallet/README.md b/projects/web3/eth_wallet/README.md
@@ -0,0 +1,188 @@
+# Eth-Wallet: A Sample Trusted Application for Wallet Abstraction and Transaction Signing
+
+This repository provides a reference implementation of an Ethereum wallet as a
+Trusted Application (TA) written in Rust. The primary goal is to ensure that
+secret credentials (such as private keys) remain securely within the Trusted
+Execution Environment (TEE) throughout their entire lifecycle, enhancing
+security and privacy for Ethereum-based operations. This reference
+implementation can be extended to support additional wallet features or adapted
+to other blockchain platforms with similar requirements for secure key
+management. The implementation provides basic wallet abstractions, including:
+
+- Key Generation: Securely generating random seeds within the TEE.
+- Key Derivation: Deriving keys from seeds within the TEE.
+- Key Persistency: Storing cryptographic keys securely in the TEE.
+- Transaction Signing: Signing Ethereum transactions without exposing private
+  keys to the normal world.
+- Key Erase: Erasing keys when they are no longer needed.
+
+## Structure
+
+- [TA](./ta): The Trusted Application (TA) that performs all secure operations
+  related to the wallet. This component runs within the TrustZone TEE, ensuring
+  that secret credentials never leave the secure environment.
+- [CA](./host): The Client Application (CA) that runs in the normal world and
+  communicates with the TA. It is responsible for user interaction and
+  non-sensitive operations.
+- [Proto](./proto): Contains shared structures and definitions used by both the
+  TA and CA to facilitate communication between the two environments.
+
+## Setup
+
+To set up the environment, follow the instructions in the
+[Apache Teaclave TrustZone SDK README](https://github.com/apache/incubator-teaclave-trustzone-sdk/blob/master/README.md).
+
+## Functionalities
+
+- **Create Wallet**: Generate a new Ethereum wallet with a unique ID.
+- **Derive Address**: Derive an Ethereum address from a wallet.
+- **Sign Transaction**: Sign Ethereum transactions securely within the TEE.
+- **Remove Wallet**: Delete a wallet and its associated keys from the TEE.
+
+## Usage
+
+### Build
+
+```
+$ cd projects/eth_wallet-rs
+$ make
+```
+
+### Run
+
+After QEMU boots:
+
+```bash
+Welcome to Buildroot, type root or test to login
+buildroot login: root
+# mkdir shared && mount -t 9p -o trans=virtio host shared
+# cd shared/
+# ls
+be2dc9a0-02b4-4b33-ba21-9964dbdf1573.ta
+eth_wallet-rs
+# cp be2dc9a0-02b4-4b33-ba21-9964dbdf1573.ta /lib/optee_armtz/
+# ./eth_wallet-rs
+```
+
+### Command-Line Interface
+
+```bash
+A simple Ethereum wallet based on TEE
+
+USAGE:
+eth_wallet-rs <SUBCOMMAND>
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+SUBCOMMANDS:
+    create-wallet       Create a new wallet
+    derive-address      Derive an address from a wallet
+    help                Prints this message or the help of the given subcommand(s)
+    remove-wallet       Remove a wallet
+    sign-transaction    Sign a transaction
+    test                Run tests
+```
+
+## Example Commands
+
+### Create a Wallet
+
+```bash
+# ./eth_wallet-rs create-wallet
+```
+
+**CA Output:**
+
+```text
+CA: command: CreateWallet
+CA: invoke_command success
+Wallet ID: aa5798a1-3c89-4708-b316-712aea4f59e2
+```
+
+**TA Output:**
+
+```text
+[+] TA create
+[+] TA open session
+[+] TA invoke command
+[+] Wallet created: Wallet { id: aa5798a1-3c89-4708-b316-712aea4f59e2, entropy: [...] }
+[+] Wallet ID: aa5798a1-3c89-4708-b316-712aea4f59e2
+[+] Wallet saved in secure storage
+```
+
+### Derive an Address
+
+```bash
+# ./eth_wallet-rs derive-address -w aa5798a1-3c89-4708-b316-712aea4f59e2
+```
+
+**CA Output:**
+
+```text
+CA: command: DeriveAddress
+CA: invoke_command success
+Address: 0x7ca2b64a29bbf7a77bf8a3187ab09f50413826ea
+Public key: 03e1289e07eca6fe47c4825ea52f7cd27e3143ac5d65d5842aa5f59b5eba2d58df
+```
+
+**TA Output:**
+
+```text
+[+] TA invoke command
+[+] Deriving address: secure object loaded
+[+] Wallet::derive_pub_key(): pub key: "xpub6FhY8TmVeQ6Yo5ViNX6LK3mM66nMJDe4ZumHmznLNRkK2wEhGoEjaossvKmjgETpFHNGs9CFjUS7HK1un9Djzw9jfsukyNxu53b87abRJUv"
+[+] Wallet::derive_pub_key(): non-extended pub key: 03e1289e07eca6fe47c4825ea52f7cd27e3143ac5d65d5842aa5f59b5eba2d58df
+[+] Wallet::derive_address(): address: [124, 162, 182, 74, 41, 187, 247, 167, 123, 248, 163, 24, 122, 176, 159, 80, 65, 56, 38, 234]
+[+] Deriving address: address: [124, 162, 182, 74, 41, 187, 247, 167, 123, 248, 163, 24, 122, 176, 159, 80, 65, 56, 38, 234]
+[+] Deriving address: public key: [3, 225, 40, 158, 7, 236, 166, 254, 71, 196, 130, 94, 165, 47, 124, 210, 126, 49, 67, 172, 93, 101, 213, 132, 42, 165, 245, 155, 94, 186, 45, 88, 223]
+```
+
+### Sign a Transaction
+
+```bash
+# ./eth_wallet-rs sign-transaction -t 0xc0ffee254729296a45a3885639AC7E10F9d54979 -v 100 -w aa5798a1-3c89-4708-b316-712aea4f59e2
+```
+
+**CA Output:**
+
+```text
+CA: command: SignTransaction
+CA: invoke_command success
+Signature: "f86380843b9aca0082520894c0ffee254729296a45a3885639ac7e10f9d5497964802ea0774fc5a364c3d7e3f4e039f8da96b66fb0a5d51cad7524e54a0c9013fb473304a033922ecf964f02c6ebdd7380bc86fe759b65c87dc9e09677d983622e35334931"
+```
+
+**TA Output:**
+
+```text
+[+] TA invoke command
+[+] Sign transaction: secure object loaded
+[+] Wallet::derive_prv_key() finished
+[+] sign_transaction: signed transaction bytes: [248, 99, 128, 132, 59, 154, 202, 0, 130, 82, 8, 148, 192, 255, 238, 37, 71, 41, 41, 106, 69, 163, 136, 86, 57, 172, 126, 16, 249, 213, 73, 121, 100, 128, 46, 160, 119, 79, 197, 163, 100, 195, 215, 227, 244, 224, 57, 248, 218, 150, 182, 111, 176, 165, 213, 28, 173, 117, 36, 229, 74, 12, 144, 19, 251, 71, 51, 4, 160, 51, 146, 46, 207, 150, 79, 2, 198, 235, 221, 115, 128, 188, 134, 254, 117, 155, 101, 200, 125, 201, 224, 150, 119, 217, 131, 98, 46, 53, 51, 73, 49]
+[+] Sign transaction: signature: [248, 99, 128, 132, 59, 154, 202, 0, 130, 82, 8, 148, 192, 255, 238, 37, 71, 41, 41, 106, 69, 163, 136, 86, 57, 172, 126, 16, 249, 213, 73, 121, 100, 128, 46, 160, 119, 79, 197, 163, 100, 195, 215, 227, 244, 224, 57, 248, 218, 150
+
+, 182, 111, 176, 165, 213, 28, 173, 117, 36, 229, 74, 12, 144, 19, 251, 71, 51, 4, 160, 51, 146, 46, 207, 150, 79, 2, 198, 235, 221, 115, 128, 188, 134, 254, 117, 155, 101, 200, 125, 201, 224, 150, 119, 217, 131, 98, 46, 53, 51, 73, 49]
+```
+
+### Remove a Wallet
+
+```bash
+# ./eth_wallet-rs remove-wallet -w aa5798a1-3c89-4708-b316-712aea4f59e2
+```
+
+**CA Output:**
+
+```text
+CA: command: RemoveWallet
+CA: invoke_command success
+Wallet removed
+```
+
+**TA Output:**
+
+```text
+[+] TA invoke command
+[+] Removing wallet: secure object loaded
+[+] Wallet removed from secure storage
+```