Skip to content

S
sgxwallet
Unverified Commit cfcfbb5f authored by Chadwick Strange's avatar Chadwick Strange Committed by GitHub
Browse files
Options

Merge pull request #56 from skalenetwork/enhancement/documentation 

Enhancement/documentation
parents 5fd5d025 41acaebb
Hide whitespace changes
Inline Side-by-side
Showing with 730 additions and 322 deletions
.github/CONTRIBUTING.md 0 → 100644
View file @ cfcfbb5f
# Contributing
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
Feedback and contributions are very welcome!
Here's help on how to make contributions, divided into the following sections:
- general information,
- documentation changes,
- code changes, and
- keeping up with external changes.
## General information
For specific proposals, please provide them as
[pull requests](https://github.com/skalenetwork/sgxwallet/pulls)
or
[issues](https://github.com/skalenetwork/sgxwallet/issues)
via our
[GitHub site](https://github.com/skalenetwork/sgxwallet).
For general discussion, feel free to use
[![Discord](https://img.shields.io/discord/534485763354787851.svg)](https://discord.gg/vvUtWJB)
### Pull requests and different branches recommended
Pull requests are preferred, since they are specific.
For more about how to create a pull request, see
<https://help.github.com/articles/using-pull-requests/>.
We recommend creating different branches for different (logical)
changes, and creating a pull request when you're done into the master branch.
See the GitHub documentation on
[creating branches](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/)
and
[using pull requests](https://help.github.com/articles/using-pull-requests/).
### How we handle proposals
We use GitHub to track proposed changes via its
[issue tracker](https://github.com/skalenetwork/sgxwallet/issues) and
[pull requests](https://github.com/skalenetwork/sgxwallet/pulls).
Specific changes are proposed using those mechanisms.
Issues are assigned to an individual, who works it and then marks it complete.
If there are questions or objections, the conversation area of that
issue or pull request is used to resolve it.
### Two-person review
Our policy is that at least 50% of all proposed modifications will be reviewed
before release by a person other than the author,
to determine if it is a worthwhile modification and free of known issues
which would argue against its inclusion
(per the Gold requirement two_person_review).
We achieve this by splitting proposals into two kinds:
1. Low-risk modifications. These modifications are being proposed by
people authorized to commit directly, pass all tests, and are unlikely
to have problems. These include documentation/text updates
(other than changes to the criteria) and/or updates to existing gems
(especially minor updates) where no risk (such as a security risk)
have been identified. The project lead can decide that any particular
modification is low-risk.
2. Other modifications. These other modifications need to be
reviewed by someone else or the project lead can decide to accept
the modification. Typically this is done by creating a branch and a
pull request so that it can be reviewed before accepting it.
### Contributor License Agreement (CLA)
All contributions must agree to the
[SKALE Network Contributor License Agreement](https://cla.skale.network).
This is derived from Apache Software Foundations’ Individual Contributor License
Agreement v2.0, and it's purpose is to ensure that the guardian of a project's
outputs has the necessary ownership or grants of rights over all contributions
to allow them to distribute under the chosen license.
Simply submitting a contribution implies this agreement, however,
for a pull request to be accepted, you must use the
[SKALE Network CLA assistant](https://cla.skale.network), which
is one of the requirement for pull request checks.
### License (AGPL)
All (new) contributed material must be released
under the [AGPL-3.0-only license](./LICENSE), with exception to material included
under the `third_party` directory.
All new contributed material
that is not executable, including all text when not executed,
is also released under the
[Creative Commons Attribution 3.0 International (CC BY 4.0) license](https://creativecommons.org/licenses/by/4.0/) or later.
### We are proactive
In general we try to be proactive to detect and eliminate
mistakes and vulnerabilities as soon as possible,
and to reduce their impact when they do happen.
We use a defensive design and coding style to reduce the likelihood of mistakes,
a variety of tools that try to detect mistakes early,
and an automatic test suite with significant coverage.
We also release the software as open source software so others can review it.
Since early detection and impact reduction can never be perfect, we also try to
detect and repair problems during deployment as quickly as possible.
This is _especially_ true for security issues; see our
[security information](docs/security.md) for more.
### No trailing whitespace
Please do not use or include trailing whitespace
(spaces or tabs at the end of a line).
Since they are often not visible, they can cause silent problems
and misleading unexpected changes.
For example, some editors (e.g., Atom) quietly delete them by default.
## Documentation changes
Most of the documentation is in "markdown" or "mdx" format.
All markdown files use the .md filename extension, otherwise .mdx for mdx files.
Where reasonable, limit yourself to Markdown
that will be accepted by different markdown processors
(e.g., what is specified by CommonMark or the original Markdown)
In practice we use
the version of Markdown implemented by GitHub when it renders .md files,
and you can use its extensions
(in particular, mark code snippets with the programming language used).
This version of markdown is sometimes called
[GitHub-flavored markdown](https://help.github.com/articles/github-flavored-markdown/).
In particular, blank lines separate paragraphs; newlines inside a paragraph
do _not_ force a line break.
Beware - this is _not_
the same markdown algorithm used by GitHub when it renders
issue or pull comments; in those cases
[newlines in paragraph-like content are considered as real line breaks](https://help.github.com/articles/writing-on-github/);
unfortunately this other algorithm is _also_ called
GitHub rendered markdown.
(Yes, it'd be better if there were standard different names
for different things.)
Do not use trailing two spaces for line breaks, since these cannot be
seen and may be silently removed by some tools.
Instead, use <tt>&lt;br /></tt> (an HTML break).
## Code changes
### Code style and formatting
The code style is defined by `.clang-format`, and in general, all C++ files
should follow it. Files with minor deviations from the defined style are still
accepted in PRs; however, unless explicitly marked with `// clang-format off`
and `// clang-format on`, these deviations will be rectified any commit soon
after.
Exercise the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
where reasonable and appropriate. Prefer less-coupled cohesive code.
## How to check proposed changes before submitting them
Checking the code on at least one configuration is essential; if you only have
a hasty fix that doesn't even compile, better make an issue and put a link to
your commit into it (with an explanation what it is about and why).
### clang-format
We strongly recommend using clang-format or, even better, use an IDE that
supports it. This will lay a tedious task of following the assumed
code style from your shoulders over to your computer.
## Keeping up with external changes
The installer adds a git remote named 'upstream'.
Running 'git pull upstream master' will pull the current version from
upstream, enabling you to sync with upstream.
You can reset this, if something has happened to it, using:
```bash
git remote add upstream \
https://github.com/skalenetwork/sgxwallet.git
```
## Attribution
This text is based on CONTRIBUTING.md from CII Best Practices Badge project,
which is a collective work of its contributors (many thanks!). The text itself
is licensed under CC-BY-4.0.
README.md
View file @ cfcfbb5f
# sgxwallet: SKALE SGX-based hardware crypto wallet
[![Discord](https://img.shields.io/discord/534485763354787851.svg)](https://discord.gg/vvUtWJB)
## Intro
**sgxwallet** is a next generation hardware secure crypto wallet that is based on **Intel SGX** technology. It currently supports **Ethereum** and **SKALE**, and will support **Bitcoin** in the future.
......@@ -17,355 +18,49 @@ The administrator manually approves each registration.
## An important note about production readiness
The sgxwallet server is still in active development and therefore should be regarded as _alpha software_. The development is still subject to security hardening, further testing, and breaking changes. **This server has not yet been reviewed or audited for security.**
The sgxwallet server is still in active development and therefore should be regarded as _alpha software_. The development is still subject to security hardening, further testing, and breaking changes. **This server has not yet been reviewed or audited for security.** Please see [SECURITY.md](SECURITY.md) for reporting policies.
![Build, test and push sgxwallet container](https://github.com/skalenetwork/sgxwallet/workflows/Build,%20test%20and%20push%20sgxwallet%20container/badge.svg)
![Build, test and push sim mode container](https://github.com/skalenetwork/sgxwallet/workflows/Build,%20test%20and%20push%20sim%20mode%20container/badge.svg)
## Running sgxwallet
Table of Contents
=================
* [Running sgxwallet](#running-sgxwallet)
* [Clone this repository and its submodules](#clone-this-repository-and-its-submodules)
* [Try instantly in simulation mode](#try-instantly-in-simulation-mode)
* [Start, stop and upgrade sgxwallet](#start-stop-and-upgrade-sgxwallet)
* [Configure logging](#configure-logging)
* [Enable SGX on your machine](#enable-sgx-on-your-machine)
* [Enable "software-controlled" SGX](#enable-software-controlled-sgx)
* [Install SGX driver](#install-sgx-driver)
* [Run sgxwallet in secure SGX mode](#run-the-latest-sgxwallet-docker-container-from-dockerhub)
* [Development](#development)
* [Install Prerequisites](#install-prerequisites)
* [Install SGX sdk](#install-sgx-sdk)
* [Install required debian packages](#install-required-debian-packages)
* [Build dependencies](#build-dependencies)
* [Configure and build sgxwallet](#configure-and-build-sgxwallet)
* [Run sgxwallet](#run-sgxwallet)
* [Build Docker container](#build-docker-container)
* [Build Docker container in simulation mode](#build-docker-container-in-simulation-mode)
* [Run Docker container](#run-docker-container)
* [Run Docker container in simulation mode](#run-docker-container-in-simulation-mode)
* [Adding new source files](#adding-new-source-files)
* [Example of client certificate instantiation](#example-of-client-certificate-instantiation)
* [Libraries](#libraries)
* [License](#license)
# Running sgxwallet
## Clone this repository and its submodules
`git clone --recurse-submodules https://github.com/skalenetwork/sgxwallet.git`
## Try instantly in simulation mode
The easiest way to try the sgxwallet server is to run it in
insecure simulation mode that emulates an SGX processor. Once you are familiar with the server,
you can enable sgx on your machine and run it in secure production mode.
To try the server:
Install docker-compose if you do not have it.
```
sudo apt-get install docker.io docker-compose
```
And then do
```
cd run_sgx_sim;
sudo docker-compose up
```
Voila! You should see the "SGX Server started" message.
## Start, stop and upgrade sgxwallet
As any docker-compose application sgxwallet is super easy to use.
To run the server as a daemon, do
```
sudo docker-compose up -d
```
To stop/start the server do
```
sudo docker-compose stop
sudo docker-compose start
```
To view server logs do
```
sudo docker-compose logs
```
To upgrade sgxwallet to the latest version do
```
sudo docker-compose stop
sudo docker-compose pull
sudo docker-compose up
```
Note: all docker-compose commands need to be issued from run_sgx_sim directory.
Note: sgxwallet places all its data into the sgx_data directory, which is created the first time you run sgxwallet.
Do not remove this directory!
Note: sgxwallet operates on network ports 1026 (https) and 1027 (http for initial registration).
If you have a firewall on your network, please make sure these ports are open so clients are able to
connect to the server.
## Configure logging
By default, sgxwallet will log into default Docker logs, which are rotated into four files 10M each.
To send logs to an external syslog service, edit docker compose YAML file to specify logging configuration as
```
logging:
driver: syslog
options:
syslog-address: "tcp://SYSLOG_SERVER_IP:PORT"
```
See docker-compose documentation for more options.
## Enable SGX on your machine
Once your tried sgxwallet in the simulation mode, you can enable sgx on your machine, and run the server in production
mode. First, remove the simulation mode wallet by doing
```
sudo docker-compose rm
```
You'll need **Intel SGX** capable hardware. Most Intel chips that were produced after 2015 support **SGX**.
- Enter **BIOS** of your machine by pressing and holding **Del** or **F2** on boot-up and verify that **BIOS** includes **SGX options**.
If not, your machine cant run **SGX**.
- Set SGX in BIOS as `enabled` or `software-controlled`.
- If you can set SGX to `enabled` you are done! Proceed with "Install SGX Driver" section
- If not, set SGX in BIOS to `software-controlled` and then enable by running a sgx-enable utility, as described below.
## Enable "software-controlled" SGX
This repo includes the ***sgx_enable*** utility. To enable SGX run:
```bash
sudo ./sgx_enable
```
Note: if you are not using Ubuntu 18.04 (something that we do not recommend), you may need
to rebuild the sgx-software-enable utility before use by typing:
```bash
cd sgx-software-enable;
make
```
## Install SGX driver
```bash
cd scripts; sudo ./sgx_linux_x64_driver_2.5.0_2605efa.bin; cd ..
```
Reboot you machine after driver install. Do `ls /dev/isgx` to check that `isgx` device is properly installed.
If you do not see the `isgx` device, you need to troubleshoot your driver installation.
## Run sgxwallet in secure SGX mode
Run the latest sgxwallet docker container image in SGX mode
```
cd run_sgx;
sudo docker-compose up -d
```
You should see "SGX Server started message".
Note: on some machines, the SGX device is not `/dev/mei0` but a different device, such
as "/dev/bs0". In this case please edit `docker-compose.yml` on your machine to specify the correct
device to use.
# Development
## Install Prerequisites
```bash
sudo apt-get install build-essential make cmake gcc g++ yasm python libprotobuf10 flex bison automake libtool texinfo libgcrypt20-dev libgnutls28-dev
```
## Install SGX sdk
```bash
cd scripts; sudo ./sgx_linux_x64_sdk_2.5.100.49891.bin; cd ..
```
## Install required debian packages
```bash
cd scripts; sudo ./install_packages.sh; cd ..
```
## Build dependencies
Dependencies only need to be built once.
```bash
cd scripts; ./build.py; cd ..
```
### Try in simulation mode
## Configure and build sgxwallet
The easiest way to try the sgxwallet server is to run a docker container in insecure simulation mode that emulates an SGX processor. Once you are familiar with the server, you can enable sgx on your machine and run it in secure production mode.
Go to the project's top directory, then run
Get it with [Docker](https://www.docker.com/):
```bash
libtoolize --force
aclocal
autoheader
automake --force-missing --add-missing
autoconf
./configure
make
```
Note: to run in simulation mode, add --enable-sgx-simulation flag when you run configure.
$ docker pull skalenetwork/sgxwalletsim
```
./configure --enable-sgx-simulation
```
## Run sgxwallet
Type:
Then run:
```bash
source sgx-sdk-build/sgxsdk/environment;
./sgxwallet
```
## Build Docker container
$ docker run -it --network host --name sgxwalletsim skalenetwork/sgxwalletsim
```bash
sudo docker build -t sgxcontainer .
```
## Build Docker container in simulation mode
or for detached mode:
```bash
sudo docker build -t sgxcontainersim -f ./DockerfileSimulation .
```
$ docker run -di --network host --name sgxwalletsim skalenetwork/sgxwalletsim
## Run Docker container
```bash
sudo docker run -di --network host --device /dev/isgx --device /dev/mei0 --name sgxwallet sgxcontainer
```
This will run the server in a Docker container named sgxwallet
## Building
You can start and stop running sgxwallet container by doing
See [docs/building.md](docs/building.md).
```bash
docker stop sgxwallet
docker start sgxwallet
```
## Run Docker container in simulation mode
```bash
sudo docker run -di --network host --name sgxwalletsim sgxcontainersim
```
## Documentation
See [docs](docs) for sgxwallet documentation.
## Adding new source files
Note that `configure, Makefile` and `Makefile.in` files are created by `automake` tools on the fly.
Please do not add these files to the source tree!
To add new source and include files to app and enclave, edit the corresponding **Makefile.am** file and then re-run configure.
If you change **.edl** file, you need to re-run configure too.
## Example of client certificate instantiation
Go to the project's top directory, then run
```bash
export CSR_FILE=a.csr
export KEY_FILE=k.key
export CERT_NAME_UNIQUE=someVeryUniqueName
openssl req -new -sha256 -nodes -out $CSR_FILE -newkey rsa:2048 -keyout $KEY_FILE -subj /CN=$CERT_NAME_UNIQUE
cat $CSR_FILE
cat $KEY_FILE
export KEY_PEM_FILE=k.pem
openssl rsa -in $KEY_FILE -text > $KEY_PEM_FILE
cat $KEY_PEM_FILE
```
Next, send content of `a.csr` as single line (by replacing real end of lines with `\n`) to port `1027`.
Example:
```bash
export URL_SGX_WALLET="http://127.0.0.1:1027"
curl -X POST --data '{ "jsonrpc": "2.0", "id": 2, "method": "signCertificate", "params": { "certificate": "-----BEGIN CERTIFICATE REQUEST-----\nMIICYjCCAUoCAQAwHTEbMBkGA1UEAwwSc29tZVZlcnlVbmlxdWVOYW1lMIIBIjAN\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3C4ceRhzMAZnG87PwlkzMROHsm3B\ncPydIeiqs1dieuuvVETJqbXAcOENNsGA+AdXjZwFkDuIS24p2yZ8AwuIMAwdMsGa\n5Hzk0ugOy52iPyGEuooqV94nnL6eWw/zryTvkk7j239wMWn5our5Ia1/CBQlXXo2\n4IWTWfWYOz26SWUh4DuvzMOheMVSxg3KLaxpx7Bq09p32lR9xpl53+HqxSDIMYh9\nC3y3kA6NdkKsGE/Jt4WoZ5S5LlrhYjw+PFTeX2lbGDZpn/sxQIM16Pxo2LCfefIa\nik+aZBEAlpn22ljLZ5sEcVgBmOlL+v3waq9u0AaSYzdGFRA+0ceVwU/QTQIDAQAB\noAAwDQYJKoZIhvcNAQELBQADggEBAJXodL69Q/8zDt24AySXK0ksV3C3l5l10Hno\nfF6zKypsYev33CFbZu6HweSgK2f21+DeI9TsGKJxI7K6MUqyH0pJhwlFSeMB5/qP\nJueqXMuvStZSp0GGTaNy7Al/jzOKYNf0ePsv/Rx8NcOdy7RCZE0gW998B5jKb66x\nPgy6QvD8CkZULiRScYlOC8Ex6nc+1Z54pRC1NFWs/ugGyFgLJHy0J2gNkOv6yfsl\nH3V/ocCYSoF4ToUQAxwx+dcy4PXrL9vKzRNJgWzsI/LzCZkglo8iis9YZQawDOUf\nGmDMDkr0Fx1W1tSEpvkw0flkAXZ8PhIGCC0320jkuPeClt7OWNs=\n-----END CERTIFICATE REQUEST-----\n" } }' -H 'content-type:application/json;' $URL_SGX_WALLET
```
The above example produces on success:
```
{"id":2,"jsonrpc":"2.0","result":{"errorMessage":"","result":true,"status":0}}
```
Next, generate the client certificate signed by root ones:
```bash
cd cert
./create_client_cert
ls -1
cat client.crt
openssl x509 -inform PEM -in client.crt > client.pem
cat client.pem
cd ..
```
Finally, execute a test call such as importing BLS key.
Example:
```bash
export URL_SGX_WALLET="https://127.0.0.1:1026"
curl \
-X POST --data '{ "jsonrpc": "2.0", "id": 1, "method": "importBLSKeyShare", "params": { "keyShareName": "nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3C4ceRhzMAZnG87PwlkzMROHsm3B", "n": 2, "t": 2, "index" : 1, "keyShare": "21043165427057050523208250969869713544622230829814517880078280390613973680760" } }' -H 'content-type:application/json;' \
-v --cacert ./cert/rootCA.pem --key $KEY_PEM_FILE --cert ./cert/client.pem $URL_SGX_WALLET -k
```
The above example produces on success:
```
{"id":1,"jsonrpc":"2.0","result":{"encryptedKeyShare":"0400020000000000040effffff02000000000000000000000b000000000000ff0000000000000000cecb5d7bd507cb936464fdb6b88cfe80e38eae963af6a39b6b05cdfba5521c60000000f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000080000000000000000000000000000000875c0520e8d6739c440e0e5073633861769fc1d31d627e9a72c66d43871c62bce2cc48e821341e10784242c4c8aad6ca73a491cbf7453c2ff012b6b3d9d96823c0256992d9792ea60269789b2d51ae87c75fe522dbcb8053458c1bca421cbc57f4a58e4e5689d534ca0303db83c7a9e88cd23afe3a39e1a3801371c95e7ffa54e834c6be8853983dcaa1fa9f5e6959a5","errorMessage":"","status":0}}
```
## Contributing
If you change .edl file, you need to re-run configure too.
See [contributing](CONTRIBUTING.md) for information on how to contribute.
## Libraries
......
SECURITY.md 0 → 100644
View file @ cfcfbb5f
# Security
## Reporting a Bug
The SKALE community take all security bugs seriously to ensure the security of the SKALE Network.
You can report security bugs by emailing us directly at security@skalelabs.com.
## Comments on This Policy
If you have suggestions on how this process could be improved, please submit a pull request.
docs/README.md 0 → 100644
View file @ cfcfbb5f
# Sgxwallet Documentation
## Introduction
- [README.md](../README.md) Overview of sgxwallet
- [Getting Started](index.md)
- [Prerequisites for sgxwallet containers](prerequisites.md)
- [Enabling SGX](enabling-sgx.md)
- [Example sgxwallet certificate instantiation](examples.md#example-of-client-certificate-instantiation)
## Community
- [SKALE Discord](http://skale.chat)
## Source Code
- [Sgxwallet code repository](https://github.com/skalenetwork/sgxwallet)
- [Building source code](../building.md)
- [Example Usage](../examples.md)
- [Contributing source code](../.github/CONTRIBUTING.md)
- [Security Bug Reporting](../SECURITY.md)
docs/building.md 0 → 100644
View file @ cfcfbb5f
# Building the sgxwallet server
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
This document describes how to build sgxwallet on Ubuntu 18.04 systems. Currently, systems other than Ubuntu (such as Windows, MacOS, ...) are not currently supported.
## Clone this repository and its submodules
`git clone --recurse-submodules https://github.com/skalenetwork/sgxwallet.git`
## Install Prerequisites
```bash
sudo apt-get install build-essential make cmake gcc g++ yasm python libprotobuf10 flex bison automake libtool texinfo libgcrypt20-dev libgnutls28-dev
```
## Install SGX SDK
```bash
cd scripts; sudo ./sgx_linux_x64_sdk_2.5.100.49891.bin; cd ..
```
## Install required debian packages
```bash
cd scripts; sudo ./install_packages.sh; cd ..
```
## Build dependencies
Dependencies only need to be built once.
```bash
cd scripts; ./build.py; cd ..
```
## Configure and build sgxwallet
Go to the project's top directory, then run
```bash
libtoolize --force
aclocal
autoheader
automake --force-missing --add-missing
autoconf
./configure
make
```
Note: to run in simulation mode, add --enable-sgx-simulation flag when you run configure.
```bash
./configure --enable-sgx-simulation
```
## Build Docker container
```bash
sudo docker build -t sgxwallet_base .
```
## Build Docker container in simulation mode
```bash
sudo docker build -t sgxwalletsim -f ./DockerfileSimulation .
```
## Adding new source files
Note that `configure, Makefile` and `Makefile.in` files are created by `automake` tools on the fly.
Please do not add these files to the source tree!
To add new source and include files to app and enclave, edit the corresponding **Makefile.am** file and then re-run configure.
If you change **.edl** file, you need to re-run configure too.
docs/configuring.md 0 → 100644
View file @ cfcfbb5f
# Configuring sgxwallet server
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
## Docker Compose configuration
To try the server:
Install docker-compose if you do not have it.
```bash
sudo apt-get install docker.io docker-compose
```
And then do
```bash
cd run_sgx_sim;
sudo docker-compose up
```
Voila! You should see the "SGX Server started" message.
## Start, stop and upgrade sgxwallet containers
As any docker-compose application sgxwallet is super easy to use.
To run the server as a daemon, do
sudo docker-compose up -d
To stop/start the server do
sudo docker-compose stop
sudo docker-compose start
To view server logs do
sudo docker-compose logs
To upgrade sgxwallet to the latest version do
sudo docker-compose stop
sudo docker-compose pull
sudo docker-compose up
Note: all docker-compose commands need to be issued from run_sgx_sim directory.
Note: sgxwallet places all its data into the sgx_data directory, which is created the first time you run sgxwallet.
Do not remove this directory!
Note: sgxwallet operates on network ports 1026 (https) and 1027 (http for initial registration).
If you have a firewall on your network, please make sure these ports are open so clients are able to
connect to the server.
## Run sgxwallet in secure SGX mode
Run the latest sgxwallet docker container image in SGX mode
cd run_sgx;
sudo docker-compose up -d
You should see "SGX Server started message".
Note: on some machines, the SGX device is not `/dev/mei0` but a different device, such
as "/dev/bs0". In this case please edit `docker-compose.yml` on your machine to specify the correct
device to use.
## Logging
By default, sgxwallet will log into default Docker logs, which are rotated into four files 10M each.
To send logs to an external syslog service, edit docker compose YAML file to specify logging configuration as
```yaml
logging:
driver: syslog
options:
syslog-address: "tcp://SYSLOG_SERVER_IP:PORT"
```
See docker-compose documentation for more options.
docs/enabling-sgx.md 0 → 100644
View file @ cfcfbb5f
# Enabling SGX
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
To enable SGX on your machine, you'll need **Intel SGX** capable hardware. Most Intel chips that were produced after 2015 support **SGX**. Otherwise you can enable software-controlled SGX.
## Enable SGX on your machine
Once your tried sgxwallet in the simulation mode, you can enable sgx on your machine, and run the server in production mode.
1. Stop then remove the simulation mode sgxwallet containers either by doing
```bash
sudo docker-compose rm
```
> or
```bash
docker stop sgxwallet && docker rm sgxwallet
```
2. Enter **BIOS** of your machine by pressing and holding **Del** or **F2** on boot-up and verify that **BIOS** includes **SGX options**.
If not, your machine cannot run **SGX**.
3. Set SGX in BIOS as `enabled` or `software-controlled`.
4. If you can set SGX to `enabled` you are done! Proceed with "Install SGX Driver" section
5. If not, set SGX in BIOS to `software-controlled` and then enable by running a sgx-enable utility, as described below.
## Enable "software-controlled" SGX
This repo includes the **_sgx_enable_** utility. To enable SGX run:
```bash
sudo ./sgx_enable
```
Note: if you are not using Ubuntu 18.04 (something that we do not recommend), you may need
to rebuild the sgx-software-enable utility before use by typing:
```bash
cd sgx-software-enable;
make
```
## Install SGX driver
```bash
cd scripts; sudo ./sgx_linux_x64_driver_2.5.0_2605efa.bin; cd ..
```
Reboot you machine after driver install. Do `ls /dev/isgx` to check that `isgx` device is properly installed.
If you do not see the `isgx` device, you need to troubleshoot your driver installation.
docs/examples.md 0 → 100644
View file @ cfcfbb5f
# Example usage
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
## Run sgxwallet from build
Type:
```bash
source sgx-sdk-build/sgxsdk/environment;
./sgxwallet
```
## Run Docker container
Depending on whether you built a docker container or pulled it from docker hub, use the appropriate docker image name (e.g. sgxwallet_base, sgxwalletsim, ...) and execute:
```bash
sudo docker run -di --network host --device /dev/isgx --device /dev/mei0 --name sgxwallet <sgx-docker-image>
```
This will run the server in a Docker container named sgxwallet
You can start and stop running sgxwallet container by doing
```bash
docker stop sgxwallet
docker start sgxwallet
```
## Example of client certificate instantiation
Go to the project's top directory, then run
```bash
export CSR_FILE=a.csr
export KEY_FILE=k.key
export CERT_NAME_UNIQUE=someVeryUniqueName
openssl req -new -sha256 -nodes -out $CSR_FILE -newkey rsa:2048 -keyout $KEY_FILE -subj /CN=$CERT_NAME_UNIQUE
cat $CSR_FILE
cat $KEY_FILE
export KEY_PEM_FILE=k.pem
openssl rsa -in $KEY_FILE -text > $KEY_PEM_FILE
cat $KEY_PEM_FILE
```
Next, send content of `a.csr` as single line (by replacing real end of lines with `\n`) to port `1027`.
Example:
```bash
export URL_SGX_WALLET="http://127.0.0.1:1027"
curl -X POST --data '{ "jsonrpc": "2.0", "id": 2, "method": "signCertificate", "params": { "certificate": "-----BEGIN CERTIFICATE REQUEST-----\nMIICYjCCAUoCAQAwHTEbMBkGA1UEAwwSc29tZVZlcnlVbmlxdWVOYW1lMIIBIjAN\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3C4ceRhzMAZnG87PwlkzMROHsm3B\ncPydIeiqs1dieuuvVETJqbXAcOENNsGA+AdXjZwFkDuIS24p2yZ8AwuIMAwdMsGa\n5Hzk0ugOy52iPyGEuooqV94nnL6eWw/zryTvkk7j239wMWn5our5Ia1/CBQlXXo2\n4IWTWfWYOz26SWUh4DuvzMOheMVSxg3KLaxpx7Bq09p32lR9xpl53+HqxSDIMYh9\nC3y3kA6NdkKsGE/Jt4WoZ5S5LlrhYjw+PFTeX2lbGDZpn/sxQIM16Pxo2LCfefIa\nik+aZBEAlpn22ljLZ5sEcVgBmOlL+v3waq9u0AaSYzdGFRA+0ceVwU/QTQIDAQAB\noAAwDQYJKoZIhvcNAQELBQADggEBAJXodL69Q/8zDt24AySXK0ksV3C3l5l10Hno\nfF6zKypsYev33CFbZu6HweSgK2f21+DeI9TsGKJxI7K6MUqyH0pJhwlFSeMB5/qP\nJueqXMuvStZSp0GGTaNy7Al/jzOKYNf0ePsv/Rx8NcOdy7RCZE0gW998B5jKb66x\nPgy6QvD8CkZULiRScYlOC8Ex6nc+1Z54pRC1NFWs/ugGyFgLJHy0J2gNkOv6yfsl\nH3V/ocCYSoF4ToUQAxwx+dcy4PXrL9vKzRNJgWzsI/LzCZkglo8iis9YZQawDOUf\nGmDMDkr0Fx1W1tSEpvkw0flkAXZ8PhIGCC0320jkuPeClt7OWNs=\n-----END CERTIFICATE REQUEST-----\n" } }' -H 'content-type:application/json;' $URL_SGX_WALLET
```
The above example produces on success:
```
{"id":2,"jsonrpc":"2.0","result":{"errorMessage":"","result":true,"status":0}}
```
Next, generate the client certificate signed by root ones:
```bash
cd cert
./create_client_cert
ls -1
cat client.crt
openssl x509 -inform PEM -in client.crt > client.pem
cat client.pem
cd ..
```
Finally, execute a test call such as importing BLS key.
Example:
```bash
export URL_SGX_WALLET="https://127.0.0.1:1026"
curl \
-X POST --data '{ "jsonrpc": "2.0", "id": 1, "method": "importBLSKeyShare", "params": { "keyShareName": "nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3C4ceRhzMAZnG87PwlkzMROHsm3B", "n": 2, "t": 2, "index" : 1, "keyShare": "21043165427057050523208250969869713544622230829814517880078280390613973680760" } }' -H 'content-type:application/json;' \
-v --cacert ./cert/rootCA.pem --key $KEY_PEM_FILE --cert ./cert/client.pem $URL_SGX_WALLET -k
```
The above example produces on success:
```
{"id":1,"jsonrpc":"2.0","result":{"encryptedKeyShare":"0400020000000000040effffff02000000000000000000000b000000000000ff0000000000000000cecb5d7bd507cb936464fdb6b88cfe80e38eae963af6a39b6b05cdfba5521c60000000f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000080000000000000000000000000000000875c0520e8d6739c440e0e5073633861769fc1d31d627e9a72c66d43871c62bce2cc48e821341e10784242c4c8aad6ca73a491cbf7453c2ff012b6b3d9d96823c0256992d9792ea60269789b2d51ae87c75fe522dbcb8053458c1bca421cbc57f4a58e4e5689d534ca0303db83c7a9e88cd23afe3a39e1a3801371c95e7ffa54e834c6be8853983dcaa1fa9f5e6959a5","errorMessage":"","status":0}}
```
docs/index.md 0 → 100644
View file @ cfcfbb5f
# Getting Started
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
If you want to build the server first, start with [building.md](building.md).
Otherwise, with docker installed, pull one of the two containers:
```bash
docker pull skalenetwork/sgxwalletsim
```
or
```bash
docker pull skalenetwork/sgxwallet_base
```
To configure the containers with docker-compose, see [configuring.md](configuring.md).
# References
You should have some knowledge of Docker, SGX, and Certificate Signing Requests before trying to use this software.
docs/prerequisites.md 0 → 100644
View file @ cfcfbb5f
# SKALE sgxwallet Prerequisites
<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
sgxwallet depends on several freely available
software components. These must be installed and configured before
compiling sgxwallet.
This document describes how to get and compile these required components.
# Table of Contents
- [Recommend Host System](#recommended-host-system)
- [Docker](#docker)
- [Intel® Software Guard Extensions (Intel SGX)](#sgx)
- [Troubleshooting Installation](#troubleshooting-installation)
## Recommended host system
sgxwallet should be ran on Ubuntu 18.04. Sgxwallet has been tested on Ubuntu 18.04.
Sgxwallet may run on other Linux distributions, but the installation process is likely to be more complicated, and the use of other distributions is not supported by their respective communities at this time.
## Docker
Docker may be used instead of building sgxwallet directly (standalone mode) and is recommended. If you build using Docker, you need to install Docker Engine and Docker Compose if it is not already installed.
### To install Docker CE Engine:
```bash
sudo apt-get install -y apt-transport-https ca-certificates
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce
```
To verify a correct installation, run `sudo docker run hello-world`
### To install Docker Compose:
```bash
sudo curl -L \
https://github.com/docker/compose/releases/download/1.24.1/docker-compose-`uname -s`-`uname -m` \
-o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
To verify a correct installation, run `docker-compose version`
For details on Docker installation, see <https://docs.docker.com/engine/installation/linux/ubuntu> and <https://docs.docker.com/compose/install/#install-compose>
## Intel® Software Guard Extensions (Intel SGX)
Sgxwallet is intended to be run on Intel SGX-enabled platforms. However, it can also be run in "simulator mode" on platforms that do not have hardware support for Intel SGX. Support for other hardware-based Trusted Execution Environments (TEEs) can be added by submitting a Pull Request.
### Intel SGX SDK
The Intel SGX SDK is required for both Intel SGX hardware platform and Intel SGX simulator mode.
The following instructions download the Intel SGX SDK 2.5 and installs it in
`/opt/intel/sgxsdk/` :
```bash
sudo mkdir -p /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/linux-2.5/rhel7.4-server/sgx_linux_x64_psw_2.5.100.49891.bin
echo "yes" | sudo bash ./sgx_linux_x64_sdk_2.5.100.49891.bin
```
This installs the Intel SGX SDK in the recommended location,
`/opt/intel/sgxsdk` .
The Intel SGX OpenSSL library expects the SDK to be here by default.
After installing, source the Intel SGX SDK activation script to set
`$SGX_SDK`, `$PATH`, `$PKG_CONFIG_PATH`, and `$LD_LIBRARY_PATH`.
Append this line to your login shell script (`~/.bashrc` or similar):
```bash
source /opt/intel/sgxsdk/environment
echo "source /opt/intel/sgxsdk/environment" >>~/.bashrc
```
To learn more about Intel SGX read the
[Intel SGX SDK documentation](https://software.intel.com/en-us/sgx-sdk/documentation)
or visit the [Intel SGX homepage](https://software.intel.com/en-us/sgx).
Downloads are listed at
[Intel SGX Downloads for Linux](https://01.org/intel-software-guard-extensions/downloads).
### Intel SGX in Hardware Mode
If you plan to run this on Intel SGX-enabled hardware, you will need to
install the Intel SGX driver and install additional packages
for both standalone and docker builds.
You need to install the Intel SGX driver whether you build Avalon standalone
or using Docker.
Before installing Intel SGX software, install these packages:
```bash
sudo apt-get install -y libelf-dev cpuid
```
Verify your processor supports Intel SGX with:
`cpuid | grep SGX:`
Verify Intel SGX is enabled in BIOS.
Enter BIOS by pressing the BIOS key during boot.
The BIOS key varies by manufacturer and could be F10, F2, F12, F1, DEL, or ESC.
Usually Intel SGX is disabled by default.
If disabled, enter BIOS and find the Intel SGX feature
(it is usually under the "Advanced" or "Security" menu),
enable Intel SGX, save your BIOS settings, and exit BIOS.
Download and install libsgx-enclave-common version 2.5.101:
```bash
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/pool/main/libs/libsgx-enclave-common/libsgx-enclave-common_2.5.101.50123-bionic1_amd64.deb
sudo dpkg -i libsgx-enclave-common_2.5.101.50123-bionic1_amd64.deb
```
### Intel SGX in Simulator-mode
If running only in simulator mode (no hardware support), you only
need the Intel SGX SDK.
`SGX_MODE` is optional. If set, it must be set to `SIM` (the default).
Verify `SGX_MODE` is not set, or is set to `SIM`, with `echo $SGX_MODE` .
## Troubleshooting Installation
- If the message `intel_sgx: SGX is not enabled` appears in `/var/log/syslog`
Intel SGX needs to be enabled in BIOS
- If you are running in Intel SGX hardware mode, make sure you have device
`/dev/isgx` (and not `/dev/sgx`). Review the Intel SGX device driver
installation instructions above. If you have `/dev/sgx` the
device driver must be removed first
- If you are running in Intel SGX hardware mode, you need to modify
the `ias_api_key` in `config/tcs_config.toml` with your
IAS Subscription key obtained in the instructions above
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment