Skip to content

Commit

Permalink
Merge pull request #165 from blockchain-certificates/jh_UpdateReadme
Browse files Browse the repository at this point in the history 
Added additional workaround link to help resolve Mac scrypt problems
  • Loading branch information
AnthonyRonning committed Jan 24, 2020
2 parents add823c + 041f6d7 commit 18f875d
Showing 1 changed file with 27 additions and 27 deletions.
54 changes: 27 additions & 27 deletions README.md
View file
Expand Up @@ -5,7 +5,7 @@
# cert-issuer

The cert-issuer project issues blockchain certificates by creating a transaction from the issuing institution to the
recipient on the Bitcoin blockchain that includes the hash of the certificate itself.
recipient on the Bitcoin blockchain that includes the hash of the certificate itself.

## Web resources
For development or testing using web requests, check out the documentation at [docs/web_resources.md](./docs/web_resources.md).
Expand All @@ -26,7 +26,7 @@ experimenting only.


3. From a command line in cert-issuer dir, build your docker container:

```
docker build -t bc/cert-issuer:1.0 .
```
Expand Down Expand Up @@ -61,17 +61,17 @@ Ensure your docker image is running and bitcoind process is started
sed -i.bak "s/<issuing-address>/$issuer/g" /etc/cert-issuer/conf.ini
bitcoin-cli dumpprivkey $issuer > /etc/cert-issuer/pk_issuer.txt
```

2. Don't forget to save snapshots so you don't lose your work (see step 3 of client setup)

## Issuing certificates

1. Add your certificate to /etc/cert-issuer/data/unsigned_certificates/.
1. Add your certificate to /etc/cert-issuer/data/unsigned_certificates/.

```
# To use a sample unsigned certificate as follows:
cp /cert-issuer/examples/data-testnet/unsigned_certificates/3bc1a96a-3501-46ed-8f75-49612bbac257.json /etc/cert-issuer/data/unsigned_certificates/
cp /cert-issuer/examples/data-testnet/unsigned_certificates/3bc1a96a-3501-46ed-8f75-49612bbac257.json /etc/cert-issuer/data/unsigned_certificates/
# If you created your own unsigned certificate using cert-tools (assuming you placed it under data/unsigned_certificates):
cp <cert-issuer-home>/data/unsigned_certificates/<your-cert-guid>.json /etc/cert-issuer/data/unsigned_certificates/
```
Expand All @@ -97,7 +97,7 @@ Ensure your docker image is running and bitcoind process is started
```
cert-issuer -c /etc/cert-issuer/conf.ini
```

4. Your Blockchain certificates are located in `/etc/cert-issuer/data/blockchain_certificates`. Copy these to your local machine, and add them to cert-viewer's `cert_data` folder to see your certificates in the Certificate Viewer.

```
Expand All @@ -107,9 +107,9 @@ docker cp <containerId>:/etc/cert-issuer/data/blockchain_certificates <localPath

# How batch issuing works

While it is possible to issue one certificate with one Bitcoin transaction, it is far more efficient to use one Bitcoin transaction to issue a batch of certificates.
While it is possible to issue one certificate with one Bitcoin transaction, it is far more efficient to use one Bitcoin transaction to issue a batch of certificates.

The issuer builds a Merkle tree of certificate hashes and registers the Merkle root as the OP_RETURN field in the Bitcoin transaction.
The issuer builds a Merkle tree of certificate hashes and registers the Merkle root as the OP_RETURN field in the Bitcoin transaction.

Suppose the batch contains `n` certificates, and certificate `i` contains recipient `i`'s information. The issuer hashes each certificate and combines them into a Merkle tree:

Expand All @@ -118,7 +118,7 @@ Suppose the batch contains `n` certificates, and certificate `i` contains recipi

The root of the Merkle tree, which is a 256-bit hash, is issued on the Bitcoin blockchain. The complete Bitcoin transaction outputs are described in 'Transaction structure'.

The Blockchain Certificate given to recipient `i` contains a [2017 Merkle Proof Signature Suite](https://w3c-dvcg.github.io/lds-merkleproof2017/)-formatted signature, proving that certificate `i` is contained in the Merkle tree.
The Blockchain Certificate given to recipient `i` contains a [2017 Merkle Proof Signature Suite](https://w3c-dvcg.github.io/lds-merkleproof2017/)-formatted signature, proving that certificate `i` is contained in the Merkle tree.

![](img/blockchain_certificate_components.png)

Expand Down Expand Up @@ -174,11 +174,11 @@ The Quick Start assumed you are issuing certificates in Bitcoin regtest mode, wh

We recommend starting in testnet before mainnet.

By default, cert-issuer does not assume you have a bitcoin/ethereum node running locally, and it uses APIs to look up and broadcast transactions. There is API support for both testnet and mainnet chains.
By default, cert-issuer does not assume you have a bitcoin/ethereum node running locally, and it uses APIs to look up and broadcast transactions. There is API support for both testnet and mainnet chains.

If you do want to use a local bitcoin node, [see details about installing and configuring a bitcoin node for use with cert-issuer](docs/bitcoind.md) before continuing.

These steps walk you through issuing in testnet and mainnet mode. Note that the prerequisites and the configuration for the Bitcoin issuing and the Ethereum issuing differ.
These steps walk you through issuing in testnet and mainnet mode. Note that the prerequisites and the configuration for the Bitcoin issuing and the Ethereum issuing differ.

## Prerequisites

Expand All @@ -203,7 +203,7 @@ python setup.py experimental --blockchain=ethereum
First, ensure you've created an issuing address appropriate for the Bitcoin chain you are using. Please note:
- regtest or testnet addresses will start with 'm' or 'n'
- mainnet addresses will start with '1'

__These steps involve storing secure information on a USB. Do not plug in this USB when your computer's wifi is on.__

1. Use bitaddress.org
Expand All @@ -221,7 +221,7 @@ If you are using a local bitcoin node, you can create addresses by command line.
Currently Blockcerts just supports issuing to the Ropsten Ethereum testnet, and the Ethereum mainnet. In Ethereum a public/private key pair is the same accross all test/main networks.

__These steps involve storing secure information on a USB. Do not plug in this USB when your computer's wifi is on.__

1. Create issuing address on Myetherwallet
- Go to https://www.myetherwallet.com/.
- For the best security turn off your connection to the internet when you are on the create wallet page.
Expand All @@ -244,24 +244,24 @@ Note ensure you've transferred sufficient funds to your issuing address to cover

- Request some testnet coins by searching for “Testnet Faucet”, and entering your issuing public address. It may take a while for the transaction to be confirmed.
- Important: make sure you follow the guidance of the testnet faucet provider!

#### Obtaining mainnet coins

- If this is your first time purchasing Bitcoin or Ethereum, start by reading starter information:
- For __Bitcoin__: [https://bitcoin.org/en/getting-started] Specifically, the first section “How to use Bitcoin” is an overview of choosing a wallet, obtaining your first Bitcoins, and securing your money.
- For __Ethereum__: https://myetherwallet.github.io/knowledge-base/getting-started/getting-started-new.html - MyEtherWallet's knowledge base getting started entry.
- For __Ethereum__: https://myetherwallet.github.io/knowledge-base/getting-started/getting-started-new.html - MyEtherWallet's knowledge base getting started entry.
- Transfer a small amount of money to the issuer address created in step 1.


## Configuring cert-issuer
## Configuring cert-issuer

Edit your conf.ini file (the config file for this application).
Edit your conf.ini file (the config file for this application).

```
issuing_address = <issuing-address>
chain=<bitcoin_regtest|bitcoin_testnet|bitcoin_mainnet|ethereum_ropsten|ethereum_mainnet|mockchain>
usb_name = </Volumes/path-to-usb/>
key_file = <file-you-saved-pk-to>
Expand Down Expand Up @@ -291,7 +291,7 @@ python cert-issuer -c conf.ini

3. Output
- The Blockchain Certificates will be located in data/blockchain_certificates.
- If you ran in the mainnet or testnet mode, you can also see your transaction on a live blockchain explorer.
- If you ran in the mainnet or testnet mode, you can also see your transaction on a live blockchain explorer.
- For Bitcoin, Blockr.io has explorers for both [testnet](https://tbtc.blockr.io/) and [mainnet](https://blockr.io/).
- For Ethereum, Etherscan has explorers for [ropsten](https://ropsten.etherscan.io/) and [mainnet](https://etherscan.io/)
- The transaction id is located in the Blockchain Certificate under `signature.anchors[0].sourceId`
Expand All @@ -307,26 +307,26 @@ This project uses tox to validate against several python environments.
```
./run_tests.sh
```

# Class design

## Core issuing classes
![](img/issuer_main_classes.png)

The `Issuer` api is quite simple; it relies on `CertificateHandler`s and `Transaction Handler`s to do the work of
The `Issuer` api is quite simple; it relies on `CertificateHandler`s and `Transaction Handler`s to do the work of
extracting the data to issue on the blockchain, and handling the blockchain transaction, respectively.

`CertificateBatchHandler` manages the certificates to issue on the blockchain. It ensures that all accessors iterate
certificates in a predictable order. This is critical because the Merkle Proofs must be associated with the correct
certificate. Python generators are used here to help keep the memory footprint low while reading from files.

- `prepare_batch`
- performs the preparatory steps on certificates in the batch, including validation of the schema and forming the
- `prepare_batch`
- performs the preparatory steps on certificates in the batch, including validation of the schema and forming the
data that will go on the blockchain. Certificate-level details are handled by `CertificateHandler`s
- returns the hex byte array that will go on the blockchain
- `finish_batch` ensures each certificate is updated with the blockchain transaction information (and proof in general)

`CertificateHandler` is responsible for reading from and updating a specific certificate (identified by certificate_metadata).
`CertificateHandler` is responsible for reading from and updating a specific certificate (identified by certificate_metadata).
It is used exclusively by `CertificateBatchHandler` to handle certificate-level details:
- `validate`: ensure the certificate is well-formed
- `sign`: (currently unused)
Expand Down Expand Up @@ -376,7 +376,7 @@ This class structure is intended to be general-purpose to allow other implementa

# Examples

The files in examples/data-testnet contain results of previous runs.
The files in examples/data-testnet contain results of previous runs.

# FAQs

Expand All @@ -396,7 +396,7 @@ output. To view a transaction in a web browser, you might try something like th

## Mac scrypt problems

If your install on Mac is failing with a message like the following, try the [workaround described in this thread](https://github.com/ethereum/pyethereum/issues/292).
If your install on Mac is failing with a message like the following, try the [workaround described in this thread](https://github.com/ethereum/pyethereum/issues/292) or the [workaround described here](https://github.com/pyca/cryptography/issues/2692#issuecomment-272773481).

```
fatal error: 'openssl/aes.h'
Expand Down

0 comments on commit 18f875d

Please sign in to comment.