bigchaindb / cryptoconditions

A Python implementation of the Crypto-Conditions spec

BigchainDB Server

BigchainDB is the blockchain database. This repository is for BigchainDB Server.

The Basics

• Try the Quickstart
• Read the BigchainDB 2.0 whitepaper
• Check out the Hitchiker's Guide to BigchainDB

Run and Test BigchainDB Server from the master Branch

Running and testing the latest version of BigchainDB Server is easy. Make sure you have a recent version of Docker Compose installed. When you are ready, fire up a terminal and run:

git clone https://github.com/bigchaindb/bigchaindb.git
cd bigchaindb
make run

BigchainDB should be reachable now on http://localhost:9984/.

There are also other commands you can execute:

• make start: Run BigchainDB from source and daemonize it (stop it with make stop).
• make stop: Stop BigchainDB.
• make logs: Attach to the logs.
• make test: Run all unit and acceptance tests.
• make test-unit-watch: Run all tests and wait. Every time you change code, tests will be run again.
• make cov: Check code coverage and open the result in the browser.
• make doc: Generate HTML documentation and open it in the browser.
• make clean: Remove all build, test, coverage and Python artifacts.
• make reset: Stop and REMOVE all containers. WARNING: you will LOSE all data stored in BigchainDB.

To view all commands available, run make.

Links for Everyone

• BigchainDB.com - the main BigchainDB website, including newsletter signup
• Roadmap
• Blog
• Twitter

Links for Developers

• All BigchainDB Documentation
• BigchainDB Server Documentation
• CONTRIBUTING.md - how to contribute
• Community guidelines
• Open issues
• Open pull requests
• Gitter chatroom

Legal

• Licenses - open source & open content
• Imprint
• Contact Us

cryptoconditions's Issues

Add travis row for Python 3.6

Un-pin requirements in setup.py

See best practices outlined in https://packaging.python.org/requirements/#id5:

It is not considered best practice to use install_requires to pin dependencies to specific versions, or to specify sub-dependencies (i.e. dependencies of your dependencies). This is overly-restrictive, and prevents the user from gaining the benefit of dependency upgrades.

limit inverter subconditions to oracles

Move ThresholdSha256.get_subcondition_from_vk() outside implementation

This method seems to be more of an application-specific utility which could be found elsewhere.

At least, for now, that would simplify the implementation and reduce the amount of things to test for.

The method is currently untested.

Add docs about why & how to install the ffi.h dependency

as suggested by @TimDaub in bigchaindb/bigchaindb#694 (comment)

They could follow the same pattern as https://docs.bigchaindb.com/projects/server/en/latest/appendices/install-os-level-deps.html

Implement base exception for all other exceptions

e.g.:

class CryptoConditionsError(Exception):
    """bla bla bla"""

Support for RsaFulfillment

ed25519_generate_key_pair should return decoded strings

From bigchaindb/bigchaindb-common#4. May affect #22.

As far as I can tell, there's no need to return the byte version and it isn't required by the Cryptoconditions spec. We typically use .decode() on them anyway.

Could Ed25519Fulfillment.sign() private_key arg support strings?

Remove json serialization from cryptoconditions

Just provide functions for serialization to dicts.
Users should be able to serialize from there on to dicts themselves.

Document classes with empty docstrings

Empty docstrings were added to simplify the work of pulling the docstrings via automodule. See #33 (comment)

Now, we can document those classes.

Put ConditionTypes bitstring to set in its own method

see #67 (comment)

VerifyingKey.verify throws ValueError or AttributeError

For some values VerifyingKey.validate throws ValueError or AttributeError, while it should just return False. As far as I remember, this happened when the signature parameter was out of the expected range of the method, so:

1. Inputting a non-string
2. Inputting a non-compliant fulfillment URI ('abc' e.g.)

See how we have to handle this currently in BDB:

• https://github.com/bigchaindb/bigchaindb/pull/641/files#diff-9f1ab5b5daf1b3072e2123b6939bfb07R150
• https://github.com/bigchaindb/bigchaindb/pull/641/files#diff-9f1ab5b5daf1b3072e2123b6939bfb07R171

Remove support for Python 3.4

Mirror JS ref impl class names for types

This includes:

• module
• class
• etc

Investigate possible encoding problem

related to bigchaindb/bigchaindb#617

Make partial signing for threshold conditions easy

RFC-002 mirror: move InvertedThresholdSha256Fulfillment

• move InvertedThresholdSha256Fulfillment to py-bdb-crypto-conditions

Validate minimal thresholdfulfillment

Rename ParsingError to ParseError

At least for now now, whenever it makes sense, we mirror the JS reference implementation. That is, for language-independent things.

Add checks for Condition.cost property (getter and setter)

See #67 (comment)

Move repo and issues under Interledger org

At https://github.com/interledger/python-crypto-conditions

Support for PrefixSha256Fulfillment

Investigate what can be done for pynacl dependency on libffi (header file ffi.h)

Carrying this over from bigchaindb/bigchaindb-driver#140, copying here for convenience:

Some questions:

• Can we detect the missing header file via setup.py?
• Can we package the header file as part of the distribution? See following:
  • pypa/packaging-problems#84
  • http://stackoverflow.com/questions/32313793/how-to-have-pypi-package-install-header-files-for-c-extension-with-distutils-set

Important note: Although this issue is being created under bigchaindb-driver for the time being, this is something, if possible, that should be pushed down to cryptoconditions, at the very least, and further to pynacl if it makes sense.

Use the cryptoconditions spec terminology for public/private keys

Relates to bigchaindb/bigchaindb#746

In BigchainDB we unified the language of keys to public key and private key, instead of using public/verifying private/signing interchangeably throughout the code and documentation.

Cryptoconditions should do the same but use the terminology used on the spec

Replace INTEGER_REGEX with simpler int() and error handling

see #67 (comment)

Update to version 02 of the draft specification

draft is at https://tools.ietf.org/html/draft-thomas-crypto-conditions-02

• part of this work should incorporate the test vectors documented at https://github.com/rfcs/crypto-conditions#test-vectors

Some details to double check for:

• URI normalization: see issues rfcs/crypto-conditions#8 and rfcs/crypto-conditions#12
• add condition validation to tests
• document support for subtypes (which ones) and behaviour of the implementation with respect to unsupported types (types above id 4 are ignored)

Things left to be done

• Test signature operation (see rfcs/crypto-conditions#15)

Add PyPI badge

Since cryptoconditions is on PyPI, we could add a PyPI badge for it. See http://shields.io/

Remove MAX_SAFE_INTEGER_JS?

see #67 (comment)

Update link to rfc in readme

The new link is https://github.com/rfcs/crypto-conditions/

feat: switch to DER encoding and ni: uris

Try to shorten the description in setup.py and on github

The description given in setup.py and on github is quite lengthy. Could we find a way to capture the essence of cryptoconditions in fewer words?

This would be useful when referring to cryptoconditions.

E.g.:

• python port from the Interledger Protocol (ILP)
• multi-algorithm, multi-level, multi-signature standard format for expressing conditions and fulfillments
• multi-signature standard for expressing conditions and fulfillments

KeyError on calculate_smallest_valid_fulfillment_set

ThresholdSha256Fulfillment.calculate_smallest_valid_fulfillment_set(self.threshold, subfulfillments)['set'] might not always include set in its keys

Error on long subfulfillments

After adding a certain amount of subconditions, the serializeUri fails:

Test vector attached

Stacktrace

  File "bigchaindb-server/bigchaindb/common/transaction.py", line 904, in
to_dict                                                                                                
    condition['uri'] = self.fulfillment.condition_uri                                                   
  File "cryptoconditions/fulfillment.py", line 154, in condition_uri                                                                             
    return self.condition.serialize_uri()                                                               
  File "cryptoconditions/fulfillment.py", line 142, in condition                                                                                 
    condition.hash = self.generate_hash()                                                               
  File "cryptoconditions/types/base_sha256.py", line 21, in generate_hash                                                                        
    self.write_hash_payload(hasher)                                                                     
  File "cryptoconditions/types/threshold_sha256.py", line 206, in write_hash_payload                                                             
    if c['type'] == FULFILLMENT                                                                         
  File "cryptoconditions/fulfillment.py", line 164, in condition_binary                                                                          
    return self.condition.serialize_binary()                                                            
  File "cryptoconditions/condition.py", line 244, in serialize_binary                                                                            
    writer.write_var_uint(self.max_fulfillment_length)                                                  
  File "cryptoconditions/lib/writer.py", line 50, in write_var_uint                                                                              
    buffer += bytes([value])                                                                            
ValueError: bytes must be in range(0, 256)                                                              

Test vector

{"id":"f018248e7793a9ad69300bcfb600420ceec9ae496a00244f3ac5a65e6d69ee7c","operation":"CREATE","outputs":[{"amount":1,"condition":{"details":{"type_id":2,"type":"fulfillment","bitmask":43,"threshold":2,"subfulfillments":[{"type_id":4,"bitmask":32,"signature":null,"public_key":"79K8SPZbeSDYXBrWgt3dsNmYTZbKNtdYQ5XrjA9XEWfG","type":"fulfillment","weight":1},{"type_id":2,"type":"fulfillment","bitmask":11,"threshold":3,"subfulfillments":[{"type_id":0,"bitmask":3,"hash":"5wbD6GsVBReHetMUw17QcNne8BjB1xSKRoU4JYpafEx5","max_fulfillment_length":5,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"EuNEkS8TUYaTngMPGiS3DHdApYBf2YYQVdg3hHHTnPDx","max_fulfillment_length":11,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"Ay3VvUjfEnEhCWxJMGLGBpWTS5iu2nVB64wcsYkPnCqd","max_fulfillment_length":5,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"H7nD6xkFRm99GzAxvA5JG8DQSZBEGdiUdnYuh7714vMW","max_fulfillment_length":10,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"8EmZwLhhFAZ9QgHgHfgMokfQ2CfzXaLbyEz4uaXaJyq4","max_fulfillment_length":7,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"DFf8KSmzgHEarJ2RPJmyDGTvnS8E8MjxkDNVjNsUN8Hr","max_fulfillment_length":8,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"3qUBtEhzGazLRTM9c3JWKGPTnrkgxbtEoezh7WaJuJBS","max_fulfillment_length":3,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"4w6YMt6nH3oSsA1uTk6Vmqvqsa9eSquKSAxWtDWPrzTg","max_fulfillment_length":4,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"HT5nStZQ4x2ecqwZFiKtJWs14TVWiViNVrfFpEqpvf3u","max_fulfillment_length":5,"type":"condition","weight":1},{"type_id":0,"bitmask":3,"hash":"JBMM3eF7iEdJ9XxwSfHe4JrwkcFQExTsiCF4YSGyuJoH","max_fulfillment_length":3,"type":"condition","weight":1}],"weight":1}]},"uri":"cc:2:2b:RnwQdfUJUqPi-zhtS-5WeijFScfyxo2tUVL56T6rQXQ:439"},"public_keys":["79K8SPZbeSDYXBrWgt3dsNmYTZbKNtdYQ5XrjA9XEWfG"]}],"inputs":[{"fulfillment":"cf:4:W0dEBH4MFkphXyUzeuY04q8z2visobk5dtiggDfGdOfdku6Uawyk3SF0B6mWirTC6XC7CaWCKi62xRDXnWXQ_yl-A-Ihi315r65IpGf1AIJhLryNx1rcKocczKUCsAsB","fulfills":null,"owners_before":["79K8SPZbeSDYXBrWgt3dsNmYTZbKNtdYQ5XrjA9XEWfG"]}],"metadata":null,"asset":{"data":{"item":"shirt","frequency":10,"timestamp":"1493634802"}},"version":"0.9"}

Provide ThresholdSha256Fulfillment.add_subfulfillments()?

Being able to pass multiple fulfillments at once would be convenient. E.g., given:

alice_ed25519 = Ed25519Fulfillment(public_key=alice.verifying_key)
bob_ed25519 = Ed25519Fulfillment(public_key=bob.verifying_key)
threshold_sha256 = ThresholdSha256Fulfillment(threshold=2)

currently:

threshold_sha256.add_subfulfillment(alice_ed25519)
threshold_sha256.add_subfulfillment(bob_ed25519)

proposal:

threshold_sha256.add_subfulfillments(alice_ed25519, bob_ed25519)

Could Ed25519Fulfillment.sign() message arg be a string instead of bytes, or both?

Support for strings would be convenient.

Why is Condition a metaclass?

On a related note, why not provide an __init__ to Condition?

Such that instead of the following

condition = Condition()
condition.type_id = type_id
condition.bitmask = bitmask
condition.hash = _hash
condition.max_fulfillment_length = max_fulfillment_length

we could simply do:

condition = Condition(
    type_id=self.type_id,
    bitmask=self.bitmask,
    hash=_hash,
    max_fulfillment_length=max_fulfillment_length,
)

Simplify Condition subtypes validation

see #67 (comment)

GET/UPDATE/DELETE of subcondition

We want to update a single subcondition
hence try to find the path of the subcondition or better ways to navigate subconditions

example

GET/DEL/UPDATE fulfillment.subcondition_by_path([(type_id=cc.types.THRESHOLD, args=[branch_nb]), (type_id=cc.types.ED25519, args=[public_key]))]

the args list

[(type_id=cc.types.THRESHOLD, args=[branch_nb]), (type_id=cc.types.ED25519, args=[public_key])]

is an ordered selector for each depth in the tree so at depth=0 you will look for a THRESHOLD and select subcondition with branch_nb

Where to validate a condition's subtypes?

Some questions:

• Should the implementation silently ignore extra unsupported subtypes?

If not, then when should the implementation complain about it?

• At parsing time?
• When .validate() is explicitly called?

As an example, if we were to validate the subtypes when parsing, we could do so:

class ConditionTypes(BitString):
    namedValues = NamedValues(
        ('preImageSha256', 0),
        ('prefixSha256', 1),
        ('thresholdSha256', 2),
        ('rsaSha256', 3),
        ('ed25519Sha256', 4),
    )
    subtypeSpec = ValueSizeConstraint(0, 5)

The line subtypeSpec = ValueSizeConstraint(0, 5) requires the length of the BIT STRING to be no longer than 5.

Add support for utf-8

relates to bigchaindb/bigchaindb#529

Cryptoconditions fails when using utf-8 payloads on bigchaindb.
I think it makes for us to support utf-8 throughout bigchaindb and cryptoconditions.

Document installation of cryptoconditions via pip (pypi)

Since cryptoconditions is on PyPI, we could document its installation via pip.

RFC-002 mirror: move TimeoutFulfillment

• Move TimeoutFulfillment to py-bdb-crypto-conditions

Make PreimageSha256 preimage attr a property

see #67 (comment)

PreimageSha256 validation returns only True can be dangerous

See this method: https://github.com/bigchaindb/cryptoconditions/blob/master/cryptoconditions/types/sha256.py#L120

PreimageSha256.validate always yields True, while all other respective types validate by checking external parameters (usually the message parameter).
A user would expect that calling .validate on all present fulfillments in a transaction to (at least partially) validate the transaction.
However, for a PreimageSha256 fulfillment, a comparison between the input condition and the newly created fulfillment's condition will also have to happen. In BigchainDB, this case is handled here:
https://github.com/bigchaindb/bigchaindb/blob/master/bigchaindb/util.py#L458

To avoid pitfalls for users of this library it would be nice if we could force the submission of the input-condition and then yield the respective boolean in the validate method.

Make type match type_id

Currently, the 'type' field only shows either 'condition' or 'fulfillment', whereas the 'type_id' is set according to the rfc.

Example:

>>> Condition.from_uri('cc:2:2b:mJUaGKCuF5n-3tfXM2U81VYtHbX-N8MP6kz8R-ASwNQ:146').to_dict()
{'bitmask': 43,
 'hash': 'BGcqXDoe5DeQB87es8AQEDWr3A6Dvjuq3egZF5sZ1qfy',
 'max_fulfillment_length': 146,
 'type': 'condition',
 'type_id': 2}

This issue proposes to change the above to:

>>> Condition.from_uri('cc:2:2b:mJUaGKCuF5n-3tfXM2U81VYtHbX-N8MP6kz8R-ASwNQ:146').to_dict()
{'bitmask': 43,
 'hash': 'BGcqXDoe5DeQB87es8AQEDWr3A6Dvjuq3egZF5sZ1qfy',
 'max_fulfillment_length': 146,
 'type': 'prefix_sha_256',
 'type_id': 2}

Unless @sbellem's understanding is wrong this would be in line with the RFC:

2.4. Condition

Below are the string and binary encoding formats for a condition.

2.4.1. String Format

Conditions are ASCII encoded as:

"cc:" BASE16(type) ":" BASE16(featureBitmask) ":"
      BASE64URL(fingerprint) ":" BASE10(maxFulfillmentLength)

2.4.2. Binary Format

Conditions are binary encoded as:

  Condition ::= SEQUENCE {
    type ConditionType,
    featureBitmask INTEGER (0..MAX),
    fingerprint OCTET STRING,
    maxFulfillmentLength INTEGER (0..MAX)
  }

```text
  ConditionType ::= INTEGER {
    preimageSha256(0),
    rsaSha256(1),
    prefixSha256(2),
    thresholdSha256(3),
    ed25519(4)
  } (0..65535)

Perhaps a different, issue, but raising here as it related. Why not use the word type to denote the id, since it is what the spec uses? We could use type_name to store the name.

Use namedtuples for registered types

Simply to make it more convenient to deal with registered types.

Example:

RegisteredType = namedtuple('RegisteredType', 'type_id name class_')

registered_type = RegisteredType(type_id=0, name='n', class_='c')

registered_type.name

Remove duplicate regex

see #67 (comment)

Remove support for weighted threshold conditions

Assuming we wish to follow the reference implementation (interledger/five-bells-condition). See commit interledgerjs/five-bells-condition@2059af5

Rewriting the commit message here for convenience:

The fact that threshold conditions are weighted doesn't seem to provide enough of a benefit to warrant the complexity this feature adds. We will take out the weights for now and possibly add a weighted threshold condition type in the future.

BREAKING: Threshold condition are no longer weighted.

Could Fulfillment.sign() return the signature?

ed25519_fulfillment.sign(message=msg.encode(), private_key=sk)

returns None

proposal:

def sign(self, message, private_key):
    sk = private_key
    vk = sk.get_verifying_key()
    self.public_key = vk
    self.signature = sk.sign(message, encoding='bytes')
    return self.signature