Skip to content

Commit 7f07b9a

Browse files
munapowermbrandenburger
munapower
authored and
mbrandenburger
committed
Reorganize Readme
Signed-off-by: munapower <[email protected]> correct links to setup Signed-off-by: munapower <[email protected]> moving architecture design Signed-off-by: munapower <[email protected]> moved reference guides, troubleshooting and build sgx Signed-off-by: munapower <[email protected]> nonsgx playground Signed-off-by: munapower <[email protected]> update samples readme and fix main readme Signed-off-by: munapower <[email protected]> fix readme Signed-off-by: munapower <[email protected]> add playground nonsgx doc Signed-off-by: munapower <[email protected]> fixed links to other pages or sections Signed-off-by: munapower <[email protected]> correct link errprs Signed-off-by: munapower <[email protected]> Apply suggestions from code review Signed-off-by: Marcus Brandenburger <[email protected]> Update samples/README.md Signed-off-by: Marcus Brandenburger <[email protected]>
1 parent 805e428 commit 7f07b9a

File tree

10 files changed

+471
-439
lines changed

10 files changed

+471
-439
lines changed

‎MAINTAINERS.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,27 @@
1414
|---|---|---|
1515
| Michael Steiner | g2flyer | [email protected] |
1616

17+
## Special thanks to:
18+
19+
### Initial Committers
20+
21+
- [Marcus Brandenburger](https://github.com/mbrandenburger) ([email protected])
22+
- [Christian Cachin](https://github.com/cca88) ([email protected])
23+
- [Rüdiger Kapitza](https://github.com/rrkapitz) ([email protected])
24+
- [Alessandro Sorniotti](https://github.com/ale-linux) ([email protected])
25+
26+
27+
### Core Team FPC 1.0
28+
- [Mic Bowman](https://github.com/cmickeyb) ([email protected])
29+
- [Marcus Brandenburger](https://github.com/mbrandenburger) ([email protected])
30+
- [Jeb Linton](https://github.com/jrlinton) ([email protected])
31+
- [Michael Steiner](https://github.com/g2flyer) ([email protected])
32+
- [Bruno Vavala](https://github.com/bvavala) ([email protected])
33+
34+
35+
### Sponsor
36+
37+
[Gari Singh](https://github.com/mastersingh24) ([email protected])
38+
39+
1740
<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>

‎README.md

Lines changed: 8 additions & 439 deletions
Large diffs are not rendered by default.

‎docs/architecture-design.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Architecture design
2+
3+
The main [README](../README.md) gives an high-level overview of the FPC architecture. Here we provide additional details.
4+
5+
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).
6+
7+
The full detailed operation of FPC is documented in a series of UML
8+
Sequence Diagrams. Note that FPC version 1.x corresponds to `FPC Lite`
9+
in documents and code.
10+
11+
Specifically:
12+
13+
- The `fpc-lifecycle-v2`([puml](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.
14+
- The `fpc-registration`([puml](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.
15+
- The `fpc-key-dist`([puml](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.
16+
- The `fpc-cc-invocation`([puml](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.
17+
- The `fpc-cc-execution`([puml](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.
18+
- The `fpc-validation`([puml](design/fabric-v2%2B/fpc-validation.puml)) diagram describes the FPC-specific process of validation.
19+
- The `fpc-components`([puml](design/fabric-v2%2B/fpc-components.puml)) diagram shows the important data structures of FPC components and messages exchanged between components.
20+
- The detailed message definitions can be found as [protobufs](protos/fpc).
21+
- The [interfaces document](design/fabric-v2%2B/interfaces.md) defines the interfaces exposed by the FPC components and their internal state.
22+
23+
Additional Google documents provide details on FPC 1.0:
24+
25+
- 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.
26+
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.
27+
- The [FPC externalized endorsement validation](https://docs.google.com/document/d/1RSrOfI9nh3d_DxT5CydvCg9lVNsZ9a30XcgC07in1BY/) describes the FPC 1.0 enclave endorsement validation mechanism.
28+

‎docs/build-sgx.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Build with Intel SGX HW support
2+
3+
Here we give additional information how to build and run FPC Chaincode with Intel SGX HW support.
4+
5+
## Details - Intel SGX Attestation Support
6+
7+
Note that the simulation mode is for developing purpose only and does
8+
not provide any security guarantees.
9+
10+
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
11+
explicitly opt for building in hardware-mode SGX, `SGX_MODE=HW`. In order to set non-default values for install
12+
location, or for building in hardware-mode SGX, you can create the file `$FPC_PATH/config.override.mk` and override the default
13+
values by defining the corresponding environment variable.
14+
15+
Note that you can always come back here when you want a setup with SGX
16+
hardware-mode later after having tested with simulation mode.
17+
18+
## Register with Intel Attestation Service (IAS)
19+
20+
If you run SGX in __simulation mode only__, you can skip this section.
21+
We currently support EPID-based attestation and use the Intel's
22+
Attestation Service to perform attestation with chaincode enclaves.
23+
24+
What you need:
25+
* a Service Provider ID (SPID)
26+
* the (primary) api-key associated with your SPID
27+
28+
In order to use Intel's Attestation Service (IAS), you need to register
29+
with Intel. On the [IAS EPID registration page](https://api.portal.trustedservices.intel.com/EPID-attestation)
30+
you can find more details on how to register and obtain your SPID plus corresponding api-key.
31+
We currently support both `linkable` and `unlinkable` signatures for the attestation.
32+
33+
Place your ias api key and your SPID in the `ias` folder as follows:
34+
```bash
35+
echo 'YOUR_API_KEY' > $FPC_PATH/config/ias/api_key.txt
36+
echo 'YOUR_SPID_TYPE' > $FPC_PATH/config/ias/spid_type.txt
37+
echo 'YOUR_SPID' > $FPC_PATH/config/ias/spid.txt
38+
```
39+
where `YOUR_SPID_TYPE` must be `epid-linkable` or `epid-unlinkable`, depending on the type of your subscription.

‎docs/playground-nonsgx.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# FPC Playground for non-SGX environments
2+
3+
Here we explain how you can tinker with FPC even without Intel SGX hardware. That is, you can write your first FPC Chaincode compile it, and run it on almost any machine.
4+
5+
In your `config.override.mk` set the following to variables:
6+
```Makefile
7+
FPC_CCENV_IMAGE=ubuntu:22.04
8+
ERCC_GOTAGS=
9+
```
10+
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`.
11+
12+
Next you can build `ercc` using the following command:
13+
```bash
14+
GOOS=linux make -C $FPC_PATH/ercc build docker
15+
```
16+
17+
For building a chaincode, for instance `$FPC_PATH/samples/chaincode/kv-test-go`, just run:
18+
```bash
19+
GOOS=linux make -C $FPC_PATH/samples/chaincode/kv-test-go with_go docker
20+
```
21+
22+
You can test your FPC chaincode easily with one of the [sample deployments](../samples/deployment) tutorials.
23+
We recommend to start with [the-simple-testing-network](../samples/deployment/fabric-smart-client/the-simple-testing-network).
24+
25+
Notes:
26+
- On Mac use a recent version of bash (`brew install bash`).
27+
- TODO more to come

‎docs/referenceguides.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Reference Guides
2+
3+
Here you will find the FPC reference guides, including the management API, the FPC Shim, and the FPC Client SDK.
4+
5+
## Management API
6+
7+
While the management API for Fabric is mostly unchanged, some modifications are needed for FPC to work.
8+
In particular, FPC extends the Fabric's lifecycle API with additional commands to create an FPC enclave and handle the key provisioning.
9+
These are detailed separately in the **[FPC Management API document](design/fabric-v2%2B/fpc-management.md)**
10+
11+
## FPC Shim
12+
13+
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.
14+
These details are documented separately in the Shim header file itself: **[`../ecc_enclave/enclave/shim.h`](../ecc_enclave/enclave/shim.h)**
15+
16+
*Important*: The initial version of FPC, FPC 1.0 (aka FPC Lite), has a
17+
few constraints in applicability and programming model. Hence, study carefully the
18+
[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)
19+
and the comments at the top of [`shim.h`](../ecc_enclave/enclave/shim.h)
20+
before designing, implementing and deploying an FPC-based solution.
21+
<!-- could also mention
22+
[FPC for Health use case](https://docs.google.com/document/d/1jbiOY6Eq7OLpM_s3nb-4X4AJXROgfRHOrNLQDLxVnsc/)
23+
-->
24+
25+
26+
## FPC Client SDK
27+
28+
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.
29+
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.
30+
31+
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/).
32+
33+
For the command-line invocations, use the **`$FPC_PATH/fabric/bin/peer.sh`** wrapper script. We refer to our integration tests for usage examples.

‎docs/setup-option1.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Setup your Development Environment (Option 1)
2+
3+
In this document we explain how to setup your FPC development environment using the FPC dev docker container. We refer to this setup as `Option 1`. An alternative setup without docker you can find in [Option 2](setup-option2.md).
4+
5+
6+
In this section we explain how to set up a Docker-based development environment that allows you to develop and test FPC chaincode.
7+
The docker images come with all necessary software dependencies and allow you a quick start.
8+
We recommend to set privileges to manage docker as a non-root user. See the
9+
official docker [documentation](https://docs.docker.com/install/linux/linux-postinstall/)
10+
for more details.
11+
12+
First make sure your host has
13+
* Docker v23.0 (or higher).
14+
It also should use `/var/run/docker.sock` as socket to interact with the daemon (or you
15+
will have to override in `$FPC_PATH/config.override.mk` the default definition in make of `DOCKER_DAEMON_SOCKET`)
16+
* GNU make
17+
18+
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.
19+
20+
## Pull docker images
21+
To pull the docker image execute the following:
22+
```bash
23+
make -C $FPC_PATH/utils/docker pull pull-dev
24+
```
25+
26+
## Manually build docker images
27+
In order to build the development image manually you can use the following commands. Note that this process may take some time.
28+
```bash
29+
make -C $FPC_PATH/utils/docker build build-dev
30+
```
31+
32+
## Start the dev container
33+
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.
34+
Continue with the following command:
35+
36+
```bash
37+
make -C $FPC_PATH/utils/docker run-dev
38+
```
39+
40+
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.
41+
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.
42+
43+
A few more notes:
44+
* We use Ubuntu 22.04 by default.
45+
To build also docker images with a different version of Ubuntu, add the following to `$FPC_PATH/config.override.mk`.
46+
```bash
47+
DOCKER_BUILD_OPTS=--build-arg UBUNTU_VERSION=18.04 --build-arg UBUNTU_NAME=bionic
48+
```
49+
* If you run behind a proxy, you will have to configure the proxy,
50+
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`.
51+
See [Working from behind a proxy](troubleshooting.md#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.
52+
* If your local host is SGX enabled, i.e., there is a device `/dev/sgx/enclave` or
53+
`/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.
54+
* If you want additional apt packages to be automatically added to your
55+
container images, you can do so by modifying `$FPC_PATH/config.override.mk` file in the fabric-private-chaincode directory.
56+
In that file, define
57+
`DOCKER_BASE_RT_IMAGE_APT_ADD_PKGS`,
58+
`DOCKER_BASE_DEV_IMAGE_APT_ADD_PKGS'`and/or
59+
`DOCKER_DEV_IMAGE_APT_ADD_PKGS` with a list of packages you want to be added to you
60+
all images,
61+
all images where fabric/fpc is built from source and
62+
the dev(eloper) container, respectively.
63+
They will then be automatically added to the docker image.
64+
* Due to the way the peer's port for chaincode connection is managed,
65+
you will be able to run only a single FPC development container on a
66+
particular host.
67+
* For support for Apple Mac (M1 or newer) see the [Troubleshooting](../README.md#troubleshooting) section.
68+
69+
Now you are ready to start development *within* the container. Continue with building FPC as described in the [Build Fabric Private Chaincode
70+
](../README.md#build-fabric-private-chaincode) Section and then write [your first Private Chaincode](../README.md#your-first-private-chaincode).

‎docs/setup-option2.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Setup your Development Environment (Option 2)
2+
3+
In this document we explain how to setup your FPC development environment by installing all required software components on your machine. We refer to this setup as `Option 2`. An alternative setup with docker you can find in [Option 1](setup-option1.md).
4+
5+
6+
## Requirements
7+
8+
Make sure that you have the following required dependencies installed:
9+
* Linux (OS) (we recommend Ubuntu 22.04, see [list](https://github.com/intel/linux-sgx#prerequisites) supported OS)
10+
11+
* CMake v3.5.1 or higher
12+
13+
* [Go](https://golang.org/) 1.21.x or higher
14+
15+
* Docker 18.09 (or higher) and docker-compose 1.25.x (or higher)
16+
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
17+
```bash
18+
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
19+
sudo chmod +x /usr/local/bin/docker-compose
20+
```
21+
22+
To install docker-componse 1.25.4 from [docker.com](https://docs.docker.com/compose/install/), execute
23+
```bash
24+
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
25+
sudo chmod +x /usr/local/bin/docker-compose
26+
```
27+
28+
* yq v4.x
29+
You can install `yq` via `go get`.
30+
```bash
31+
go get github.com/mikefarah/yq/v4
32+
```
33+
34+
* Protocol Buffers
35+
- Protocol Buffers 3.0.x needed for the Intel SGX SDK
36+
- Protocol Buffers 3.11.x or higher and [Nanopb](http://github.com/nanopb/nanopb) 0.4.7
37+
38+
* SGX PSW & SDK v2.22 for [Linux](https://01.org/intel-software-guard-extensions/downloads)
39+
(alternatively, you could also install it from the [source](https://github.com/intel/linux-sgx)
40+
41+
* Credentials for Intel Attestation Service, read [here](../README.md#intel-attestation-service-ias) (for hardware-mode SGX)
42+
43+
* [Intel Software Guard Extensions SSL](https://github.com/intel/intel-sgx-ssl)
44+
(we recommend using tag `3.0_Rev2` OpenSSL `3.0.12`)
45+
46+
* Hyperledger [Fabric](https://github.com/hyperledger/fabric/tree/v2.5.9) v2.5.9
47+
48+
* Clang-format 6.x or higher
49+
50+
* jq
51+
52+
* hex (for Ubuntu, found in package basez)
53+
54+
* A recent version of [PlantUML](http://plantuml.com/), including Graphviz, for building documentation. See [Documentation](../README.md#building-documentation) for our recommendations on installing. The version available in common package repositories may be out of date.
55+
56+
## Intel SGX SDK and SSL
57+
58+
Fabric Private Chaincode requires the Intel [SGX SDK](https://github.com/intel/linux-sgx) and
59+
[SGX SSL](https://github.com/intel/intel-sgx-ssl) to build the main components of our framework and to develop and build
60+
your first private chaincode.
61+
62+
Install the Intel SGX software stack for Linux by following the
63+
official [documentation](https://github.com/intel/linux-sgx). Please make sure that you use the
64+
SDK version as denoted above in the list of requirements.
65+
66+
For SGX SSL, just follow the instructions on the [corresponding
67+
github page](https://github.com/intel/intel-sgx-ssl). In case you are
68+
building for simulation mode only and do not have HW support, you
69+
might also want to make sure that [simulation mode is set](https://github.com/intel/intel-sgx-ssl#available-make-flags)
70+
when building and installing it.
71+
72+
Once you have installed the SGX SDK and SSL for SGX SDK please double check that `SGX_SDK` and `SGX_SSL` variables
73+
are set correctly in your environment.
74+
75+
76+
## Protocol Buffers
77+
78+
We use *nanopb*, a lightweight implementation of Protocol Buffers, inside the enclaves to parse blocks of
79+
transactions. Install nanopb by following the instruction below. For this you need a working Google Protocol Buffers
80+
compiler with python bindings (e.g. via `apt-get install protobuf-compiler python3-protobuf libprotobuf-dev`).
81+
For more detailed information consult the official nanopb documentation http://github.com/nanopb/nanopb.
82+
```bash
83+
export NANOPB_PATH=/path-to/install/nanopb/
84+
git clone https://github.com/nanopb/nanopb.git $NANOPB_PATH
85+
cd $NANOPB_PATH
86+
git checkout nanopb-0.4.7
87+
cd generator/proto && make
88+
```
89+
90+
Make sure that you set `$NANOPB_PATH` as it is needed to build Fabric Private Chaincode.
91+
92+
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
93+
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
94+
```bash
95+
wget https://github.com/protocolbuffers/protobuf/releases/download/v22.3/protoc-22.3-linux-x86_64.zip
96+
unzip protoc-22.3-linux-x86_64.zip -d /usr/local/proto3
97+
export PROTOC_CMD=/usr/local/proto3/bin/protoc
98+
```
99+
100+
## Hyperledger Fabric
101+
102+
Our project fetches the latest supported Fabric binaries during the build process automatically.
103+
However, if you want to use your own Fabric binaries, please checkout Fabric 2.5.9 release using the following commands:
104+
```bash
105+
export FABRIC_PATH=$GOPATH/src/github.com/hyperledger/fabric
106+
git clone https://github.com/hyperledger/fabric.git $FABRIC_PATH
107+
cd $FABRIC_PATH; git checkout tags/v2.5.9
108+
```
109+
110+
Note that Fabric Private Chaincode may not work with the Fabric `main` branch.
111+
Therefore, make sure you use the Fabric `v2.5.9` tag.
112+
Make sure the source of Fabric is in your `$GOPATH`.

0 commit comments

Comments
 (0)