Skip to content

Commit d96033b

Browse files
byron-marohnbyron-marohn
committed
Initial Hyperledger Private Data Objects implementation
Signed-off-by: Byron Marohn <[email protected]> Signed-off-by: Abdulkareem Adesokan <[email protected]> Signed-off-by: Tom Barnes <[email protected]> Signed-off-by: Mic Bowman <[email protected]> Signed-off-by: Holly Harmon <[email protected]> Signed-off-by: Andrea Miele <[email protected]> Signed-off-by: Bruno Vavala <[email protected]> Signed-off-by: Eugene Yarmosh <[email protected]>
1 parent 00b113b commit d96033b

File tree

349 files changed

+47350
-52
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

349 files changed

+47350
-52
lines changed

‎BUILD.md

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
<!---
2+
Licensed under Creative Commons Attribution 4.0 International License
3+
https://creativecommons.org/licenses/by/4.0/
4+
--->
5+
# BUILD
6+
7+
In order to build, install, and run Hyperledger Private Data Objects, a number
8+
of additional components must be installed and configured. The following
9+
instructions will guide you through the installation and build process for
10+
Hyperledger Private Data Objects.
11+
12+
## Table of Contents
13+
14+
- [Prerequisites](#prerequisites)
15+
- [Installing Sawtooth Distributed Ledger](#sawtooth)
16+
- [Quickstart: Installing PDO Using Scripts](#quickstart)
17+
- [Building and installing PDO manually](#manual-install)
18+
- [Setting up a Python Virtual Environment](#virtualenv)
19+
- [Compiling the Common C++ Libraries](#common)
20+
- [Compiling the Python shared libraries](#python)
21+
- [Building the Enclave Service](#eservice)
22+
- [Building the Provisioning Service](#pservice)
23+
- [Building the Client](#client)
24+
- [Using Private Data Objects](#using)
25+
26+
# <a name="prerequisites"></a>Prerequisites
27+
Follow the instructions [here](PREREQUISITES.md) to install and configure
28+
components on which PDO depends.
29+
30+
# <a name="sawtooth"></a>Installing Sawtooth Distributed Ledger
31+
Hyperledger Private Data Objects uses the Hyperledger Sawtooth distributed
32+
ledger to store data object instances and state, and to guarantee update
33+
atomicity.
34+
35+
Application logic is implemented in Sawtooth through the use of Transaction
36+
Processors; transaction processors enable the distributed ledger to handle
37+
application requests. This repository contains the code required to build
38+
Transaction Processors that handle PDO requests.
39+
40+
Follow the setup document [here](sawtooth/docs/SETUP.md) to install both
41+
Sawtooth and the custom Sawtooth Transaction Processors.
42+
43+
Note that the Sawtooth components do not depend on any other components of the
44+
PDO project, and can be set up on an entirely separate machine from the one
45+
running Private Data Objects. It is recommended that Sawtooth be run on Ubuntu
46+
16.04 as it is the only operating system version on which Sawtooth is actively
47+
supported.
48+
49+
# <a name="quickstart"></a>Quickstart: Installing PDO Using Scripts
50+
The following section of this document describes manual compilation and
51+
installation instructions for Private Data Objects components. Following those
52+
steps is a good way to learn about the components of the project as you become
53+
an advanced user.
54+
55+
This section describes how to get started with PDO quickly using provided
56+
scripts to compile and install PDO.
57+
58+
First, make sure environment variables are set as described in the
59+
[prerequisites](#prerequisites) section.
60+
61+
The quickstart build will set up a python virtual environment to install things
62+
into. Set `CONTRACTHOME` to point to the target install directory for PDO
63+
components. You will need this environment variable set in every shell session
64+
where you interact with PDO.
65+
```
66+
export CONTRACTHOME=`pwd`/__tools__/build/_dev/opt/pdo
67+
```
68+
69+
Change to the quickstart build directory:
70+
```
71+
cd __tools__/build
72+
```
73+
74+
Edit `opt/pdo/etc/template/eservice.toml` and
75+
`opt/pdo/etc/template/pservice.toml` to have the correct ledger URL for your
76+
sawtooth installation.
77+
78+
Build the virtual environment and install PDO components into it:
79+
```
80+
make
81+
```
82+
83+
Activate the new virtual environment for the current shell session. You will
84+
need to do this in each new shell session (in addition to exporting environment
85+
variables).
86+
```
87+
source _dev/bin/activate
88+
```
89+
90+
Run the test suite to check that the installation is working correctly. Replace
91+
the URL with the URL for the rest-api of your Sawtooth installation.
92+
```
93+
cd ..
94+
LEDGER_URL=http://127.0.0.1:8008 ./run-tests.sh
95+
```
96+
97+
# <a name="manual-install"></a>Building and installing PDO manually
98+
## <a name="virtualenv"></a>Setting up a Python Virtual Environment
99+
The directories containing python code (`python`, `eservice`, `pservice`, and
100+
`client`) all create installable Python modules. You can install these to the
101+
root system's python if you want; however, the recommended approach is to
102+
create a new python "virtual environment" where they can be installed without
103+
affecting the root system.
104+
105+
Create a python virtual environment in the folder `venv` by running:
106+
```
107+
python3 -m venv venv
108+
```
109+
110+
Now activate that virtual environment for your current shell session. You will
111+
need to do this every time you start a new shell session:
112+
```
113+
source venv/bin/activate
114+
```
115+
116+
Now that the virtual environment is active, install the python libraries that
117+
Private Data Objects depends upon. NOTE: On Ubuntu 17.10 (and probably others)
118+
secp256k1 may not install correctly with pip. If this happens to you, try first
119+
installing your distribution's libsecp256k1-dev package via something like
120+
`sudo apt-get install libsecp256k1-dev` and then re-run the pip installation.
121+
```
122+
pip install --upgrade pip
123+
pip install --upgrade setuptools
124+
pip install --upgrade toml
125+
pip install --upgrade requests
126+
pip install --upgrade colorlog
127+
pip install --upgrade twisted
128+
pip install --upgrade pyyaml
129+
pip install --upgrade google
130+
pip install --upgrade protobuf
131+
pip install --upgrade secp256k1
132+
pip install --upgrade cryptography
133+
pip install --upgrade pyparsing
134+
```
135+
136+
If you are using this recommended virtual environment setup, you will also need
137+
to export the environment variable `CONTRACTHOME`. This is used by PDO to find
138+
configuration files and encryption keys. Set this variable in your current
139+
shell session with:
140+
```
141+
export CONTRACTHOME=`pwd`/venv/opt/pdo
142+
```
143+
144+
## <a name="common"></a>Compiling the Common C++ Libraries
145+
The `common` directory contains cryptography, encoding, and other miscellaneous
146+
routines used by many other components. Follow the build instructions
147+
[here](common/BUILD.md) to compile the common libraries.
148+
149+
## <a name="python"></a>Compiling the Python shared libraries
150+
The `python` directory contains shared python libraries/imports used by many
151+
other components. Much of the higher-level user logic of Private Data Objects
152+
is implemented in Python. The python directory includes a python SWIG wrapper
153+
of the common libraries, so common must be compiled prior to compiling the
154+
`python` directory.
155+
156+
Instructions for compiling and installing the python directory are available
157+
[here](python/BUILD.md).
158+
159+
## <a name="eservice"></a>Building the Enclave Service
160+
The Enclave Service (eservice for short) consists of two components:
161+
- A Software Guard Extensions "enclave" which runs the actual contract code
162+
- A python service wrapper (the eservice) which passes messages to and from the enclave
163+
164+
More information about the eservice is available
165+
[here](eservice/docs/eservice.md), and instructions for how to build it are
166+
[here](eservice/docs/BUILD.md).
167+
168+
## <a name="pservice"></a>Building the Provisioning Service
169+
The Provisioning Service (pservice for short) is a simple key/value store used
170+
to generate "secrets" which provision specific enclaves for use with specific
171+
contracts.
172+
173+
Instructions for how to build the provisioning service are available
174+
[here](pservice/docs/BUILD.md).
175+
176+
## <a name="client"></a>Building the Client
177+
The client directory contains several utilities for creating and executing
178+
contracts.
179+
180+
Instructions for how to build the client utilities service are available
181+
[here](client/docs/BUILD.md).
182+
183+
# <a name="using"></a>Using Private Data Objects
184+
See the main [USAGE](USAGE.md) document for information on how to test and
185+
use your Private Data Objects installation.

‎LICENSE

+115-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Apache License
1+
Apache License
22
Version 2.0, January 2004
33
http://www.apache.org/licenses/
44

@@ -199,3 +199,117 @@
199199
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200200
See the License for the specific language governing permissions and
201201
limitations under the License.
202+
203+
--------------------------------------------------------------------------------
204+
--------------------------------------------------------------------------------
205+
206+
The Hyperledger Private Data Object project contains open source components with
207+
separate copyright notices and license terms. Your use of the source code for
208+
the these components is subject to the terms and conditions of the following
209+
licenses.
210+
211+
--------------------------------------------------------------------------------
212+
--------------------------------------------------------------------------------
213+
parson
214+
215+
For project details see: https://github.com/kgabis/parson
216+
217+
MIT License
218+
219+
Copyright (c) 2012 - 2017 Krzysztof Gabis
220+
221+
Permission is hereby granted, free of charge, to any person obtaining a copy
222+
of this software and associated documentation files (the "Software"), to deal
223+
in the Software without restriction, including without limitation the rights
224+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
225+
copies of the Software, and to permit persons to whom the Software is
226+
furnished to do so, subject to the following conditions:
227+
228+
The above copyright notice and this permission notice shall be included in
229+
all copies or substantial portions of the Software.
230+
231+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
232+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
233+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
234+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
235+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
236+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
237+
THE SOFTWARE.
238+
239+
--------------------------------------------------------------------------------
240+
--------------------------------------------------------------------------------
241+
René Nyffenegger cpp-base64
242+
243+
For project details see: https://github.com/ReneNyffenegger/cpp-base64
244+
245+
Copyright © 2004-2017 by René Nyffenegger
246+
247+
This source code is provided 'as-is', without any express or implied
248+
warranty. In no event will the author be held liable for any damages
249+
arising from the use of this software.
250+
251+
Permission is granted to anyone to use this software for any purpose,
252+
including commercial applications, and to alter it and redistribute it
253+
freely, subject to the following restrictions:
254+
255+
1. The origin of this source code must not be misrepresented; you must not
256+
claim that you wrote the original source code. If you use this source code
257+
in a product, an acknowledgment in the product documentation would be
258+
appreciated but is not required.
259+
260+
2. Altered source versions must be plainly marked as such, and must not be
261+
misrepresented as being the original source code.
262+
263+
3. This notice may not be removed or altered from any source distribution.
264+
265+
266+
/*
267+
The original source code has been modified to be used with Private Data
268+
Objects (PDOs).
269+
*/
270+
271+
--------------------------------------------------------------------------------
272+
--------------------------------------------------------------------------------
273+
ELK
274+
275+
Copyright 1990, 1991, 1992, 1993, 1994, 1995, Oliver Laumann, Berlin(except for
276+
the contents of the directory `doc / usenix'). This software was derived from
277+
Elk 1.2, which was Copyright 1987, 1988, 1989, Nixdorf Computer AG and TELES
278+
GmbH, Berlin (Elk 1.2 has been written by Oliver Laumann (me) for TELES
279+
Telematic Services, Berlin, in a joint project between TELES and Nixdorf
280+
Microprocessor Engineering, Berlin). Oliver Laumann, TELES GmbH, and Nixdorf
281+
Computer AG, as co-owners or individual owners of copyright in this software,
282+
grant to any person or company a worldwide, royalty free, license to i) copy
283+
this software, ii) prepare derivative works based on this software, iii)
284+
distribute copies of this software or derivative works, iv) perform this
285+
software, or v) display this software, provided that this notice is not removed
286+
and that neither Oliver Laumann nor Teles nor Nixdorf are deemed to have made
287+
any representations as to the suitability of this software for any purpose nor
288+
are held responsible for any defects of this software. THERE IS ABSOLUTELY NO
289+
WARRANTY FOR THIS SOFTWARE. Berlin, June 20, 1995 Oliver Laumann
290+
291+
--------------------------------------------------------------------------------
292+
--------------------------------------------------------------------------------
293+
SLIB
294+
295+
SLIB LICENSE Each file in SLIB (over a dozen lines in length) is either in the
296+
public domain, or comes with a statement of terms permitting users to copy,
297+
modify, and redistribute it. The comments at the beginning each file (containing
298+
over a dozen lines) must specify its terms. For instance, the comments at the
299+
beginning of "Template.scm" declare that it is in the public domain: ;;;
300+
"Template.scm" configuration template of *features* for Scheme ;;; Author:
301+
Aubrey Jaffer ;;; ;;; This code is in the public domain. Each copyrighted file
302+
lists the names of the copyright holders and gives permissions to copy, modify,
303+
and redistribute the file. For instance, the beginning of "require.scm" states:
304+
;;;; Implementation of VICINITY and MODULES for Scheme ;Copyright (C) 1991,
305+
1992, 1993, 1994, 1997 Aubrey Jaffer ; ;Permission to copy this software, to
306+
modify it, to redistribute it, ;to distribute modified versions, and to use it
307+
for any purpose is ;granted, subject to the following restrictions and
308+
understandings. ; ;1. Any copy made of this software must include this copyright
309+
notice ;in full. ; ;2. I have made no warranty or representation that the
310+
operation of ;this software will be error-free, and I am under no obligation to
311+
;provide any services, by way of maintenance, update, or otherwise. ; ;3. In
312+
conjunction with products arising from the use of this ;material, there shall be
313+
no use of my name in any advertising, ;promotional, or sales literature without
314+
prior written consent in ;each case.
315+

0 commit comments

Comments
 (0)