Taxa Network Python SDK Documentation

This library is used to aid developers in building applications on the Taxa Network. It works with both Python 2.7 and Python 3.5+.

Generate keys for the TEE remote attestation

Intel’s Software Guard Extensions (SGX) is currently the Trusted Execution Environment (TEE) technology supported by Taxa Network.

To enable the SGX's remote attestation feature on your node, follow these instructions to generate a service provider ID (SPID) and primary key:

Register with Intel here
Go to https://api.portal.trustedservices.intel.com/EPID-attestation

In the Development access section, click the Subscribe (unlickable) button. Follow the steps to generate an SPID and Primary Key.

Installation

pip install taxa_sdk

or to install the development version:

Download the zip file from Github. Extract into a folder anywhere.
On the command line, navigate to that folder and run the install script: python setup.py install

Tell the SDK your TEE remote attestation keys

Run the following command using the SPID and primary key you got from Intel:

python3 -m taxa_sdk.install_intel_keys [SPID] [primary key]

Extra Installation steps for OSX users

If you are on OSX, you need to install the Apple signed libraries:

sudo python3 -m taxa_sdk.install_osx_libs

(Note the requirement of sudo)

Usage

The functionality of this SDK is accessible from the instances of the class TaxaRequest.

TaxaRequest

Wrapper class for the request going to a taxa server.

from taxa_sdk import TaxaRequest
request = TaxaRequest(identity='/path/to/identity.json')

The identity argument is the path to your identity file that you either generated with a previous request, or if you're using this SDK for the first time, it will make one for you if the path you pass in is an empty file.

This "identity file" contains all the keys you need to use the Taxa network, including the AES master keys, the client_cert and the client_key. You only ever need to have one identity file, unless you are using the Taxa network as multiple users.

If you don't pass in an identity by leaving the constructor blank, a new identity file will be created for you in your home folder called profile_{publickey_hash}.json.

Sending your first request

from taxa_sdk import TaxaRequest
request = TaxaRequest()
response = request.send(
    code_path="/path/to/tsetvice.py",
    function="submit",
    data={'amount': 3500000}
)

Note: All values within the data argument must be json serializable. In future version of this SDK, this restriction may be lifted.

Passing in client_cert and client_key

If you already have a keyfile/cert, you can pass those in like this:

request = TaxaRequest(
  client_key_path="/path/to/my.key",
  client_cert_path="/path/to/my.cert"
)

If the client_cert and client_key have the same filename, except for the extension, and are in the same folder, then you may only pass in client_key. When the attestation process commences, the master key used for AES encryption of data between you and the Taxa server is stored in my.[ip].aes. It takes the filename of the client_key and appends the IP and changes the extension to ".aes".

You can also pass in the path to the taxa_client executable. But keep in mind the bug in taxa_client prevents this from working unless you are in the same folder as taxa_client. So, using "./taxa_client" (the default) for now is recommended.

request = TaxaRequest(
  core_path="./taxa_client",
  verbose=True
)

You can also pass in verbose=True to get extra debug information printed to the screen.

Taxa Response

The response from the .send() method will be a dictionary object that looks like this:

{
  'version': '0.1',
  'content-type': 'text/plain',
  'response-code': '1000',
  'direction': '0',
  'public-message': '',
  'pyxa-version': '0.1',
  'content-transfer-encoding': 'base64',
  'encrypted_data': 'dF5sFeU8/GfxDsJiNaL4gms3',
  'decrypted_data': 'Your value is less than your opponent'
}

The response from the server decrypted with your AES key can be found in the decrypted_data section of the response.

Other request parameters

You can set the ip instance variable to a string depicting the IP address of the server you want to connect to. This feature is helpful for testing. If this argument is left off, then the SDK will route the request to a random Taxa server.

Manual Decrypting Responses

If you've received a response from the Taxa server through other means (like you called taxa_client separately), then you can decrypt the response manually using the decrypt_data method of TaxaRequest.

>>> request = TaxaRequest(
  keyfile_path="/path/to/keyfile.key",
  cert_path="/path/to/client_cert.cert"
)
>>> request.decrypt_data('dF5sFeU8/GfxDsJiNaL4gms3')
'Your value is less than your opponent'

Converting a Taxa identity file into individual files

If you are using the Taxa identity format (which is the default), then all of your keys, both private and public, are stored into a single file. This makes it hard to share your public key. You can't just send your Taxa identity to another person because they'll get your private keys too.

You can run the key_manager.write_key_to_file() method to write just the cert file to a separate file for sharing:

>>> from taxa_sdk.key_managers import IdentityKeyManager
manager = IdentityKeyManager("/path/to/identity.json")
manager.write_key_to_file("client_cert")

The key_manager object can also be accessed through the TaxaRequest class:

>>> from taxa_sdk import TaxaRequest
request = TaxaRequest("/path/to/identity.json")
request.key_manager.write_key_to_file("client_cert")

Then the cert will be written to a file located here /path/to/identity.taxa.cert. You can pass in either "client_cert", "client_key", or "aes".

Exceptions

If the SDK throws an exception that descends from taxa_sdk.exceptions.TaxaException, then it means you probably made a mistake and you need to consult the documentation. If the exception that gets raised is not descended from TaxaException, then you might have encountered a bug in the SDK and you should report the issue to the developers.