bigchaindb/docs/server/source/appendices/cryptography.md

Cryptography

The section documents the cryptographic algorithms and Python implementations that we use.

Before hashing or computing the signature of a JSON document, we serialize it as described in the section on JSON serialization.

Hashes

BigchainDB computes transaction and block hashes using an implementation of the SHA3-256 algorithm provided by the pysha3 package, which is a wrapper around the optimized reference implementation from http://keccak.noekeon.org.

Here's the relevant code from bigchaindb/bigchaindb/common/crypto.py (as of 11 December 2016):

import sha3

def hash_data(data):
    """Hash the provided data using SHA3-256"""
    return sha3.sha3_256(data.encode()).hexdigest()

The incoming data is understood to be a Python 3 string, which may contain Unicode characters such as 'ü' or '字'. The Python 3 encode() method converts data to a bytes object. sha3.sha3_256(data.encode()) is a _sha3.SHA3 object; the hexdigest() method converts it to a hexadecimal string. For example:

>>> import sha3
>>> data = '字'
>>> sha3.sha3_256(data.encode()).hexdigest()
'c67820de36d949a35ca24492e15767e2972b22f77213f6704ac0adec123c5690'

Note: Hashlocks (which are one kind of crypto-condition) may use a different hash function.

Signature Algorithm and Keys

BigchainDB uses the Ed25519 public-key signature system for generating its public/private key pairs. Ed25519 is an instance of the Edwards-curve Digital Signature Algorithm (EdDSA). As of December 2016, EdDSA was an "Internet-Draft" with the IETF but was already widely used.

BigchainDB uses the the cryptoconditions package to do signature and keypair-related calculations. That package, in turn, uses the PyNaCl package, a Python binding to the Networking and Cryptography (NaCl) library.

All keys are represented with a Base58 encoding. The cryptoconditions package uses the base58 package to calculate a Base58 encoding. (There's no standard for Base58 encoding.) Here's an example public/private key pair:

"keypair": {
    "public": "9WYFf8T65bv4S8jKU8wongKPD4AmMZAwvk1absFDbYLM",
    "private": "3x7MQpPq8AEUGEuzAxSVHjU1FhLWVQJKFNNkvHhJPGCX"
}