From 2d4e0a5b3bd659b9e52c7ef8944f0db0fa898a03 Mon Sep 17 00:00:00 2001 From: munapower Date: Tue, 7 Jan 2025 15:27:45 -0300 Subject: [PATCH 1/8] remove setup options and augment maintainers Signed-off-by: munapower --- MAINTAINERS.md | 23 +++++ README.md | 201 +----------------------------------------- docs/setup-option1.md | 63 +++++++++++++ docs/setup-option2.md | 108 +++++++++++++++++++++++ 4 files changed, 197 insertions(+), 198 deletions(-) create mode 100644 docs/setup-option1.md create mode 100644 docs/setup-option2.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 3634c5c08..6e09e57fb 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -14,4 +14,27 @@ |---|---|---| | Michael Steiner | g2flyer | michael.steiner@intel.com | +## Special thanks to: + +### Initial Committers + +- [Marcus Brandenburger](https://github.com/mbrandenburger) (bur@zurich.ibm.com) +- [Christian Cachin](https://github.com/cca88) (cca@zurich.ibm.com) +- [Rüdiger Kapitza](https://github.com/rrkapitz) (kapitza@ibr.cs.tu-bs.de) +- [Alessandro Sorniotti](https://github.com/ale-linux) (aso@zurich.ibm.com) + + +### Core Team FPC 1.0 +- [Mic Bowman](https://github.com/cmickeyb) (mic.bowman@intel.com) +- [Marcus Brandenburger](https://github.com/mbrandenburger) (bur@zurich.ibm.com) +- [Jeb Linton](https://github.com/jrlinton) (jrlinton@us.ibm.com) +- [Michael Steiner](https://github.com/g2flyer) (michael.steiner@intel.com) +- [Bruno Vavala](https://github.com/bvavala) (bruno.vavala@intel.com) + + +### Sponsor + +[Gari Singh](https://github.com/mastersingh24) (garis@us.ibm.com) + + Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License diff --git a/README.md b/README.md index d0e68c800..8479b8f02 100644 --- a/README.md +++ b/README.md @@ -180,185 +180,14 @@ git clone --recursive https://github.com/hyperledger/fabric-private-chaincode.gi ## Setup your Development Environment -There are two different ways to develop Fabric Private Chaincode. Using our preconfigured Docker container development environment or setting up your local system with all required software dependencies to build and develop chaincode locally. +There are two different ways to develop Fabric Private Chaincode. ### Option 1: Using the Docker-based FPC Development Environment - -In this section we explain how to set up a Docker-based development environment that allows you to develop and test FPC chaincode. -The docker images come with all necessary software dependencies and allow you a quick start. -We recommend to set privileges to manage docker as a non-root user. See the -official docker [documentation](https://docs.docker.com/install/linux/linux-postinstall/) -for more details. - -First make sure your host has -* Docker v23.0 (or higher). - It also should use `/var/run/docker.sock` as socket to interact with the daemon (or you - will have to override in `$FPC_PATH/config.override.mk` the default definition in make of `DOCKER_DAEMON_SOCKET`) -* GNU make - -Once you have cloned the repository, you can either use the pre-built images or you can manually build them. After that you will start the development container. - -#### Pull docker images -To pull the docker image execute the following: -```bash -make -C $FPC_PATH/utils/docker pull pull-dev -``` -#### Manually build docker images -In order to build the development image manually you can use the following commands. Note that this process may take some time. -```bash -make -C $FPC_PATH/utils/docker build build-dev -``` -#### Start the dev container -Next we will open a shell inside the FPC development container, with environment variables like `$FPC_PATH` appropriately defined and all dependencies like the Intel SGX SDK, ready to build and run FPC. -Continue with the following command: - -```bash -make -C $FPC_PATH/utils/docker run-dev -``` - -Note that by default the dev container mounts your local cloned FPC project as a volume to `/project/src/github.com/hyperledger/fabric-private-chaincode` within the docker container. -This allows you to edit the content of the repository using your favorite editor in your system and the changes inside the docker container. Additionally, you are also not loosing changes inside the container when you reboot or the container gets stopped for other reasons. - -A few more notes: -* We use Ubuntu 22.04 by default. - To build also docker images with a different version of Ubuntu, add the following to `$FPC_PATH/config.override.mk`. - ```bash - DOCKER_BUILD_OPTS=--build-arg UBUNTU_VERSION=18.04 --build-arg UBUNTU_NAME=bionic - ``` -* If you run behind a proxy, you will have to configure the proxy, - e.g., for docker (`~/.docker/config.json`) and load the configuration inside the dev container by setting `DOCKER_DEV_RUN_OPTS += -v "$HOME/.docker":"/root/.docker"` in `$FPC_PATH/config.override.mk`. - See [Working from behind a proxy](#working-from-behind-a-proxy) below for more information. Also note that with newer docker versions (i.e., docker desktop), the docker socket is located on the host in `~/.docker/`. This may cause issues when using docker inside the FPC dev container as the docker client is not able to access the docker socket at the path of the host system. You may try to switch the docker context to use `/var/run/docker.sock`. We do not recommend this approach and happy for suggestions. -* If your local host is SGX enabled, i.e., there is a device `/dev/sgx/enclave` or - `/dev/isgx` and your PSW daemon listens to `/var/run/aesmd`, then the docker image will be sgx-enabled and your settings from `./config/ias` will be used. You will have to manually set `SGX_MODE=HW` before building anything to use HW mode. -* If you want additional apt packages to be automatically added to your - container images, you can do so by modifying `$FPC_PATH/config.override.mk` file in the fabric-private-chaincode directory. - In that file, define - `DOCKER_BASE_RT_IMAGE_APT_ADD_PKGS`, - `DOCKER_BASE_DEV_IMAGE_APT_ADD_PKGS'`and/or - `DOCKER_DEV_IMAGE_APT_ADD_PKGS` with a list of packages you want to be added to you - all images, - all images where fabric/fpc is built from source and - the dev(eloper) container, respectively. - They will then be automatically added to the docker image. -* Due to the way the peer's port for chaincode connection is managed, - you will be able to run only a single FPC development container on a - particular host. -* For support for Apple Mac (M1 or newer) see the [Troubleshooting](#troubleshooting) section. - -Now you are ready to start development *within* the container. Continue with building FPC as described in the [Build Fabric Private Chaincode -](#build-fabric-private-chaincode) Section and then write [your first Private Chaincode](#your-first-private-chaincode). +Using our preconfigured Docker container development environment or setting up your local system with all required software dependencies to build and develop chaincode locally. [md](docs/setup-option1.md) ### Option 2: Setting up your system to do local development -As an alternative to the Docker-based FPC development environment you can install and manage all necessary software dependencies which are required to compile and run FPC. - -#### Requirements - -Make sure that you have the following required dependencies installed: -* Linux (OS) (we recommend Ubuntu 22.04, see [list](https://github.com/intel/linux-sgx#prerequisites) supported OS) - -* CMake v3.5.1 or higher - -* [Go](https://golang.org/) 1.21.x or higher - -* Docker 18.09 (or higher) and docker-compose 1.25.x (or higher) - Note that version from Ubuntu 18.04 is not recent enough! To upgrade, install a recent version following the instructions from [docker.com](https://docs.docker.com/compose/install/), e.g., for version 1.25.4 execute - ```bash - sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose - sudo chmod +x /usr/local/bin/docker-compose - ``` - - To install docker-componse 1.25.4 from [docker.com](https://docs.docker.com/compose/install/), execute - ```bash - sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose - sudo chmod +x /usr/local/bin/docker-compose - ``` - -* yq v4.x - You can install `yq` via `go get`. - ```bash - go get github.com/mikefarah/yq/v4 - ``` - -* Protocol Buffers - - Protocol Buffers 3.0.x needed for the Intel SGX SDK - - Protocol Buffers 3.11.x or higher and [Nanopb](http://github.com/nanopb/nanopb) 0.4.7 - -* SGX PSW & SDK v2.22 for [Linux](https://01.org/intel-software-guard-extensions/downloads) - (alternatively, you could also install it from the [source](https://github.com/intel/linux-sgx) - -* Credentials for Intel Attestation Service, read [here](#intel-attestation-service-ias) (for hardware-mode SGX) - -* [Intel Software Guard Extensions SSL](https://github.com/intel/intel-sgx-ssl) - (we recommend using tag `3.0_Rev2` OpenSSL `3.0.12`) - -* Hyperledger [Fabric](https://github.com/hyperledger/fabric/tree/v2.5.9) v2.5.9 - -* Clang-format 6.x or higher - -* jq - -* hex (for Ubuntu, found in package basez) - -* A recent version of [PlantUML](http://plantuml.com/), including Graphviz, for building documentation. See [Documentation](#building-documentation) for our recommendations on installing. The version available in common package repositories may be out of date. - -#### Intel SGX SDK and SSL - -Fabric Private Chaincode requires the Intel [SGX SDK](https://github.com/intel/linux-sgx) and -[SGX SSL](https://github.com/intel/intel-sgx-ssl) to build the main components of our framework and to develop and build -your first private chaincode. - -Install the Intel SGX software stack for Linux by following the -official [documentation](https://github.com/intel/linux-sgx). Please make sure that you use the -SDK version as denoted above in the list of requirements. - -For SGX SSL, just follow the instructions on the [corresponding -github page](https://github.com/intel/intel-sgx-ssl). In case you are -building for simulation mode only and do not have HW support, you -might also want to make sure that [simulation mode is set](https://github.com/intel/intel-sgx-ssl#available-make-flags) -when building and installing it. - -Once you have installed the SGX SDK and SSL for SGX SDK please double check that `SGX_SDK` and `SGX_SSL` variables -are set correctly in your environment. - - -#### Protocol Buffers - -We use *nanopb*, a lightweight implementation of Protocol Buffers, inside the enclaves to parse blocks of -transactions. Install nanopb by following the instruction below. For this you need a working Google Protocol Buffers -compiler with python bindings (e.g. via `apt-get install protobuf-compiler python3-protobuf libprotobuf-dev`). -For more detailed information consult the official nanopb documentation http://github.com/nanopb/nanopb. -```bash -export NANOPB_PATH=/path-to/install/nanopb/ -git clone https://github.com/nanopb/nanopb.git $NANOPB_PATH -cd $NANOPB_PATH -git checkout nanopb-0.4.7 -cd generator/proto && make -``` - -Make sure that you set `$NANOPB_PATH` as it is needed to build Fabric Private Chaincode. - -Moreover, in order to build Fabric protobufs we also require a newer Protobuf compiler than what is provided as standard Ubuntu package and is used to build the -Intel SGX SDK. For this reason you will have to download and install another version and use it together with Nanopb. Do not install the new protobuf, though, such that it is not found in your standard PATH but instead define the `PROTOC_CMD`, either as environment variable or via `config.override.mk` to point to the new `protoc` binary -```bash -wget https://github.com/protocolbuffers/protobuf/releases/download/v22.3/protoc-22.3-linux-x86_64.zip -unzip protoc-22.3-linux-x86_64.zip -d /usr/local/proto3 -export PROTOC_CMD=/usr/local/proto3/bin/protoc -``` - -#### Hyperledger Fabric - -Our project fetches the latest supported Fabric binaries during the build process automatically. -However, if you want to use your own Fabric binaries, please checkout Fabric 2.5.9 release using the following commands: -```bash -export FABRIC_PATH=$GOPATH/src/github.com/hyperledger/fabric -git clone https://github.com/hyperledger/fabric.git $FABRIC_PATH -cd $FABRIC_PATH; git checkout tags/v2.5.9 -``` - -Note that Fabric Private Chaincode may not work with the Fabric `main` branch. -Therefore, make sure you use the Fabric `v2.5.9` tag. -Make sure the source of Fabric is in your `$GOPATH`. +As an alternative to the Docker-based FPC development environment you can install and manage all necessary software dependencies which are required to compile and run FPC. [md](docs/setup-option2.md) ## Build Fabric Private Chaincode @@ -691,8 +520,6 @@ section. [Slides](https://docs.google.com/presentation/d/1KX3_gB70H6PZw5uvYbIPYPOMt8qsh2nLRsGmXEf98Ls/edit#slide=id.ga89b65b885_0_0) - - ## Project Status Hyperledger Fabric Private Chaincode was accepted via a Hyperledger Fabric [RFC](https://github.com/hyperledger/fabric-rfcs/blob/main/text/0000-fabric-private-chaincode-1.0.md) and is now under development. @@ -702,28 +529,6 @@ mechanisms and to facilitate collaboration to refine the project architecture and define minimum viable product requirements. The code provided in this repository is prototype code and not intended for production use. - -## Initial Committers - -- [Marcus Brandenburger](https://github.com/mbrandenburger) (bur@zurich.ibm.com) -- [Christian Cachin](https://github.com/cca88) (cca@zurich.ibm.com) -- [Rüdiger Kapitza](https://github.com/rrkapitz) (kapitza@ibr.cs.tu-bs.de) -- [Alessandro Sorniotti](https://github.com/ale-linux) (aso@zurich.ibm.com) - - -## Core Team FPC 1.0 -- [Mic Bowman](https://github.com/cmickeyb) (mic.bowman@intel.com) -- [Marcus Brandenburger](https://github.com/mbrandenburger) (bur@zurich.ibm.com) -- [Jeb Linton](https://github.com/jrlinton) (jrlinton@us.ibm.com) -- [Michael Steiner](https://github.com/g2flyer) (michael.steiner@intel.com) -- [Bruno Vavala](https://github.com/bvavala) (bruno.vavala@intel.com) - - -## Sponsor - -[Gari Singh](https://github.com/mastersingh24) (garis@us.ibm.com) - - ## License Hyperledger Fabric Private Chaincode source code files are made diff --git a/docs/setup-option1.md b/docs/setup-option1.md new file mode 100644 index 000000000..eba4dfe5b --- /dev/null +++ b/docs/setup-option1.md @@ -0,0 +1,63 @@ +In this section we explain how to set up a Docker-based development environment that allows you to develop and test FPC chaincode. +The docker images come with all necessary software dependencies and allow you a quick start. +We recommend to set privileges to manage docker as a non-root user. See the +official docker [documentation](https://docs.docker.com/install/linux/linux-postinstall/) +for more details. + +First make sure your host has +* Docker v23.0 (or higher). + It also should use `/var/run/docker.sock` as socket to interact with the daemon (or you + will have to override in `$FPC_PATH/config.override.mk` the default definition in make of `DOCKER_DAEMON_SOCKET`) +* GNU make + +Once you have cloned the repository, you can either use the pre-built images or you can manually build them. After that you will start the development container. + +#### Pull docker images +To pull the docker image execute the following: +```bash +make -C $FPC_PATH/utils/docker pull pull-dev +``` +#### Manually build docker images +In order to build the development image manually you can use the following commands. Note that this process may take some time. +```bash +make -C $FPC_PATH/utils/docker build build-dev +``` +#### Start the dev container +Next we will open a shell inside the FPC development container, with environment variables like `$FPC_PATH` appropriately defined and all dependencies like the Intel SGX SDK, ready to build and run FPC. +Continue with the following command: + +```bash +make -C $FPC_PATH/utils/docker run-dev +``` + +Note that by default the dev container mounts your local cloned FPC project as a volume to `/project/src/github.com/hyperledger/fabric-private-chaincode` within the docker container. +This allows you to edit the content of the repository using your favorite editor in your system and the changes inside the docker container. Additionally, you are also not loosing changes inside the container when you reboot or the container gets stopped for other reasons. + +A few more notes: +* We use Ubuntu 22.04 by default. + To build also docker images with a different version of Ubuntu, add the following to `$FPC_PATH/config.override.mk`. + ```bash + DOCKER_BUILD_OPTS=--build-arg UBUNTU_VERSION=18.04 --build-arg UBUNTU_NAME=bionic + ``` +* If you run behind a proxy, you will have to configure the proxy, + e.g., for docker (`~/.docker/config.json`) and load the configuration inside the dev container by setting `DOCKER_DEV_RUN_OPTS += -v "$HOME/.docker":"/root/.docker"` in `$FPC_PATH/config.override.mk`. + See [Working from behind a proxy](#working-from-behind-a-proxy) below for more information. Also note that with newer docker versions (i.e., docker desktop), the docker socket is located on the host in `~/.docker/`. This may cause issues when using docker inside the FPC dev container as the docker client is not able to access the docker socket at the path of the host system. You may try to switch the docker context to use `/var/run/docker.sock`. We do not recommend this approach and happy for suggestions. +* If your local host is SGX enabled, i.e., there is a device `/dev/sgx/enclave` or + `/dev/isgx` and your PSW daemon listens to `/var/run/aesmd`, then the docker image will be sgx-enabled and your settings from `./config/ias` will be used. You will have to manually set `SGX_MODE=HW` before building anything to use HW mode. +* If you want additional apt packages to be automatically added to your + container images, you can do so by modifying `$FPC_PATH/config.override.mk` file in the fabric-private-chaincode directory. + In that file, define + `DOCKER_BASE_RT_IMAGE_APT_ADD_PKGS`, + `DOCKER_BASE_DEV_IMAGE_APT_ADD_PKGS'`and/or + `DOCKER_DEV_IMAGE_APT_ADD_PKGS` with a list of packages you want to be added to you + all images, + all images where fabric/fpc is built from source and + the dev(eloper) container, respectively. + They will then be automatically added to the docker image. +* Due to the way the peer's port for chaincode connection is managed, + you will be able to run only a single FPC development container on a + particular host. +* For support for Apple Mac (M1 or newer) see the [Troubleshooting](#troubleshooting) section. + +Now you are ready to start development *within* the container. Continue with building FPC as described in the [Build Fabric Private Chaincode +](#build-fabric-private-chaincode) Section and then write [your first Private Chaincode](#your-first-private-chaincode). diff --git a/docs/setup-option2.md b/docs/setup-option2.md new file mode 100644 index 000000000..bf88f9894 --- /dev/null +++ b/docs/setup-option2.md @@ -0,0 +1,108 @@ + +#### Requirements + +Make sure that you have the following required dependencies installed: +* Linux (OS) (we recommend Ubuntu 22.04, see [list](https://github.com/intel/linux-sgx#prerequisites) supported OS) + +* CMake v3.5.1 or higher + +* [Go](https://golang.org/) 1.21.x or higher + +* Docker 18.09 (or higher) and docker-compose 1.25.x (or higher) + Note that version from Ubuntu 18.04 is not recent enough! To upgrade, install a recent version following the instructions from [docker.com](https://docs.docker.com/compose/install/), e.g., for version 1.25.4 execute + ```bash + sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose + sudo chmod +x /usr/local/bin/docker-compose + ``` + + To install docker-componse 1.25.4 from [docker.com](https://docs.docker.com/compose/install/), execute + ```bash + sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose + sudo chmod +x /usr/local/bin/docker-compose + ``` + +* yq v4.x + You can install `yq` via `go get`. + ```bash + go get github.com/mikefarah/yq/v4 + ``` + +* Protocol Buffers + - Protocol Buffers 3.0.x needed for the Intel SGX SDK + - Protocol Buffers 3.11.x or higher and [Nanopb](http://github.com/nanopb/nanopb) 0.4.7 + +* SGX PSW & SDK v2.22 for [Linux](https://01.org/intel-software-guard-extensions/downloads) + (alternatively, you could also install it from the [source](https://github.com/intel/linux-sgx) + +* Credentials for Intel Attestation Service, read [here](#intel-attestation-service-ias) (for hardware-mode SGX) + +* [Intel Software Guard Extensions SSL](https://github.com/intel/intel-sgx-ssl) + (we recommend using tag `3.0_Rev2` OpenSSL `3.0.12`) + +* Hyperledger [Fabric](https://github.com/hyperledger/fabric/tree/v2.5.9) v2.5.9 + +* Clang-format 6.x or higher + +* jq + +* hex (for Ubuntu, found in package basez) + +* A recent version of [PlantUML](http://plantuml.com/), including Graphviz, for building documentation. See [Documentation](#building-documentation) for our recommendations on installing. The version available in common package repositories may be out of date. + +#### Intel SGX SDK and SSL + +Fabric Private Chaincode requires the Intel [SGX SDK](https://github.com/intel/linux-sgx) and +[SGX SSL](https://github.com/intel/intel-sgx-ssl) to build the main components of our framework and to develop and build +your first private chaincode. + +Install the Intel SGX software stack for Linux by following the +official [documentation](https://github.com/intel/linux-sgx). Please make sure that you use the +SDK version as denoted above in the list of requirements. + +For SGX SSL, just follow the instructions on the [corresponding +github page](https://github.com/intel/intel-sgx-ssl). In case you are +building for simulation mode only and do not have HW support, you +might also want to make sure that [simulation mode is set](https://github.com/intel/intel-sgx-ssl#available-make-flags) +when building and installing it. + +Once you have installed the SGX SDK and SSL for SGX SDK please double check that `SGX_SDK` and `SGX_SSL` variables +are set correctly in your environment. + + +#### Protocol Buffers + +We use *nanopb*, a lightweight implementation of Protocol Buffers, inside the enclaves to parse blocks of +transactions. Install nanopb by following the instruction below. For this you need a working Google Protocol Buffers +compiler with python bindings (e.g. via `apt-get install protobuf-compiler python3-protobuf libprotobuf-dev`). +For more detailed information consult the official nanopb documentation http://github.com/nanopb/nanopb. +```bash +export NANOPB_PATH=/path-to/install/nanopb/ +git clone https://github.com/nanopb/nanopb.git $NANOPB_PATH +cd $NANOPB_PATH +git checkout nanopb-0.4.7 +cd generator/proto && make +``` + +Make sure that you set `$NANOPB_PATH` as it is needed to build Fabric Private Chaincode. + +Moreover, in order to build Fabric protobufs we also require a newer Protobuf compiler than what is provided as standard Ubuntu package and is used to build the +Intel SGX SDK. For this reason you will have to download and install another version and use it together with Nanopb. Do not install the new protobuf, though, such that it is not found in your standard PATH but instead define the `PROTOC_CMD`, either as environment variable or via `config.override.mk` to point to the new `protoc` binary +```bash +wget https://github.com/protocolbuffers/protobuf/releases/download/v22.3/protoc-22.3-linux-x86_64.zip +unzip protoc-22.3-linux-x86_64.zip -d /usr/local/proto3 +export PROTOC_CMD=/usr/local/proto3/bin/protoc +``` + +#### Hyperledger Fabric + +Our project fetches the latest supported Fabric binaries during the build process automatically. +However, if you want to use your own Fabric binaries, please checkout Fabric 2.5.9 release using the following commands: +```bash +export FABRIC_PATH=$GOPATH/src/github.com/hyperledger/fabric +git clone https://github.com/hyperledger/fabric.git $FABRIC_PATH +cd $FABRIC_PATH; git checkout tags/v2.5.9 +``` + +Note that Fabric Private Chaincode may not work with the Fabric `main` branch. +Therefore, make sure you use the Fabric `v2.5.9` tag. +Make sure the source of Fabric is in your `$GOPATH`. From 86f4f540ef2b81132241314482dc5e10e82cfa51 Mon Sep 17 00:00:00 2001 From: munapower Date: Tue, 7 Jan 2025 15:32:20 -0300 Subject: [PATCH 2/8] correct links to setup Signed-off-by: munapower --- README.md | 4 ++-- docs/setup-option1.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8479b8f02..1c6305c1f 100644 --- a/README.md +++ b/README.md @@ -183,11 +183,11 @@ git clone --recursive https://github.com/hyperledger/fabric-private-chaincode.gi There are two different ways to develop Fabric Private Chaincode. ### Option 1: Using the Docker-based FPC Development Environment -Using our preconfigured Docker container development environment or setting up your local system with all required software dependencies to build and develop chaincode locally. [md](docs/setup-option1.md) +Using our preconfigured Docker container development environment or setting up your local system with all required software dependencies to build and develop chaincode locally. [Option 1](docs/setup-option1.md) ### Option 2: Setting up your system to do local development -As an alternative to the Docker-based FPC development environment you can install and manage all necessary software dependencies which are required to compile and run FPC. [md](docs/setup-option2.md) +As an alternative to the Docker-based FPC development environment you can install and manage all necessary software dependencies which are required to compile and run FPC. [Option 2](docs/setup-option2.md) ## Build Fabric Private Chaincode diff --git a/docs/setup-option1.md b/docs/setup-option1.md index eba4dfe5b..86cebe5b8 100644 --- a/docs/setup-option1.md +++ b/docs/setup-option1.md @@ -60,4 +60,4 @@ A few more notes: * For support for Apple Mac (M1 or newer) see the [Troubleshooting](#troubleshooting) section. Now you are ready to start development *within* the container. Continue with building FPC as described in the [Build Fabric Private Chaincode -](#build-fabric-private-chaincode) Section and then write [your first Private Chaincode](#your-first-private-chaincode). +](../README.md#build-fabric-private-chaincode) Section and then write [your first Private Chaincode](../README.md#your-first-private-chaincode). From 51ebfd7de72a5ff68c3901dcf556e2e313a24bc8 Mon Sep 17 00:00:00 2001 From: munapower Date: Tue, 7 Jan 2025 15:39:52 -0300 Subject: [PATCH 3/8] moving architecture design Signed-off-by: munapower --- README.md | 28 +--------------------------- docs/architecture-design.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 27 deletions(-) create mode 100644 docs/architecture-design.md diff --git a/README.md b/README.md index 1c6305c1f..2411a198b 100644 --- a/README.md +++ b/README.md @@ -90,33 +90,7 @@ The system consists of the following components: and the clients to inspect the attestation of a chaincode enclave before invoking chaincode operations or committing state changes. - -### Design - -More detailed architectural information and overview of the protocols can be found in the [Fabric Private Chaincode RFC](https://github.com/hyperledger/fabric-rfcs/blob/main/text/0000-fabric-private-chaincode-1.0.md). - -The full detailed operation of FPC is documented in a series of UML -Sequence Diagrams. Note that FPC version 1.x corresponds to `FPC Lite` -in documents and code. - -Specifically: - -- The `fpc-lifecycle-v2`([puml](docs/design/fabric-v2%2B/fpc-lifecycle-v2.puml)) diagram describes the normal lifecycle of a chaincode in FPC, focusing in particular on those elements that change in FPC vs. regular Fabric. -- The `fpc-registration`([puml](docs/design/fabric-v2%2B/fpc-registration.puml)) diagram describes how an FPC Chaincode Enclave is created on a Peer and registered in the FPC Registry, including the Remote Attestation process. -- The `fpc-key-dist`([puml](docs/design/fabric-v2%2B/fpc-key-dist.puml)) diagram describes the process by which chaincode-unique cryptographic keys are created and distributed among enclaves running identical chaincodes. Note that in the current version of FPC, key generation is performed, but the key distribution protocol has not yet been implemented. -- The `fpc-cc-invocation`([puml](docs/design/fabric-v2%2B/fpc-cc-invocation.puml)) diagram illustrates the invocation process at the beginning of the chaincode lifecycle in detail, focusing on the cryptographic operations between the Client and Peer leading up to submission of a transaction for Ordering. -- The `fpc-cc-execution`([puml](docs/design/fabric-v2%2B/fpc-cc-execution.puml)) diagram provides further detail of the execution phase of an FPC chaincode, focusing in particular on the `getState` and `putState` interactions with the Ledger. -- The `fpc-validation`([puml](docs/design/fabric-v2%2B/fpc-validation.puml)) diagram describes the FPC-specific process of validation. -- The `fpc-components`([puml](docs/design/fabric-v2%2B/fpc-components.puml)) diagram shows the important data structures of FPC components and messages exchanged between components. -- The detailed message definitions can be found as [protobufs](protos/fpc). -- The [interfaces document](docs/design/fabric-v2%2B/interfaces.md) defines the interfaces exposed by the FPC components and their internal state. - -Additional Google documents provide details on FPC 1.0: - -- The [FPC for Health use case](https://docs.google.com/document/d/1jbiOY6Eq7OLpM_s3nb-4X4AJXROgfRHOrNLQDLxVnsc/) describes how FPC 1.0 enables a health care use case. - The document also gives more details on the FPC 1.0-enabled application domains and related constraints. Lastly, it provides a security analysis why these constraints are sufficient for security. -- The [FPC externalized endorsement validation](https://docs.google.com/document/d/1RSrOfI9nh3d_DxT5CydvCg9lVNsZ9a30XcgC07in1BY/) describes the FPC 1.0 enclave endorsement validation mechanism. - +More design information can be found [here](docs/architecture-design.md) ### Source organization diff --git a/docs/architecture-design.md b/docs/architecture-design.md new file mode 100644 index 000000000..c77e81caf --- /dev/null +++ b/docs/architecture-design.md @@ -0,0 +1,26 @@ +### Design + +More detailed architectural information and overview of the protocols can be found in the [Fabric Private Chaincode RFC](https://github.com/hyperledger/fabric-rfcs/blob/main/text/0000-fabric-private-chaincode-1.0.md). + +The full detailed operation of FPC is documented in a series of UML +Sequence Diagrams. Note that FPC version 1.x corresponds to `FPC Lite` +in documents and code. + +Specifically: + +- The `fpc-lifecycle-v2`([puml](docs/design/fabric-v2%2B/fpc-lifecycle-v2.puml)) diagram describes the normal lifecycle of a chaincode in FPC, focusing in particular on those elements that change in FPC vs. regular Fabric. +- The `fpc-registration`([puml](docs/design/fabric-v2%2B/fpc-registration.puml)) diagram describes how an FPC Chaincode Enclave is created on a Peer and registered in the FPC Registry, including the Remote Attestation process. +- The `fpc-key-dist`([puml](docs/design/fabric-v2%2B/fpc-key-dist.puml)) diagram describes the process by which chaincode-unique cryptographic keys are created and distributed among enclaves running identical chaincodes. Note that in the current version of FPC, key generation is performed, but the key distribution protocol has not yet been implemented. +- The `fpc-cc-invocation`([puml](docs/design/fabric-v2%2B/fpc-cc-invocation.puml)) diagram illustrates the invocation process at the beginning of the chaincode lifecycle in detail, focusing on the cryptographic operations between the Client and Peer leading up to submission of a transaction for Ordering. +- The `fpc-cc-execution`([puml](docs/design/fabric-v2%2B/fpc-cc-execution.puml)) diagram provides further detail of the execution phase of an FPC chaincode, focusing in particular on the `getState` and `putState` interactions with the Ledger. +- The `fpc-validation`([puml](docs/design/fabric-v2%2B/fpc-validation.puml)) diagram describes the FPC-specific process of validation. +- The `fpc-components`([puml](docs/design/fabric-v2%2B/fpc-components.puml)) diagram shows the important data structures of FPC components and messages exchanged between components. +- The detailed message definitions can be found as [protobufs](protos/fpc). +- The [interfaces document](docs/design/fabric-v2%2B/interfaces.md) defines the interfaces exposed by the FPC components and their internal state. + +Additional Google documents provide details on FPC 1.0: + +- The [FPC for Health use case](https://docs.google.com/document/d/1jbiOY6Eq7OLpM_s3nb-4X4AJXROgfRHOrNLQDLxVnsc/) describes how FPC 1.0 enables a health care use case. + The document also gives more details on the FPC 1.0-enabled application domains and related constraints. Lastly, it provides a security analysis why these constraints are sufficient for security. +- The [FPC externalized endorsement validation](https://docs.google.com/document/d/1RSrOfI9nh3d_DxT5CydvCg9lVNsZ9a30XcgC07in1BY/) describes the FPC 1.0 enclave endorsement validation mechanism. + From 9e3579f439acfc426a8d04d6a536a58d36cfc566 Mon Sep 17 00:00:00 2001 From: munapower Date: Wed, 8 Jan 2025 14:52:34 -0300 Subject: [PATCH 4/8] moved reference guides, troubleshooting and build sgx Signed-off-by: munapower --- README.md | 189 +--------------------------------------- docs/build-sgx.md | 35 ++++++++ docs/referenceguides.md | 29 ++++++ docs/troubleshooting.md | 122 ++++++++++++++++++++++++++ 4 files changed, 189 insertions(+), 186 deletions(-) create mode 100644 docs/build-sgx.md create mode 100644 docs/referenceguides.md create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index 2411a198b..ec6666d3c 100644 --- a/README.md +++ b/README.md @@ -195,41 +195,7 @@ To run Fabric Private Chaincode in hardware mode (secure mode), you need an SGX- hardware as well corresponding OS support. However, even if you don't have SGX hardware available, you still can run FPC in simulation mode by setting `SGX_MODE=SIM` in your environment. - -Note that the simulation mode is for developing purpose only and does -not provide any security guarantees. - -As mentioned before, by default the project builds in SGX simulation mode, `SGX_MODE=SIM` as defined in `$FPC_PATH/config.mk` and you can -explicitly opt for building in hardware-mode SGX, `SGX_MODE=HW`. In order to set non-default values for install -location, or for building in hardware-mode SGX, you can create the file `$FPC_PATH/config.override.mk` and override the default -values by defining the corresponding environment variable. - -Note that you can always come back here when you want a setup with SGX -hardware-mode later after having tested with simulation mode. - -#### Register with Intel Attestation Service (IAS) - -If you run SGX in __simulation mode only__, you can skip this section. -We currently support EPID-based attestation and use the Intel's -Attestation Service to perform attestation with chaincode enclaves. - -What you need: -* a Service Provider ID (SPID) -* the (primary) api-key associated with your SPID - -In order to use Intel's Attestation Service (IAS), you need to register -with Intel. On the [IAS EPID registration page](https://api.portal.trustedservices.intel.com/EPID-attestation) -you can find more details on how to register and obtain your SPID plus corresponding api-key. -We currently support both `linkable` and `unlinkable` signatures for the attestation. - -Place your ias api key and your SPID in the `ias` folder as follows: -```bash -echo 'YOUR_API_KEY' > $FPC_PATH/config/ias/api_key.txt -echo 'YOUR_SPID_TYPE' > $FPC_PATH/config/ias/spid_type.txt -echo 'YOUR_SPID' > $FPC_PATH/config/ias/spid.txt -``` -where `YOUR_SPID_TYPE` must be `epid-linkable` or `epid-unlinkable`, depending on the type of your subscription. - +You can find more details [here](docs/build-sgx.md). ### FPC Playground for non-SGX environments @@ -272,130 +238,8 @@ Notes: ### Troubleshooting -This section elaborate on common issues with building Fabric Private Chaincode. - -#### Docker - -Building the project requires docker. We do not recommend to run `sudo make` -to resolve issues with mis-configured docker environments as this also changes your `$GOPATH`. Please see hints on -[docker](#docker) installation above. - -The makefiles do not ensure that docker files are always rebuild to -match the latest version of the code in the repo. If you suspect you -have an issue with outdated docker images, you can run `make clobber -build` which forces a rebuild. It also ensures that all other -download, build or test artifacts are scrubbed from your repo and might -help overcoming other problems. Be advised that that the rebuild can -take a fair amount of time. - -#### Working from behind a proxy - -The current code should work behind a proxy assuming - * you have defined the corresponding environment variables (i.e., - `http_proxy`, `https_proxy` and, potentially, `no_proxy`) properly, and - * docker (daemon & client) is properly set up for proxies as - outlined in the Docker documentation for - [clients](https://docs.docker.com/network/proxy/) and the - [daemon](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy). - * the docker version is correct. - Otherwise you may run into problems with DNS resolution inside the container. - * the docker-compose version is correct. - For example, the docker-compose from Ubuntu 18.04 (docker-compose 1.17) - is _not_ recent enough to understand `~/.docker/config.json` and related proxy options. - -Furthermore, for docker-compose networks to work properly with proxies, the `noProxy` -variable in your `~/.docker/config.json` should at least contain `127.0.0.1,127.0.1.1,localhost,.org1.example.com,.example.com`. - -Another problem you might encounter when running the integration tests -insofar that some '0.0.0.0' in `integration/config/core.yaml` used by -clients -- e.g., the peer CLI using the `address: 0.0.0.0:7051` config -as part of the `peer` section -- result in the client being unable -to find the server. The likely error you will see is - `err: rpc error: code = Unavailable desc = transport is closing`. -In that case, you will have to replace the '0.0.0.0' with a concrete -ip address such as '127.0.0.1'. - - -#### Environment settings - -Our build system requires a few variables to be set in your environment. Missing variables may cause `make` to fail. -Below you find a summary of all variables which you should carefully check and add to your environment. - -```bash -# Path to your SGX SDK and SGX SSL -export SGX_SDK=/opt/intel/sgxsdk -export SGX_SSL=/opt/intel/sgxssl - -# Path to nanopb -export NANOPB_PATH=$HOME/nanopb - -# SGX simulation mode -export SGX_MODE=SIM - -# SGX simulation mode -export SGX_MODE=HW -``` -The file `config.mk` contains various defaults for some of these, but -all can be (re)defined also in an optional file `config.override.mk`. - - -#### Clang-format +This section elaborate on [common issues](docs/troubleshooting.md) with building Fabric Private Chaincode. -Some users may experience problems with clang-format. In particular, the error `command not found: clang-format` -appears even after installing it via `apt-get install clang-format`. See [here](https://askubuntu.com/questions/1034996/vim-clang-format-clang-format-is-not-found) -for how to fix this. - -#### ERCC setup failures - - - -If, e.g., running the integration tests executed when you run `make`, -you get errors of following form: - -``` -Error: endorsement failure during invoke. response: status:500 message:"Setup failed: Can not register enclave at ercc: Error while retrieving attestation report: IAS returned error: Code 401 Access Denied" -``` - -In case you run in SGX HW mode, check that your files in `config/ias` -are set properly as explained in [Section Intel Attestation Service -(IAS)](#intel-attestation-service-ias). Note that if you run -initially in simulation mode and these files do not exist, the build -will create dummy files. In case you switch later to HW mode without -configuring these files correctly for HW mode, this will result in -above error. - - -#### no Raft leader - -The following error message sometimes appears when running the integration tests in the `$FPC_PATH/integration` folder. -The output contains the following: -``` -got unexpected status: SERVICE_UNAVAILABLE -- no Raft leader -``` - -Rerunning the tests usually works. -If this error appers during the make step of [building FPC](../fabric-private-chaincode/README.md#build-fabric-private-chaincode) than uncommenting some integration tests fixes the issue. - - -#### Working with the FPC dev container - -To make starting and stopping the dev container more reliable it is advised to use the following commands: -* Start the container and get a shell: `make -C $FPC_PATH/utils/docker run-dev` -* Get another shell inside the dev container: `docker exec -it fpc-development-main /bin/bash` -* Stop the container: `docker stop fpc-development-main` - -#### Development on Apple Mac (M1 or newer) - -For developers using Apple Mac (M1 or newer) we suggest to use the prebuilt FPC dev container. -Add the following configuration to your `config.override.mk`, pull the docker images and start the FPC dev container as described above in [Option 1: Using the Docker-based FPC Development Environment](#option-1-using-the-docker-based-fpc-development-environment). -Note that SGX is not supported on Apple platforms, and hence, FPC chaincode can only be used in simulation mode. -Alternatively, a cloud-based development environment can be used with SGX HW support, see our tutorial [How to use FPC with Azure Confidential Computing](samples/deployment/azure/FPC_on_Azure.md). - -```Makefile -DOCKER_BUILD_CMD=buildx build -DOCKER_BUILD_OPTS=--platform linux/amd64 -DOCKER_DEV_RUN_OPTS=--platform linux/amd64 -``` ### Building Documentation @@ -431,35 +275,8 @@ We provide a brief [FPC on Azure Tutorial](samples/deployment/azure/FPC_on_Azure ## Reference Guides -### Management API - -While the management API for Fabric is mostly unchanged, some modifications are needed for FPC to work. -In particular, FPC extends the Fabric's lifecycle API with additional commands to create an FPC enclave and handle the key provisioning. -These are detailed separately in the **[FPC Management API document](docs/design/fabric-v2%2B/fpc-management.md)** - -### FPC Shim - -The FPC Shim follows the programming model used in the standard Fabric Go shim and offers a C++ based FPC Shim to FPC chaincode developers. It currently comprises only a subset of the standard Fabric Shim and is complemented in the future. -These details are documented separately in the Shim header file itself: **[`ecc_enclave/enclave/shim.h`](ecc_enclave/enclave/shim.h)** - -*Important*: The initial version of FPC, FPC 1.0 (aka FPC Lite), has a -few constraints in applicability and programming model. Hence, study carefully the -[section discussing this in the FPC RFC](https://github.com/hyperledger/fabric-rfcs/blob/main/text/0000-fabric-private-chaincode-1.0.md#fpc-10-application-domain) -and the comments at the top of [`shim.h`](ecc_enclave/enclave/shim.h) -before designing, implementing and deploying an FPC-based solution. - - - -### FPC Client SDK - -In order to interact with a FPC chaincode you can use the FPC Client SDK for Go or use the Peer CLI tool provided with FPC. -Both make FPC related client-side encryption and decryption transparent to the user, i.e., client-side programming is mostly standard Fabric and agnostic to FPC. - -The FPC Client SDK for Go is located in [client_sdk/go](client_sdk/go). See also [Godocs](https://pkg.go.dev/github.com/hyperledger/fabric-private-chaincode/client_sdk/go/). +You can find more details related to the Management API, FPC Shim and FPC client SDK [here](docs/referenceguides.md). -For the command-line invocations, use the **`$FPC_PATH/fabric/bin/peer.sh`** wrapper script. We refer to our integration tests for usage examples. ## Getting Help diff --git a/docs/build-sgx.md b/docs/build-sgx.md new file mode 100644 index 000000000..d031f9213 --- /dev/null +++ b/docs/build-sgx.md @@ -0,0 +1,35 @@ +#### Details - Intel SGX Attestation Support + +Note that the simulation mode is for developing purpose only and does +not provide any security guarantees. + +As mentioned before, by default the project builds in SGX simulation mode, `SGX_MODE=SIM` as defined in `$FPC_PATH/config.mk` and you can +explicitly opt for building in hardware-mode SGX, `SGX_MODE=HW`. In order to set non-default values for install +location, or for building in hardware-mode SGX, you can create the file `$FPC_PATH/config.override.mk` and override the default +values by defining the corresponding environment variable. + +Note that you can always come back here when you want a setup with SGX +hardware-mode later after having tested with simulation mode. + +#### Register with Intel Attestation Service (IAS) + +If you run SGX in __simulation mode only__, you can skip this section. +We currently support EPID-based attestation and use the Intel's +Attestation Service to perform attestation with chaincode enclaves. + +What you need: +* a Service Provider ID (SPID) +* the (primary) api-key associated with your SPID + +In order to use Intel's Attestation Service (IAS), you need to register +with Intel. On the [IAS EPID registration page](https://api.portal.trustedservices.intel.com/EPID-attestation) +you can find more details on how to register and obtain your SPID plus corresponding api-key. +We currently support both `linkable` and `unlinkable` signatures for the attestation. + +Place your ias api key and your SPID in the `ias` folder as follows: +```bash +echo 'YOUR_API_KEY' > $FPC_PATH/config/ias/api_key.txt +echo 'YOUR_SPID_TYPE' > $FPC_PATH/config/ias/spid_type.txt +echo 'YOUR_SPID' > $FPC_PATH/config/ias/spid.txt +``` +where `YOUR_SPID_TYPE` must be `epid-linkable` or `epid-unlinkable`, depending on the type of your subscription. diff --git a/docs/referenceguides.md b/docs/referenceguides.md new file mode 100644 index 000000000..02f80180e --- /dev/null +++ b/docs/referenceguides.md @@ -0,0 +1,29 @@ +### Management API + +While the management API for Fabric is mostly unchanged, some modifications are needed for FPC to work. +In particular, FPC extends the Fabric's lifecycle API with additional commands to create an FPC enclave and handle the key provisioning. +These are detailed separately in the **[FPC Management API document](docs/design/fabric-v2%2B/fpc-management.md)** + +### FPC Shim + +The FPC Shim follows the programming model used in the standard Fabric Go shim and offers a C++ based FPC Shim to FPC chaincode developers. It currently comprises only a subset of the standard Fabric Shim and is complemented in the future. +These details are documented separately in the Shim header file itself: **[`ecc_enclave/enclave/shim.h`](ecc_enclave/enclave/shim.h)** + +*Important*: The initial version of FPC, FPC 1.0 (aka FPC Lite), has a +few constraints in applicability and programming model. Hence, study carefully the +[section discussing this in the FPC RFC](https://github.com/hyperledger/fabric-rfcs/blob/main/text/0000-fabric-private-chaincode-1.0.md#fpc-10-application-domain) +and the comments at the top of [`shim.h`](ecc_enclave/enclave/shim.h) +before designing, implementing and deploying an FPC-based solution. + + + +### FPC Client SDK + +In order to interact with a FPC chaincode you can use the FPC Client SDK for Go or use the Peer CLI tool provided with FPC. +Both make FPC related client-side encryption and decryption transparent to the user, i.e., client-side programming is mostly standard Fabric and agnostic to FPC. + +The FPC Client SDK for Go is located in [client_sdk/go](client_sdk/go). See also [Godocs](https://pkg.go.dev/github.com/hyperledger/fabric-private-chaincode/client_sdk/go/). + +For the command-line invocations, use the **`$FPC_PATH/fabric/bin/peer.sh`** wrapper script. We refer to our integration tests for usage examples. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..3dcc4661a --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,122 @@ +#### Docker + +Building the project requires docker. We do not recommend to run `sudo make` +to resolve issues with mis-configured docker environments as this also changes your `$GOPATH`. Please see hints on +[docker](#docker) installation above. + +The makefiles do not ensure that docker files are always rebuild to +match the latest version of the code in the repo. If you suspect you +have an issue with outdated docker images, you can run `make clobber +build` which forces a rebuild. It also ensures that all other +download, build or test artifacts are scrubbed from your repo and might +help overcoming other problems. Be advised that that the rebuild can +take a fair amount of time. + +#### Working from behind a proxy + +The current code should work behind a proxy assuming + * you have defined the corresponding environment variables (i.e., + `http_proxy`, `https_proxy` and, potentially, `no_proxy`) properly, and + * docker (daemon & client) is properly set up for proxies as + outlined in the Docker documentation for + [clients](https://docs.docker.com/network/proxy/) and the + [daemon](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy). + * the docker version is correct. + Otherwise you may run into problems with DNS resolution inside the container. + * the docker-compose version is correct. + For example, the docker-compose from Ubuntu 18.04 (docker-compose 1.17) + is _not_ recent enough to understand `~/.docker/config.json` and related proxy options. + +Furthermore, for docker-compose networks to work properly with proxies, the `noProxy` +variable in your `~/.docker/config.json` should at least contain `127.0.0.1,127.0.1.1,localhost,.org1.example.com,.example.com`. + +Another problem you might encounter when running the integration tests +insofar that some '0.0.0.0' in `integration/config/core.yaml` used by +clients -- e.g., the peer CLI using the `address: 0.0.0.0:7051` config +as part of the `peer` section -- result in the client being unable +to find the server. The likely error you will see is + `err: rpc error: code = Unavailable desc = transport is closing`. +In that case, you will have to replace the '0.0.0.0' with a concrete +ip address such as '127.0.0.1'. + + +#### Environment settings + +Our build system requires a few variables to be set in your environment. Missing variables may cause `make` to fail. +Below you find a summary of all variables which you should carefully check and add to your environment. + +```bash +# Path to your SGX SDK and SGX SSL +export SGX_SDK=/opt/intel/sgxsdk +export SGX_SSL=/opt/intel/sgxssl + +# Path to nanopb +export NANOPB_PATH=$HOME/nanopb + +# SGX simulation mode +export SGX_MODE=SIM + +# SGX simulation mode +export SGX_MODE=HW +``` +The file `config.mk` contains various defaults for some of these, but +all can be (re)defined also in an optional file `config.override.mk`. + + +#### Clang-format + +Some users may experience problems with clang-format. In particular, the error `command not found: clang-format` +appears even after installing it via `apt-get install clang-format`. See [here](https://askubuntu.com/questions/1034996/vim-clang-format-clang-format-is-not-found) +for how to fix this. + +#### ERCC setup failures + + + +If, e.g., running the integration tests executed when you run `make`, +you get errors of following form: + +``` +Error: endorsement failure during invoke. response: status:500 message:"Setup failed: Can not register enclave at ercc: Error while retrieving attestation report: IAS returned error: Code 401 Access Denied" +``` + +In case you run in SGX HW mode, check that your files in `config/ias` +are set properly as explained in [Section Intel Attestation Service +(IAS)](#intel-attestation-service-ias). Note that if you run +initially in simulation mode and these files do not exist, the build +will create dummy files. In case you switch later to HW mode without +configuring these files correctly for HW mode, this will result in +above error. + + +#### no Raft leader + +The following error message sometimes appears when running the integration tests in the `$FPC_PATH/integration` folder. +The output contains the following: +``` +got unexpected status: SERVICE_UNAVAILABLE -- no Raft leader +``` + +Rerunning the tests usually works. +If this error appers during the make step of [building FPC](../fabric-private-chaincode/README.md#build-fabric-private-chaincode) than uncommenting some integration tests fixes the issue. + + +#### Working with the FPC dev container + +To make starting and stopping the dev container more reliable it is advised to use the following commands: +* Start the container and get a shell: `make -C $FPC_PATH/utils/docker run-dev` +* Get another shell inside the dev container: `docker exec -it fpc-development-main /bin/bash` +* Stop the container: `docker stop fpc-development-main` + +#### Development on Apple Mac (M1 or newer) + +For developers using Apple Mac (M1 or newer) we suggest to use the prebuilt FPC dev container. +Add the following configuration to your `config.override.mk`, pull the docker images and start the FPC dev container as described above in [Option 1: Using the Docker-based FPC Development Environment](#option-1-using-the-docker-based-fpc-development-environment). +Note that SGX is not supported on Apple platforms, and hence, FPC chaincode can only be used in simulation mode. +Alternatively, a cloud-based development environment can be used with SGX HW support, see our tutorial [How to use FPC with Azure Confidential Computing](samples/deployment/azure/FPC_on_Azure.md). + +```Makefile +DOCKER_BUILD_CMD=buildx build +DOCKER_BUILD_OPTS=--platform linux/amd64 +DOCKER_DEV_RUN_OPTS=--platform linux/amd64 +``` From 2f67c998193a4301537ca4557b8b4394e061d195 Mon Sep 17 00:00:00 2001 From: munapower Date: Wed, 8 Jan 2025 14:57:58 -0300 Subject: [PATCH 5/8] nonsgx playground Signed-off-by: munapower --- README.md | 30 ++---------------------------- docs/playground-nonsgx.md | 0 2 files changed, 2 insertions(+), 28 deletions(-) create mode 100644 docs/playground-nonsgx.md diff --git a/README.md b/README.md index ec6666d3c..2fc26a476 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ cd $FPC_PATH make docker make ``` - + Besides the default target, there are also following make targets: - `build`: build all FPC build artifacts - `docker`: build docker images @@ -188,7 +188,6 @@ can all be redefined in an optional file `config.override.mk`. See also [below](#building-documentation) on how to build the documentation. - ### Intel SGX Attestation Support To run Fabric Private Chaincode in hardware mode (secure mode), you need an SGX-enabled @@ -208,34 +207,9 @@ To overcome these limitations and allow developers to toy around with the FPC AP 1) Using the [Docker-based FPC Development Environment](#setup-your-development-environment) (works well on x86-based platforms on Linux and Mac). 2) FPC builds without SGX SDK dependencies (targets x86/arm-based platforms on Linux and Mac). -We now elaborate on how to build the FPC components without the SGX SDK. +We now elaborate on how to build the FPC components without the SGX SDK [here](docs/playground-nonsgx.md). Note that this is indented for developing purpose only and does not provide any protection at all. -In your `config.override.mk` set the following to variables: -```Makefile -FPC_CCENV_IMAGE=ubuntu:22.04 -ERCC_GOTAGS= -``` -This configuration sets a standard Ubuntu image as alternative to our `fabric-private-chaincode-ccenv` image and overrides the default build tags we use to build `ercc`. - -Next you can build `ercc` using the following command: -```bash -GOOS=linux make -C $FPC_PATH/ercc build docker -``` - -For building a chaincode, for instance `$FPC_PATH/samples/chaincode/kv-test-go`, just run: -```bash -GOOS=linux make -C $FPC_PATH/samples/chaincode/kv-test-go with_go docker -``` - -You can test your FPC chaincode easily with one of the [sample deployments](samples/deployment) tutorials. -We recommend to start with [the-simple-testing-network](samples/deployment/fabric-smart-client/the-simple-testing-network). - -Notes: -- On Mac use a recent version of bash (`brew install bash`). -- TODO more to come - - ### Troubleshooting This section elaborate on [common issues](docs/troubleshooting.md) with building Fabric Private Chaincode. diff --git a/docs/playground-nonsgx.md b/docs/playground-nonsgx.md new file mode 100644 index 000000000..e69de29bb From ea3f01df319fd6893c405d21d9a9ff7a7d8856ad Mon Sep 17 00:00:00 2001 From: munapower Date: Wed, 8 Jan 2025 15:29:41 -0300 Subject: [PATCH 6/8] update samples readme and fix main readme Signed-off-by: munapower --- README.md | 4 ++-- samples/README.md | 5 +++++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2fc26a476..9b54eac08 100644 --- a/README.md +++ b/README.md @@ -157,7 +157,7 @@ git clone --recursive https://github.com/hyperledger/fabric-private-chaincode.gi There are two different ways to develop Fabric Private Chaincode. ### Option 1: Using the Docker-based FPC Development Environment -Using our preconfigured Docker container development environment or setting up your local system with all required software dependencies to build and develop chaincode locally. [Option 1](docs/setup-option1.md) +Using our preconfigured Docker container development environment. [Option 1](docs/setup-option1.md) ### Option 2: Setting up your system to do local development @@ -174,7 +174,7 @@ cd $FPC_PATH make docker make ``` - + Besides the default target, there are also following make targets: - `build`: build all FPC build artifacts - `docker`: build docker images diff --git a/samples/README.md b/samples/README.md index 5d7f51e13..fbfc0ab76 100644 --- a/samples/README.md +++ b/samples/README.md @@ -1,2 +1,7 @@ # Hyperledger Fabric Private Chaincode Samples +In the [samples](samples) folder you find a few examples how to develop applications using FPC and run them +on a Fabric network. +In particular, [samples/application](samples/application) contains examples of the FPC Client SDK for Go. +In [samples/chaincode](samples/chaincode) we give illustrate the use of the FPC Chaincode API; +and in [samples/deployment](samples/deployment) we show how to deploy and run FPC chaincode on the Fabric-samples test network and with K8s (minikube). From 7c6ebd3f48255207538897fe1ebb2eb88cd0952c Mon Sep 17 00:00:00 2001 From: munapower Date: Wed, 8 Jan 2025 15:33:59 -0300 Subject: [PATCH 7/8] fix readme Signed-off-by: munapower --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 9b54eac08..1b0a7ceba 100644 --- a/README.md +++ b/README.md @@ -212,8 +212,7 @@ Note that this is indented for developing purpose only and does not provide any ### Troubleshooting -This section elaborate on [common issues](docs/troubleshooting.md) with building Fabric Private Chaincode. - +This section elaborate on common issues with building Fabric Private Chaincode that you can read [here](docs/troubleshooting.md). ### Building Documentation From 49fbf4e581b7e831b2d1cc20d6de666a8da46e67 Mon Sep 17 00:00:00 2001 From: munapower Date: Tue, 14 Jan 2025 13:45:46 -0300 Subject: [PATCH 8/8] add playground nonsgx doc Signed-off-by: munapower --- docs/playground-nonsgx.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/playground-nonsgx.md b/docs/playground-nonsgx.md index e69de29bb..84f72c034 100644 --- a/docs/playground-nonsgx.md +++ b/docs/playground-nonsgx.md @@ -0,0 +1,23 @@ +In your `config.override.mk` set the following to variables: +```Makefile +FPC_CCENV_IMAGE=ubuntu:22.04 +ERCC_GOTAGS= +``` +This configuration sets a standard Ubuntu image as alternative to our `fabric-private-chaincode-ccenv` image and overrides the default build tags we use to build `ercc`. + +Next you can build `ercc` using the following command: +```bash +GOOS=linux make -C $FPC_PATH/ercc build docker +``` + +For building a chaincode, for instance `$FPC_PATH/samples/chaincode/kv-test-go`, just run: +```bash +GOOS=linux make -C $FPC_PATH/samples/chaincode/kv-test-go with_go docker +``` + +You can test your FPC chaincode easily with one of the [sample deployments](samples/deployment) tutorials. +We recommend to start with [the-simple-testing-network](samples/deployment/fabric-smart-client/the-simple-testing-network). + +Notes: +- On Mac use a recent version of bash (`brew install bash`). +- TODO more to come