diff --git a/projects/README.md b/projects/README.md index 658a2343..3ad8f82c 100644 --- 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 index 5d5a0632..e501c2ae 100644 --- 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 new file mode 100644 index 00000000..1e10978d --- /dev/null +++ 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 + +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 +```