hyperledger-labs / private-data-objects

The Private Data Objects lab provides technology for confidentiality-preserving, off-chain smart contracts.

Hyperledger Private Data Objects

Private Data Objects (PDO) enables sharing of data and coordinating action amongst mutually distrusting parties. Interaction is mediated through a “smart contract” that defines data access and update policies that are carried with the object regardless of where it resides or how often it changes hands. The smart contracts policies are enforced through execution in a Trusted Execution Environment (TEE).

PDO uses a distributed ledger, in this case the Microsoft Confidential Consortium Framework (CCF) distributed ledger, to ensure that there is a single, authoritative instance of the object, and to provide a means of guaranteeing atomicity of updates across interacting objects. PDO performs contract execution and storage off the blockchain, with only a hash of blockchain state stored on the distributed ledger. Currently, the PDO/CCF combo is restricted to simulated enclaves.

PDO provides benefits for both application developers seeking to define and implement privacy-preserving distributed ledgers, and for service providers seeking to provide blockchain services.

For the application developer, smart contracts implemented with PDO ensure that contract state is completely hidden from all participants, including contract validators, and allows contracts to be stored off-chain. Policies and data are bound up together in the PDO smart contract; polices travel with the data no matter how the smart contract object is shared or with whom. The PDO smart contact provides an enforceable agreement for multi-party data sharing and analytics.

For service providers, PDO provides scalable performance; separation of contract execution from ordering allows the performance of contract execution to scale with available hardware. Because PDO contract execution occurs off the blockchain, redundancy is limited to the applications requirements rather than the entire blockchain, providing fewer potential targets for compromise.

Please see the PDO Contracts open-source repository for sample smart contracts developed using the Private Data Objects framework. Our examples cover smart contracts for managing fungible and non-fungible assets, contracts that can be used to set up a fair exchange of assets among multiple parties, etc. Please use these sample contracts as guide to develop your own PDO smart contracts. We encourage you to share your use-cases including solution approaches to the PDO Contracts repository.

Documentation

Instructions for installing/building Hyperledger Private Data Objects can be found in the build documentation.

The usage document describes what you can do with a functional PDO installation.

For more information about how Private Data Objects work, see the specification document.

A paper with a more formal overview of Private Data Objects is available HERE.

A presentation about Private Data Objects is available HERE.

Project Status

Hyperledger Private Data Objects operates as a Hyperledger Labs project. This code is provided solely to demonstrate basic PDO mechanisms and to facilitate collaboration to refine PDO architecture and define minimum viable product requirements. The code provided in this repository is prototype code and not intended for production use.

Sponsor

Dan Middleton ([email protected])

License

Hyperledger Private Data Objects software is released under the Apache License Version 2.0 software license. See the license file for more details.

Hyperledger Private Data Objects documentation is licensed under the Creative Commons Attribution 4.0 International License. You may obtain a copy of the license at: http://creativecommons.org/licenses/by/4.0/.

private-data-objects's Issues

more robust service start

• move pgrep from various test scripts into *-start.sh (including adding it also to ss-start.sh where previously we did not have)
• add a test in es-start.sh when (maybe optionally/based on option) returns only once all services are up and running ...

Add a switch to the request and contract tests to specify the name of the save file to use for the contract.

Right now the multi-client tests successive clients overwrite the PDO file. This isn't really a problem (no adverse behavior).

Set commit worker threads as daemons

Currently, CTRL-C does not exit the commit threads (unless with explicit termination signals). Explicitly set the commit threads as daemons to exit these as well when the main thread terminates.

add python builds to Dockerfile

I've successfully followed your doc and could run the eservice python tests

test-contract.py
test-request.py
test-secrets.py

In order to have a development environment, I thought I'd extend your Dockerfile to include building the python stuff up to running the tests above

Here's my try: https://github.com/encointer/encointer-sdk/raw/master/docker/Dockerfile.pdo-dev

Unfortunately I run into a supposed docker bug as the image grows indefinately during build (after building the "pdo/common" layer) until it fills up my partition. That bug is out of scope here, but do you have any plans in completing your Dockerfile.pdo-dev and yaml so developers could start to implement contracts directly?

Exchange documentation typeo

https://github.com/hyperledger-labs/private-data-objects/blob/master/contracts/exchange/docs/exchange.md
Red Marbles Player Association (RMPA) -- an oversight organization that tracks blue marble banks
should read
Red Marbles Player Association (RMPA) -- an oversight organization that tracks red marble banks

Update to IAS 5.0 spec authentication

• authentication is via API key retrieved from and https://api.portal.trustedservices.intel.com/products passed in Ocp-Apim-Subscription-Key instead of doing mutual auth TLS with registered X509 key.
• url changed from https://test-as.sgx.trustedservices.intel.com/attestation/sgx/v3 to https://api.trustedservices.intel.com/sgx/attestation/v3

Enclave/Provisioning Service BUILD.md documentation manual install needs updating

The current pservice/docs/BUILD.md and eservice/docs/BUILD.md both need to be updated to describe how to generate the relevant test-service public/private .skf key files needed to run the test.

They probably also need a once-over to find other steps that are unclear.

Update documentation to cover SGX HW configuration steps

There are bits and pieces in the documentation that covers the steps necessary to get HW support for the contract enclave. However, we don't have the same level of "cookbook" documentation that we attempt to provide for the rest of the packages. Need to include a "how to configure" document that is linked from the top level document (what you would do before you run build).

Implement authenticated service shutdown

Authentication mechanism for shutting down the storage, enclave and provisioning services; this should probably take the form of a signed nonce where the authorized key is stored in the service configuration file.

Add a switch to the request and contract tests that sets the timeout for enclave requests.

For testing purposes, we should be setting the timeout very high so that even slow systems won't timeout and break the tests.

Incorporate a database of enclave services

Right now, enclave service URLs are included in the client configuration files. This works fine if those URLs are connected to a single contract and that is the only contract that will be used in the client. A better approach would be to implement a client-side database of enclave services that could be queried for enclaves listed in the .pdo description of a contract.

Remove the root block from the Sawtooth transaction.

There is no particular value in pushing it with the storage service replication policy. That is, the root block is just another block.

Eservice Database improvements

1. make sure that all tests run without any default database (currently the shell tests fail if there is no database, and if the pcontract.toml file has eservice name entries)

2. Make the eservice-id as the primary key for entries in the database.

Add eservice URLs to the PDO file

The PDO file currently contains the identities for all provisioned enclaves. While useful for verifying the information in the PDO file, enclave identities are not resolvable. We need to add the URLs for the eservices that host the provisioned enclaves. The URLs are, in some sense, a hint that must be verified.

Enclave Service Documentation conflicting descriptions

The powerpoint https://docs.google.com/presentation/d/16V0kK9M_z86WwI-PfdltY5plXnkOdFuK84sWFaExH_k/edit#slide=id.p14 says
"Enclave service takes care of registering/revoking/updating enclaves"

The
https://github.com/hyperledger-labs/private-data-objects/blob/master/eservice/docs/eservice.md
says
"The contract enclave service is an HTTP server that passes messages between a client and a contract enclave."
Confusing ?

upgrade to sgx sdk >= v2.4

Better handling of IAS v3 extensions

IAS v3 handled new return status CONFIGURATION_NEEDED and additional headers "Advisory-URL" and "Advisory-IDs". The advisory-* headers should give pointers on how to address these errors (e.g., CONFIGURATION_NEEDED might appear now due to L1TF if HT is enabled). Probably a good idea to also handle other error messages by at least passing them explicitly into logs rather than just a generic error message?

Documentation Usage Auction link Broken

In https://github.com/hyperledger-labs/private-data-objects/blob/master/USAGE.md
the link to Auction is broken
Currently
https://github.com/hyperledger-labs/private-data-objects/blob/master/contracts/auction/auction.scm

Maybe it should be ?
https://github.com/hyperledger-labs/private-data-objects/blob/master/contracts/auction/integer-key-auction.scm

document procedure to set PDO_LEDGER_KEY and PDO_IAS_KEY

we describe "what" these are but don't really provide any help with information on how to set them.

Fix race condition on directory creation for contracts

When two clients run on the same host there is a possibility that they will simultaneously attempt to create the contract_cache and state_cache directories. This shows up mostly when doing multi-client performance tests and is therefore extremely low priority.

The simple solution for this problem is to create these directories when the PDO_HOME directory structure is first created and to make sure the directories are created prior to running the multi-client tests (e.g. in run-test-perf.sh).

eservice hangs when ledger does not respond on registration

if the ledger does not respond to a registration request, the eservice stays up but never starts listening to the designated port.
Problem should lie below the transaction submitter code.

Update the sample configuration files

eservice/etc/sample_eservice.toml
eservice/etc/sample_sservice.toml
pservice/etc/sample_pservice.toml
client/etc/sample_client.toml

Add pgrep sservice in run-tests

Currently in run-tests.sh, we only grep for eservice and pservice a the start of the test. We should grep for sservice as well before starting new services.

Plans to docker-ize PDO?

Are there limitations?

Occasional failure during run-tests.sh within docker : 10 instead of 11

make test within docker folder fails sometimes. The failure happens during execution of run-tests.sh. Specifically, the issue was seen in PR177, but @g2flyer has seen it before. The failure is random, run-tests.sh executes successfully when repeated. The failure occurred during pdo-update with mock-contract. Twice, the test crashed when updating from 10 to 11. Logs as follows:

run-tests.sh: run unit tests for python, common, contracts and eservice
run-tests.sh: run unit tests for python package
run-tests.sh: run unit tests for common library
run-tests.sh: run unit tests for eservice
run-tests.sh: run unit tests for contracts
run-tests.sh: start enclave and provisioning services
run-tests.sh: start tests without provisioning or enclave services
run-tests.sh: start request test
run-tests.sh: start request test with tampered block order, this should fail
[02:20:59 ERROR pdo.eservice.pdo_helper] send_to_contract failed; <class 'ValueError'>, ('',)
[02:20:59 WARNING pdo.contract.request] contract invocation failed;
[02:20:59 ERROR pdo.test.request] enclave failed to evaluation expression; contract invocation failed
run-tests.sh: start integer-key contract test
run-tests.sh: start mock-contract contract test
run-tests.sh: start key value store test
run-tests.sh: start memory test
run-tests.sh: start tests with provisioning and enclave services
run-tests.sh: start storage service test
run-tests.sh: start request test
run-tests.sh: start integer-key contract test
run-tests.sh: start key value store test
run-tests.sh: start memory test
run-tests.sh: start pdo-create and pdo-update tests
run-tests.sh: create the contract
export CONTRACTID=jbTnMy/ePC2Enotii9GOg7RFcW5UsLb5pvgT4qKyWC0=
run-tests.sh: increment the value with a simple expression 15 times, querying enclaves in round robin
run-tests.sh: contract has the wrong value (10 instead of 11) for enclave 3
run-tests.sh: shutdown services
Makefile:79: recipe for target 'test-with-no-build' failed
make: *** [test-with-no-build] Error 111

Replace the secret wrapper in tests

In the test procedures (test-secrets, test-request and test-contract) replace the secrets helper with a wrapper for the provisioning service enclave like what we already do for the contract enclave.

Documentation improvement PdoProvisioningKeyToStateSecretMap in cregistry.md

Documentation improvement in
(https://github.com/hyperledger-labs/private-data-objects/blob/master/sawtooth/docs/cregistry.md)

Add a Link to PdoProvisioningKeyToStateSecretMap
(https://github.com/hyperledger-labs/private-data-objects/blob/master/python/sawtooth/pdo_protos/protobufs/pdo_contract_registry.proto)
or
Actually add copy of what is in the .proto file

message PdoProvisioningKeyToStateSecretMap {
    // Public key generated by the provisioning services
    string provisioning_service_public_key = 1;

    // An encrypted contract secret generated by the provisioning service
    string provisioning_contract_state_secret = 2;

    // Index defining the enclave info ordering for signing
    int32 index = 3;
}

Ideally the wiki for each Transaction family .md file would have url to the relevant .proto file in the git

possible memory leak in enclave's contract state object

There is a possible memory leak in

private-data-objects/eservice/lib/libpdo_enclave/contract_state.cpp

Line 87 in 51e0184

state_ = new pdo::state::Interpreter_KV(input_block_id_, state_encryption_key_);

as the dynamically allocated interpreterKV object may not be deleted when an exception is thrown.
Note however that the interpreterKV object is deleted in the contract_state destructor.

Quick fix: add a delete in the exception handling block.
Slow fix: remove the "new" instruction, by making two constructors: one for contract initialization (which integrates the initialize function) and another for contract update (which integrates the unpack function)

STARTER TASK: implement a blind auction contract for the exchange suite

The exchange contract suite is a (mostly) complete implementation of a multi-asset ledger. The representation of asset ownership is sufficiently general that many different kinds of exchanges could be developed. Currently, we have only implemented a simple fair exchange. We should port the blind auction that is implemented as the test suite for integer key.

more clearly separate the build time and run time configuration in the docs and scripts.

Add garbage collector for the client state cache.

This might take the form of a simple service. The advantage of that approach is that we could add a script for a client to replicate state based on commitments to the ledger for subscribed contracts.

Ensure that only one secret comes from each registered provisioning service

A provisioning service may generate multiple secrets for a given PSPK. While this is not correct behavior it shouldn't represent a security problem.

Check for duplicate PSPK's in the contract enclave to catch this situation.

Eservice tests use duplicate contract code

testrequest for example has its own version of the intkey contract, rather than loading the compiled version from the contracts directory.

remove state from the contract_response object

PR #206 removes state from the contract_request class. this makes perfect sense since we are no longer passing state in the request but the hash. similarly, we can remove state from the response since the blocks are pushed to the storage service on finalize and all that is needed for the response is the hash. this will allow the state object to be deallocated sooner.

simplify default pdo sgx key folder and description

currently we have sgx_simulation and sgx_hardware_mode for the PDO SGX keys,
By setting the default to ${PDO_SOURCE_ROOT}/build/keys/${SGX_MODE}/, this would simplify the description -- and it's a better name

Prevent contract creator from provisioning other enclaves.

This will require changing the registration transaction for Sawtooth to take a list of enclaves and then will require it to reject provisioning keys for any other enclaves. The provisioning service should also check to make sure that requesting enclaves are in the ledger.

Documentation for Commit Modules

Add documentation for new created commit modules. (replication and asynchronous transaction submission)

Create common service control scripts

We have start, stop and status scripts for provisioning, enclave and storage services. These are all roughly the same shell script. It would be nice to have a more general mechanism for starting and stopping the services.

Modify pdo-shell to enable asynchronous commits

While the new commit modules are integrated into the PDO shell, the shell commits synchronously. Modify the shell to enable asynchronous commits. The following series of steps is one way to accomplish this:

1. make wait_for_commit a separate shell command.
2. Add a provision to specify commit dependencies as input to send command.
3. Return commit_id after send command back to shell so as to use as input commit_dependency in a future send command

move contract state off-ledger to IPFS

Currently, PDO stores the contract state on the ledger. For the sake of avoiding ledger-bloat, I suggest to commit ledger state updates to IPFS and only commiting the IPFS hash to the ledger. Enclave services can then retrieve the latest state hash from the ledger and lookup the actual state on IPFS.

What are the dev's thoughts on this?

PDO tp context.get_state error

Hi ,

I get this following error/warning with PDO transaction processor when running enclave register with simulated proof data.

unexpected exception occurred on context.get_state([0b936fca070f54db6c0a03e3df66dbae0428e27f1bd93a08c8708b455be5ab70fbfd66])

STARTER TASK: document pdo-shell

The pdo-shell is implemented in client/pdo/client/controller/contract_controller.py. The shell is a relatively simple shell for interacting with PDO contracts. Among other capabilities, it allows for contract-specific plugins to be developed to simplify invocation of complex methods.

The pdo-shell is, at this point, exclusively "self-documenting" (all commands support a "help" option). We need to complete documentation for the pdo-shell.

Set replication parameters during create contract using pdo-shell

Currently, the pdo-shell create command does not set replication parameters as specified via pcontract.toml. (replication parameters is set to default values specified in the code). Add this functionality.

integer-key contract unittest fails

I've tried to run integer-key unit tests like this

cd contracts
make debug
cd integer-key
export LD_LIBRARY_PATH=<PDO path>/common/build
tinyscheme _debug_integer-key.scm 

resulting in

ERROR: (_debug_integer-key.scm : 241) open-input-string: argument 1 must be: string; 

funny enough, that file has 240 lines.

similar error for auction contract:

Auction is primed
Initial bids submitted
Error: (_debug_auction.scm : 260) open-input-string: argument 1 must be: string 
Errors encountered reading _debug_auction.scm

line 260 reads:

(display "Bids updated\n")

Is this the official way to run unit tests at all? Is there any doc on how to unit test contracts?

Resolve the usage of "wait" parameter used in commit

Prior to the new commit modules, transaction submission had a wait parameter (usually we set it to 30s) which kind of ensured that we proceeded to the next step only after the transaction completed. Precisely, after submitting a transaction to sawtooth, the client waits for at least 30s for the transaction to complete. If the transaction does not complete within 30s, the client simply moves on to the next step. (of course, the next step will fail it there is a dependency of completion of the last transaction).

In the new commit module, currently the commit_async() method takes a wait parameter as input, and this wait is the "same old wait" who meaning is described above. However, this is perhaps not a correct way to pass the "old wait parameter" to the new commit_async() method.

Fix this.

SGX attestation verification

We are not verifying - in pservice during secret provisioning and in eservice during enclave registration - all report fields for attestations, in particular we are not looking at the debug flag and (less crucially) the mode bit which has security implications:

• An enclave with the debug flag (SGX_FLAGS_DEBUG / 0x0000000000000002ULL in the report's attribute) turned on would enable an adversarial host of an enclave to see all enclave data and change it's behavior. So in secure mode a verification of the attestation, e.g., at enclave registration, should ensure this bit is 0.
• The mode flag (SGX_FLAGS_MODE64BIT / 0x0000000000000004ULL in the report's attribute) determines whether the enclave runs in 32-bit and 64-bit mode, correspondingly changing the semantics of a given measurement (MR_ENCLAVE). While tricky to achieve, it could be in theory to have code which runs in both 32-bit and 64-bit mode but exhibits completely different (and potentially adversarial) behavior. Hence to be on the safe side and as our code always is supposed to run only in 64-bit mode we should ensure that this flag is 1.

Create a common client utility module or package

Several common methods used by the client in test-request, test-cotract, pdo-udpate, pdo-create, pdo-shell. We can collect all of these in a common client utility module or package.

contract creator can provision his own enclaves

provisioning services check that the enclave is registered, but not that it can run a specific contract.
So creator can provision his own enclaves, which can access the state and invoke methods, though they cannot produce anything that can be committed -- because they are not registered with the contract.

Private Data Objects (PDO) Not be confused with Private Data Collection in Fabric

Was having a discussion on private data object (PDO) with one of my colleagues when he thought I was referring to private data collection in Fabric v1.2. It is only a small difference (object vs collection)

https://hyperledger-fabric.readthedocs.io/en/release-1.2/private-data/private-data.html

Any idea if we can differentiate private data objects (PDO) further?

Nathan Aw (Singapore)

Add failure tests for the new commit modules

Add tests that check failure conditions for the new commit modules - like unsupportable replication parameters etc.