Hyperledger Fabric Private Chaincode

Hyperledger Fabric Private Chaincode (FPC) enables the execution of chaincodes using Intel SGX for Hyperledger Fabric.

The transparency and resilience gained from blockchain protocols ensure the integrity of blockchain applications and yet contradicts the goal to keep application state confidential and to maintain privacy for its users.

To remedy this problem, this project uses Trusted Execution Environments (TEEs), in particular Intel Software Guard Extensions (SGX), to protect the privacy of chaincode data and computation from potentially untrusted peers.

Intel SGX is the most prominent TEE today and available with commodity CPUs. It establishes trusted execution contexts called enclaves on a CPU, which isolate data and programs from the host operating system in hardware and ensure that outputs are correct.

This lab provides a framework to develop and execute Fabric chaincode within an enclave. Furthermore, Fabric extensions for chaincode enclave registration and transaction verification are provided.

This lab proposes an architecture to enable private chaincode execution using Intel SGX for Hyperledger Fabric as presented and published in the paper:

• Marcus Brandenburger, Christian Cachin, Rüdiger Kapitza, Alessandro Sorniotti: Blockchain and Trusted Computing: Problems, Pitfalls, and a Solution for Hyperledger Fabric. https://arxiv.org/abs/1805.08541

We provide an initial proof-of-concept implementation of the proposed architecture. Note that the code provided in this repository is prototype code and not meant for production use! The main goal of this lab is to discuss and refine the proposed architecture involving the Hyperledger community.

Architecture and components

This lab extends a Fabric peer with the following components: A chaincode enclave that executes a particular chaincode and a ledger enclave that enables all chaincode enclaves to verify the blockchain state integrity; all run inside SGX. In the untrusted part of the peer, an enclave registry maintains the identities of all chaincode enclaves and an enclave transaction validator that is responsible for validating transactions executed by a chaincode enclave before committing them to the ledger.

The following diagram shows the architecture:

The system consists of the following components:

1. Chaincode enclave: The chaincode enclave executes one particular chaincode, and thereby isolates it from the peer and from other chaincodes. A chaincode library acts as intermediary between the chaincode in the enclave and the peer. The chaincode enclave exposes the Fabric chaincode interface and extends it with additional support for state encryption, attestation, and secure blockchain state access. This component is devided into two subcomponents: ecc_enclave contains the code running inside an enclave and ecc contains a wrapper chaincode that invokes the enclave.

2. Ledger enclave: The ledger enclave maintains the ledger in an enclave in the form of integrity-specific metadata representing the most recent blockchain state at the peer. It performs the same validation steps as the peer when a new block arrives, but additionally generates a cryptographic hash of each key-value pair of the blockchain state and stores it within the enclave. The ledger enclave exposes an interface to the chaincode enclave for accessing the integrity-specific metadata. This is used to verify the correctness of the data retrieved from the blockchain state. Like the chaincode enclave, the ledger enclave is divided into two subcomponents: tlcc and tlcc_enclave.

3. Enclave registry: The enclave registry is a chaincode that runs outside SGX and maintains a list of all existing chaincode enclaves in the network. It performs attestation with the chaincode enclave and stores the attestation result on the blockchain. The attestation demonstrates that a specific chaincode executes in an actual enclave. This enables the peers and the clients to inspect the attestation of a chaincode enclave before invoking chaincode operations or committing state changes. The enclave registry (ercc) comes with a custom validation plugin (ercc-vscc).

4. Enclave transaction validator: The enclave transaction validator (ecc/vscc) complements the peer’s validation system and is responsible for validating transactions produced by a chaincode enclave. In particular, the enclave transaction validator checks that a transaction contains a valid signature issued by a registered chaincode enclave. If the validation is successful, it marks the transactions as valid and hands it over to the ledger enclave, which crosschecks the decision before it finally commits the transaction to the ledger.

Getting started

The following steps guide you through the build phase and configuration, for deploying and running an example chaincode.

Requirements

• CMake 3.5.1 or higher

• Go 1.11.x or higher

• Hyperledger Fabric v1.4.1 https://github.com/hyperledger/fabric

  If you are new to Fabric, we recommend the Fabric documentation as your starting point. You should start with installing Fabric dependencies and setting up your development environment.

• SGX SDK v2.4 or v2.5 for Linux https://github.com/intel/linux-sgx

• SSL for SGX SDK v2.4.1 https://github.com/intel/intel-sgx-ssl (we recommend using OpenSSL 1.1.0j)

• (for hardware-mode SGX build) credentials for IAS, read here

• Docker 18.x

• Nanopb 0.3.9.2 (see below)

SGX SDK and SSL

The the chaincode envlave and the trusted ledger enclave require SGX SSL. See README in project root for more details. Intel SGX SSL https://github.com/intel/intel-sgx-ssl

After installing the SGX SDK and SGX SSL double check that SGX_SDK and SGX_SSL variables are set correctly in your env. In particular, the makefiles are configured with meaningful defaults for variables like SGX_SDK, SGX_ARCH, SGX_MODE, SGX_BUILD or SGX_SSL. Notice: by default the project builds in hardware-mode SGX, SGX_MODE=HW, and users can explicitly opt for building in simulation-mode SGX, SGX_MODE=SIM. In order to set non-default values for install location, or for building in simulation-mode SGX, you can override the default values by defining the corresponding environment variable, e.g., export SGX_MODE=SIM SGX_BUILD=DEBUG SGX_SSL=/my/sgx/ssl/install/.

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 defined, and
• docker (daemon & client) is properly set up for proxies as outlined in the Docker documentation for clients and the daemon. If you run Ubuntu 18.04, make sure you run docker 18.09 or later. Otherwise you will run into problems with DNS resolution inside the container.

Another problem you might encounter when running the sample scripts insofar that some '0.0.0.0' in fabric/sgxconfig/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'.

Time to get the code

Checkout the code and make sure it is on your GOPATH. (Important: we assume in this documentation and default configuration that your GOPATH has a single root-directoy!)

$ git clone https://github.com/hyperledger-labs/fabric-private-chaincode.git $GOPATH/src/hyperledger-labs/fabric-private-chaincode

Patch your Fabric

First we need to enable a Fabric peer to excute chaincode using our project. In Fabric you find a details described how to patch fabric and build the peer. Set FABRIC_PATH to the location of Fabric in your $GOPATH.

$ export FABRIC_PATH=${GOPATH}/src/github.com/hyperledger/fabric

Intel Attestation Service (IAS)

We use 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 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. The type of attestation used is selected based on the 'ECC_ATTESTATION_TYPE' environment variable: 'epid_unlinkable' for unlinkable or 'epid_linkable' for linkable signatures. If you do not define that environment variable, the chosen attestation method is 'epid_unlinkable'. Note that a mismatch between your IAS credentials and the linkable setting will result in an (HTTP) error '400' visible in the log-files when the code tries to verify the attestation. (Another cause for such error '400' could a mismatch between provided SPID and api key as specified below).

Place your ias api key and your SPID in the ias folder as follows:

echo 'YOUR_API_KEY' > ${GOPATH}/src/github.com/hyperledger-labs/fabric-private-chaincode/fabric/sgxconfig/ias/api_key.txt
echo 'YOURSPID' | xxd -r -p > ${GOPATH}/src/github.com/hyperledger-labs/fabric-private-chaincode/fabric/sgxconfig/ias/spid.txt

Get NanoPB

We use nanopb, a lightweight implementation of Protocol Buffers, inside the ledger enclave to parse blocks of transactions. Install nanopb by following the instruction below. For more detailed information consult the official nanopb documentation http://github.com/nanopb/nanopb.

$ export NANOPB_PATH=/path-to/install/nanopb/
$ git clone https://github.com/nanopb/nanopb.git ${NANOPB_PATH}
$ cd ${NANOPB_PATH}
$ git checkout nanopb-0.3.9.2
$ cd generator/proto && make

Make sure that you set $NANOPB_PATH as it is needed to build Fabric Private Chaincode.

Build the project

Now it's time to build the project. Just hit make and go grep a coffee. It may take a few moments when you build the project for the first time.

$ make

This will build all required components.

In utils/fabric-ccenv-sgx you can find instructions to create a custom fabric-ccenv docker image that is required to execute a chaincode within an enclave.

The chaincode enclave ecc_enclave and the ledger enclave tlcc_enclave can be build manually. Follow the instructions in the corresponding directories.

For the integration of the enclave code into a Fabric chaincode, please follow the instructions in ecc for the chaincode enclave and tlcc for the ledger enclave.

In order to run and deploy a chaincode enclave we need to build the enclave registry. See ercc.

Now we have all components we need to run the example auction chaincode in an enclave.

Run the example chaincode

Once you have successfully built the project you can play with the auction chaincode. Just follow the description in fabric.

References

• Marcus Brandenburger, Christian Cachin, Rüdiger Kapitza, Alessandro Sorniotti: Blockchain and Trusted Computing: Problems, Pitfalls, and a Solution for Hyperledger Fabric. https://arxiv.org/abs/1805.08541

Project Status

Hyperledger Fabric Private Chaincode operates as a Hyperledger Labs project. This code is provided solely to demonstrate basic Fabric Private Chaincode 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 ([email protected])
• Christian Cachin ([email protected])
• Rüdiger Kapitza ([email protected])
• Alessandro Sorniotti ([email protected])

Sponsor

Gari Singh ([email protected])

License

Hyperledger Fabric Private Chaincode source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file.