Skip to content

Latest commit

 

History

History
256 lines (195 loc) · 11.8 KB

README.md

File metadata and controls

256 lines (195 loc) · 11.8 KB
Raw

Microsoft CCF based PDO Transaction Processor

This folder contains software for PDO transaction processor (TP) based on Microsoft's CCF blockchain. The software is located under ${PDO_SOURCE_ROOT}/ledgers/ccf/. The TP software is written and tested for CCF tag 4.0.1. Compatibility with other CCF versions is not guaranteed. We support PDO enclaves working in both SIM and HW SGX mode. For HW mode, we assume EPID attestation. CCF TP enclave will work in SIM (virtual) enclave mode in both cases.

The instructions below can be used to build and deploy the CCF-based PDO TP. The PDO TP uses many of environment variables defined in the PDO configuration script common-config.sh. We recommend that you read the PDO environment variables documentation first.

In some circumstances you may wish to override the default values of the variables for the PDO TP.

  • PDO_HOSTNAME : the name of host interface used to access the TP; typically this would be set to localhost for local testing or the external name of the host to provide network access.

  • PDO_LEDGER_KEY_ROOT : the directory where PDO TP keys will be created; if you are only running the PDO TP on a server you may find it easier to point this to a directory in the CCF tree such as ${PDO_HOME}/ccf/keys.

In addition, the PDO TP assumes that the environment variable CCF_BASE points to the directory where CCF is installed.

IMPORTANT: When installing CCF and PDO on the same VM for local testing, please install PDO first and then CCF. See PDO docs for detailed instructions on installing PDO.

Install CCF

Please follow instructions at https://microsoft.github.io/CCF/main/build_apps/install_bin.html to install CCF. Below, we provide a quick summary of the steps to install CCF version 4.0.1 on bare metal with SGX simuation mode.

Please set CCF_BASE to `/opt/ccf.

export CCF_BASE=/opt/ccf_virtual/

For installing dependencies, download the CCF repo, change branch to ccf-4.0.1 and execute the following commands:

git clone https://github.com/microsoft/CCF.git
cd CCF/
git checkout ccf-4.0.1
cd getting_started/setup_vm/
./run.sh app-dev.yml --extra-vars "platform=virtual" --extra-vars "clang_version=15" --extra-vars "ccf_ver=4.0.1"

Note that CCF needs to be installed only on the machine where PDO TP is being installed. CCF is not required by PDO clients to use a CCF based PDO TP.

Build and Install PDO TP

PDO TP requires certain sgx header files for IAS atteastion report verification. To ensure that these are present in your system, run the following command:

sudo apt-get install -y sgx-aesm-service libsgx-urts libsgx-uae-service

To build the PDO TP the PDO environment variables must be set. See the PDO configuration script common-config.sh for more information. Specifically, if operating PDO in HW mode, ensure that SGX_MODE env variable is set to HW before building PDO TP, so that PDO TP will enforce submission of valid attestation reports while processing enclave registration rpcs.

To build and install the PDO TP,

source ${PDO_SOURCE_ROOT}/build/common-config.sh
cd ${PDO_SOURCE_ROOT}/ledgers/ccf
make clean
make

Please note that while installing CCF, a pip dependency related ERROR regarding cryptography package may show up. However, we believe currently that this does not affect either the installation or PDO/CCF execution. Please report if your experience is different. Further, we beleive the ERROR is realted to the issue discussed at pyca/cryptography#6548.

Configure

See the CCF documentation for information about configuring CCF. The cchost configuration file used by the PDO control scripts can be found at ${PDO_HOME}/ccf/etc/cchost.toml. The CCF governance script can be found at ${PDO_HOME}/ccf/etc/constitution.js. We note that this governance script is the based on default governance scripts found as part of the CCF repo.

Start/Stop CCF Network

You can start a new CCF network with the PDO transaction processor using the following commands:

source ${PDO_HOME}/ccf/bin/activate
${PDO_HOME}/ccf/bin/start_ccf_network.sh

The above script will start the first node in the CCF network, open the network, add the user account that will be used for other PDO transactions, and generate the ledger authority key. The ledger authority key will be stored in the file ${PDO_LEDGER_KEY_ROOT}/ledger_authority_pub.pem. This key can be used to verify claims about the state of the ledger.

Note that a CCF network must run continuously; it cannot be fully stopped and restarted. Directions for adding additional nodes will be forthcoming.

The script ${PDO_HOME}/ccf/bin/stop_cchost.sh can be used to stop the instance of cchost running on the local server. When the final instance of cchost terminates, the ledger will be irretrievably terminated.

Share CCF (TLS) Authentication Keys

CCF uses mutually authenticated TLS channels for member transactions. User transactions use one-way TLS (pdo clients remain anonymous while submitting transactions to CCF). CCF member keys and network certificate are located at ${PDO_HOME}/ccf/keys. The network certificate ('networkcert.pem`) is created as part of CCF deployment and is unique to the specific instance of CCF.

Test the Deployment with Ping Test

PDO TP contains a simple ping rpc that returns success every time it is queried. Test the PDO TP deployment using this rpc. Invoke the following commands to issue 100 ping rpcs. The net througput is reported at the end of the test.

source $PDO_HOME/ccf/bin/activate
${PDO_SOURCE_ROOT}/ledgers/ccf/scripts/ping_test.py --url ${PDO_LEDGER_URL} --cert ${PDO_LEDGER_KEY_ROOT}/networkcert.pem

While invoking the test from a remote machine, be sure to 1) copy the CCF keys from the directory pointed to by the environment variable PDO_LEDGER_KEY_ROOT on the server where the transaction processor is running to the directory pointed to by PDO_LEDGER_KEY_ROOT on the client host, and 2) set PDO_LEDGER_URL to http://ccf-ip-address:6600, where ccf-ip-address is the IP address associated with the host name where CCF listens (see PDO_HOSTNAME above).

Generate Ledger Authority Key

Responses to read-transactions include a payload signature, where the signature is generated within PDO TP. The required signing keys must be generated before PDO TP can be opened up for business from PDO clients. This will be done automatically if you start the CCF network with the script ${PDO_HOME}/ccf/bin/start_ccf_network.sh.

Otherwise, you may invoke the following commands to generate and save the ledger authority key.

${PDO_HOME}/ccf/bin/generate_ledger_authority.py
${PDO_HOME}/ccf/bin/fetch_ledger_authority.py

If successful, the rpc returns after 1) creating one set of signing keys locally within the CCF enclave, and 2) scheduling them for global commit. The ledger authority verifying key can be obtained using the get_ledger_verifying_key rpc. The verifying key is returned only after global commit is successful.

The read-payload-signature feature may be used by PDO clients to establish offline verifiable proof of transaction commits as desired by the PDO smart contract application. Note that for trust purposes, it is recommended that any entity that uses the verifying_key gets it directly from the CCF service using the get_ledger_verifying_key rpc.

Using CCF ledger using PDO

We highlight some quick details about how PDO clients can use a CCF based PDO TP deployment. The information below can be found at PDO docs as well.

  1. Set the following environment variables:
export PDO_LEDGER_TYPE=ccf
export PDO_LEDGER_URL=http://ccf-ip-address:6600

As noted above ccf-ip-address is the IP address associated with the host named in the variable PDO_HOSTNAME (see above) during CCF deployment.

  1. Ensure that the PDO TP netwrok certificate networkcert.pem is stored in the directory ${PDO_LEDGER_KEY_ROOT}.

  2. Do a clean build of PDO (if installing on the same VM CCF is installed, this will wipe out CCF, so as noted above install PDO first and then CCF)

cd ${PDO_SOURCE_ROOT}/build
make clean
make

A clean build is an easy way to ensure updated creation of config files and PDO keys that are compatible with CCF. Alternatively, the overhead of a clean build can be avoided by executing the following two commands (in place of make clean) if the intention is to switch between PDO ledgers.

source ${PDO_SOURCE_ROOT}/build/common-config.sh
make -C ${PDO_SOURCE_ROOT}/build force-conf keys
  1. Run unit tests
cd ${PDO_SOURCE_ROOT}/build
make test

CCF TP TEE attestation verification policy

We briefly describe the attestation verification policy implemented by CCF TP.

  1. The TP contains a programmable flag that specifies whether the TP will check for PDO contract enclaves' attestation when eservices attempt registering PDO enclaves with TP. The CCF TP governance consortium (see https://microsoft.github.io/CCF/release/4.x/governance/index.html) gets to set the flag after the TP is started. The flag can be set only once.

  2. If the flag described above is set, then it is expected that the CCF TP governance consortium further programs the TP with expected values required to verify enclave attestation reports. We note that PDO currently supports EPID attestation verification, and while running in SGX HW mode, the eservice submits IAS attestation report to the TP as part of contract enclave registration with TP. To help the TP verify the IAS attestation report, the TP must be programmed with the following SGX-defined expected values:

  • MREnclave, a unique identifier of the contract enclave code;
  • basename, which contains (and is directly derived from) the SPID in EPID attestations;
  • ias_public_key, which is the IAS public key for verifying attestation reports. At contract enclave registration time, the TP verifies that an attestation report is correctly signed by IAS and includes the expected values. Further, the CCF TP governance consortium is permitted to change the values of these parameters, subject to TP consortium governance rules.

The TP provides two APIs set_attestation_check_flag and set_expected_sgx_measurements to program the various values required to implement the above attestation verification policy.

  1. The first API set_attestation_check_flag accepts as input a boolean value (indicating whether to check attestation reports or not). It is meant to be called when the CCF network starts up. It must be called before enclave registrations and before the second API and only once.

A convenience script ccf_set_attestation_check_flag is provided to invoke this API. The script requires a CCF endpoint and the --attestation or --no-attestation argument.

The script for starting the CCF network in PDO automates the call to the script above, setting the check-attestation-flag based on whether PDO runs in SGX HW mode or SGX SIM mode.

  1. The second API set_expected_sgx_measurements accepts as input the MREnclave, the basename and the IAS public key values. It is meant to be called by the first eservice who will register enclaves. If the previous API was called to require attestation checks, then this API must be called; otherwise, it may, or may not, be called.

A convenience script ccf_set_expected_sgx_measurements is provided to invoke this API. The script requires a CCF endpoint and the --mrenclave, --basename and --ias-public-key arguments.

The script for starting services in PDO contains an optional argument (--register) which automates the call to the script above. This allows an eservice running in SGX HW mode to register/set the policy/arguments with the PDO TP.