chore: update document

ldclabs · Nov 7, 2024 · 49f49f3 · 49f49f3
1 parent 63432a7
commit 49f49f3
Show file tree

Hide file tree

Showing 10 changed files with 70 additions and 36 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -1,2 +1,22 @@
 # IC-TEE
 🔐 Make Trusted Execution Environments (TEEs) work with the Internet Computer.
+
+Relation project: [IC-COSE](https://github.com/ldclabs/ic-cose), a decentralized COnfiguration service with Signing and Encryption on the Internet Computer.
+
+## Libraries
+
+| Library                                                                                              | Description                                                                                               |
+| :--------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
+| [ic_tee_agent](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_agent)                         | An agent to interact with the Internet Computer for Trusted Execution Environments (TEEs).                |
+| [ic_tee_cdk](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_cdk)                             | A Canister Development Kit to make Trusted Execution Environments (TEEs) work with the Internet Computer. |
+| [ic_tee_cli](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_cli)                             | A command-line tool implemented in Rust for the IC-TEE.                                                   |
+| [ic_tee_identity](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_identity)                   | An on-chain authentication service for Trusted Execution Environments (TEEs) on the Internet Computer.    |
+| [ic_tee_logtail](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_logtail)                     | A simple log tailing service for the TEE environment.                                                     |
+| [ic_tee_nitro_attestation](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_nitro_attestation) | A Rust library to process AWS Nitro enclave attestation.                                                  |
+| [ic_tee_nitro_gateway](https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_nitro_gateway)         | A gateway service within an AWS Nitro enclave.                                                            |
+
+
+## License
+Copyright © 2024 [LDC Labs](https://github.com/ldclabs).
+
+`ldclabs/ic-tee` is licensed under the MIT License. See [LICENSE](./LICENSE-MIT) for the full license text.
diff --git a/nitro_enclave/host_iptables-config.sh b/nitro_enclave/host_iptables-config.sh
@@ -11,17 +11,17 @@
 ### END INIT INFO
 
 # Instructions:
-# 设置脚本权限
+#
 # sudo chmod +x /etc/init.d/iptables-config
-# 将脚本添加到系统服务
+#
 # sudo chkconfig --add iptables-config
-# 设置开机自启
+#
 # sudo chkconfig iptables-config on
-# 如果想立即运行脚本测试
+#
 # sudo service iptables-config start
-# 查看所有 NAT 规则
-# sudo iptables -t nat -L -n -v  --line-number
-# 查看所有 filter 规则
+#
+# sudo iptables -t nat -L -n -v --line-number
+#
 # sudo iptables -L -n -v
 # delete a rule by line number 7
 # sudo iptables -t nat -D PREROUTING 7
@@ -30,23 +30,23 @@
 # echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
 # echo "net.ipv4.conf.all.route_localnet=1" | sudo tee -a /etc/sysctl.conf
 # echo "net.ipv4.conf.default.route_localnet=1" | sudo tee -a /etc/sysctl.conf
-# 重新加载配置
+# reload sysctl config
 # sudo sysctl -p
 
-# 清除现有规则
+# clear all rules
 iptables -F
 iptables -t nat -F
 
-# 设置默认策略
+# add default policy
 iptables -P INPUT ACCEPT
 iptables -P FORWARD ACCEPT
 iptables -P OUTPUT ACCEPT
 
-# NAT 规则
+# add DNAT rule for port 443
 iptables -t nat -A PREROUTING -p tcp --dport 443 -j DNAT --to-destination 127.0.0.1:1200
 iptables -t nat -A POSTROUTING -o lo -j MASQUERADE
 
-# filter 规则
+# add filter rules
 iptables -A INPUT -i lo -j ACCEPT
 iptables -A INPUT -p tcp --dport 1200 -j ACCEPT
 iptables -A INPUT -p tcp --dport 443 -j ACCEPT

diff --git a/src/ic_tee_cli/README.md b/src/ic_tee_cli/README.md
@@ -1,8 +1,4 @@
 # `ic_tee_cli`
-![License](https://img.shields.io/crates/l/ic_tee_cli.svg)
-[![Crates.io](https://img.shields.io/crates/d/ic_tee_cli.svg)](https://crates.io/crates/ic_tee_cli)
-[![Test](https://github.com/ldclabs/ic-tee/actions/workflows/test.yml/badge.svg)](https://github.com/ldclabs/ic-tee/actions/workflows/test.yml)
-[![Latest Version](https://img.shields.io/crates/v/ic_tee_cli.svg)](https://crates.io/crates/ic_tee_cli)
 
 `ic_tee_cli` is a command-line tool implemented in Rust for the `ic-tee`.
 

diff --git a/src/ic_tee_logtail/Cargo.toml b/src/ic_tee_logtail/Cargo.toml
@@ -14,3 +14,4 @@ tokio = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true }
 log = { workspace = true }
+structured-logger = { workspace = true }
diff --git a/src/ic_tee_logtail/src/main.rs b/src/ic_tee_logtail/src/main.rs
@@ -1,5 +1,6 @@
 use anyhow::Result;
 use clap::Parser;
+use structured_logger::{async_json::new_writer, get_env_level, Builder};
 use tokio::{io, net::TcpListener};
 
 #[derive(Parser)]
@@ -12,8 +13,13 @@ pub struct Cli {
 #[tokio::main]
 async fn main() -> Result<()> {
     let cli = Cli::parse();
+
+    Builder::with_level(&get_env_level().to_string())
+        .with_target_writer("*", new_writer(tokio::io::stdout()))
+        .init();
+
     let listener = TcpListener::bind(&cli.ip_addr).await?;
-    println!("listening on {:?}", listener.local_addr()?);
+    log::info!(target: "logtail", "listening on {:?}", listener.local_addr()?);
 
     while let Ok((mut stream, addr)) = listener.accept().await {
         tokio::spawn(async move {

diff --git a/src/ic_tee_nitro_attestation/Cargo.toml b/src/ic_tee_nitro_attestation/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ic_tee_nitro_attestation"
-description = "A Rust library to process Nitro enclaves attestation"
+description = "A Rust library to process AWS Nitro enclave attestation"
 repository = "https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_nitro_attestation"
 publish = true
 version.workspace = true

diff --git a/src/ic_tee_nitro_attestation/README.md b/src/ic_tee_nitro_attestation/README.md
@@ -5,7 +5,7 @@
 [![Docs.rs](https://img.shields.io/docsrs/ic_tee_nitro_attestation?label=docs.rs)](https://docs.rs/ic_tee_nitro_attestation)
 [![Latest Version](https://img.shields.io/crates/v/ic_tee_nitro_attestation.svg)](https://crates.io/crates/ic_tee_nitro_attestation)
 
-`ic_tee_nitro_attestation` is a Rust library to process Nitro enclaves attestation.
+`ic_tee_nitro_attestation` is a Rust library to process AWS Nitro enclave attestation.
 
 ## License
 Copyright © 2024 [LDC Labs](https://github.com/ldclabs).

diff --git a/src/ic_tee_nitro_gateway/Cargo.toml b/src/ic_tee_nitro_gateway/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ic_tee_nitro_gateway"
-description = "An gateway service in an AWS Nitro enclave."
+description = "A gateway service within an AWS Nitro enclave."
 repository = "https://github.com/ldclabs/ic-tee/tree/main/src/ic_tee_nitro_gateway"
 publish = false
 version.workspace = true

diff --git a/src/ic_tee_nitro_gateway/README.md b/src/ic_tee_nitro_gateway/README.md
@@ -1,12 +1,13 @@
 # `ic_tee_nitro_gateway`
-![License](https://img.shields.io/crates/l/ic_tee_nitro_gateway.svg)
-[![Crates.io](https://img.shields.io/crates/d/ic_tee_nitro_gateway.svg)](https://crates.io/crates/ic_tee_nitro_gateway)
-[![Test](https://github.com/ldclabs/ic-tee/actions/workflows/test.yml/badge.svg)](https://github.com/ldclabs/ic-tee/actions/workflows/test.yml)
-[![Docs.rs](https://img.shields.io/docsrs/ic_tee_nitro_gateway?label=docs.rs)](https://docs.rs/ic_tee_nitro_gateway)
-[![Latest Version](https://img.shields.io/crates/v/ic_tee_nitro_gateway.svg)](https://crates.io/crates/ic_tee_nitro_gateway)
-
 ## Overview
-`ic_tee_nitro_gateway` is a gateway service in an AWS Nitro enclave.
+
+`ic_tee_nitro_gateway` is a gateway service within an AWS Nitro enclave. It is launched inside the enclave through the ICP `ic_tee_identity` identity service and the IC-COSE configuration service, then forwards requests to the business application running in the enclave. The startup process is as follows:
+
+1. **Generate attestation** for sign in, obtaining an identity via the ICP `ic_tee_identity` service to access other services on ICP. `ic_tee_identity` verifies the attestation and derives an identity, generating the same identity for identical enclave images.
+
+2. **Switch to a fixed identity** obtained from the IC-COSE configuration service to avoid identity changes due to application upgrades. This enables consistent operations with a stable identity.
+
+3. **Start the web service** using a TLS certificate obtained with the fixed identity from the IC-COSE configuration service. This web service receives requests and forwards them to the application running inside the enclave.
 
 ## Deploy
 ### Building and running AWS Nitro Enclave image
@@ -15,6 +16,7 @@
 
 https://docs.marlin.org/learn/oyster/core-concepts/networking/outgoing
 
+Forward all traffic from vsock 3 (port 1200 in the enclave) to the internet.
 ```bash
 wget -O vsock-to-ip-transparent http://public.artifacts.marlin.pro/projects/enclaves/vsock-to-ip-transparent_v1.0.0_linux_amd64
 chmod +x vsock-to-ip-transparent
@@ -23,18 +25,12 @@ chmod +x vsock-to-ip-transparent
 
 https://docs.marlin.org/learn/oyster/core-concepts/networking/incoming
 
-iptables rules:
+Add iptables rules on the host machine to forward traffic on 443 from the internet to 127.0.0.1:1200.
 ```bash
-# route local incoming packets on port 8080 to the transparent proxy
-iptables -t nat -A OUTPUT -p tcp --dport 8080 -o lo -j REDIRECT --to-port 1200
-iptables -t nat -A OUTPUT -p tcp --dport 8080 -d 127.0.0.1 -j REDIRECT --to-port 1200
-
-# route incoming packets on port 443 to the transparent proxy
-iptables -A PREROUTING -t nat -p tcp --dport 443 -i ens5 -j REDIRECT --to-port 1200
-# route incoming packets on port 1025:65535 to the transparent proxy
-# iptables -A PREROUTING -t nat -p tcp --dport 1025:65535 -i ens5 -j REDIRECT --to-port 1200
+sudo sh nitro_enclave/host_iptables-config.sh
 ```
 
+Forward all traffic from 127.0.0.1:1200 to vsock 88.
 ```bash
 wget -O port-to-vsock-transparent http://public.artifacts.marlin.pro/projects/enclaves/port-to-vsock-transparent_v1.0.0_linux_amd64
 chmod +x port-to-vsock-transparent
@@ -47,6 +43,7 @@ The following steps should be run in AWS Nitro-based instances.
 
 https://docs.aws.amazon.com/enclaves/latest/user/getting-started.html
 
+Build the enclave image.
 ```bash
 cargo install ic_tee_cli
 sudo docker pull ghcr.io/ldclabs/ic_tee_nitro_gateway_enclave_amd64:latest
@@ -62,17 +59,27 @@ sudo nitro-cli build-enclave --docker-uri ghcr.io/ldclabs/ic_tee_nitro_gateway_e
 #     "PCR2": "3f260bf23af9b00afe2b5c1debd0e26c987abf83378a0e5f99ae49cbdd711c020c1f23d84bc93ba184baddc842c6f21b"
 #   }
 # }
+```
+
+Calculate the ICP principal from the PCR0.
+```bash
 ic_tee_cli -c e7tgb-6aaaa-aaaap-akqfa-cai identity-derive --seed 929c88889044592565f259bbae65baddcf0c426bc171017375777d55161bb662ac0fb97de301d8d6c1026b62b6061098
 # principal: 6y5sx-apnmh-blpp5-u7eyr-nnl2t-rflnm-7sw2q-ptbx3-iv47r-rsnun-eqe
+```
 
+Add the principal to the permament identity setting on IC-COSE service, so that the enclave can load permament identity after sign in with the principal.
+```bash
 dfx canister call ic_cose_canister setting_add_readers '(record {
   ns = "_";
   key = blob "\69\64\5f\65\64\32\35\35\31\39";
   subject = opt principal "fbi6t-ogdrt-s4de4-sxive-x4yid-xfrk2-e6jgf-jbnuh-rzxoj-qv2qa-zae";
   version = 1;
   user_owned = false;
 }, vec{ principal "6y5sx-apnmh-blpp5-u7eyr-nnl2t-rflnm-7sw2q-ptbx3-iv47r-rsnun-eqe" })' --ic
+```
 
+Run the enclave.
+```bash
 sudo nitro-cli run-enclave --cpu-count 2 --memory 512 --enclave-cid 88 --eif-path ic_tee_nitro_gateway_enclave_amd64.eif
 # Start allocating memory...
 # Started enclave with enclave-cid: 88, memory: 512 MiB, cpu-ids: [1, 3]
@@ -88,6 +95,9 @@ sudo nitro-cli run-enclave --cpu-count 2 --memory 512 --enclave-cid 88 --eif-pat
 #   ],
 #   "MemoryMiB": 512
 # }
+```
+
+```bash
 sudo nitro-cli describe-enclaves
 sudo nitro-cli terminate-enclave --enclave-id i-056e1ab9a31cd77a0-enc193037029f7f152
 ```