Developer Pages

Documentation and Tutorials

Collect, Seal and Verify ESG data with ease

ubirch on GitHub


Ubirch Trust Protocol

Ubirch Nano Client

Ubirch Trust Service

Ubirch Console

Examples and Tutorials

Ubirch Python Example

Python client is a Python3 implementation of ubirch protocol.

The library consists of three parts which can be used individually:

A full, runnable example is located here.

Setting up api, keystore and protocol

import ubirch

# minimal ubirch protocol impl that allows you to send signed messages
class Proto(ubirch.Protocol):
    def __init__(self, keystore):
        self.__ks = keystore
    def _sign(self, uuid, message):
        return self.__ks.find_signing_key(uuid).sign(message)

keystore = ubirch.KeyStore("example-keystore.jks", "example-password")
api = ubirch.API("<YOUR_AUTH_TOKEN>", "dev")

protocol = Proto(keystore)

Initializing the KeyStore and registering keys

reg_message = protocol.message_signed(identity_uuid, UBIRCH_PROTOCOL_TYPE_REG,
registration_resp = api.register_identity(reg_message)

Creating a device

device_create_resp = api.device_create({
    "deviceId": str(device_uuid),
    # device types available at Avatar service's endpoint /device/deviceType
    "deviceTypeKey": device_type,  
    "deviceName": device_name,
    # you can put group uuids here, so other users see the device
    "groups": ["db1488ae-becc-40a3-a5c2-b6daadd6715b"],
    "hwDeviceId": str(device_hwid),
    "tags": ["python-example", "python-client"],
    "deviceProperties": {
        "storesData": True,
        "blockChain": False
    "created": "{}Z".format(datetime.utcnow()

Sending messages

In general, sending messages looks like this:

message = protocol.message_*(<uuid>, <message_type>, <payload>)
response = api.send(message)

Here are some examples with concrete payload types:

Sealing and verifying integrity of messages

This is useful when you want to verify the integrity of messages, but don’t want to share the messages themself with ubirch.

payload_hash = hashlib.sha512(payload).digest()  # use hashing function of your choice
message = protocol.message_chained(device_uuid, UBIRCH_PROTOCOL_TYPE_BIN, payload_hash)
seal_response = api.send(message)


And then in your backend, to verify the validity of the received message

payload = receive_sensitive_message()
payload_hash = hashlib.sha512(payload).digest()
hash_b64 = bytes.decode(base64.b64encode(payload_hash))

from urllib.parse import quote
import requests

response = requests.get(
    .format("<YOUR_UBIRCH_ENV>", quote(received_message_hash, safe="+=")),

is_message_valid = response.ok

© 2019 ubirch GmbH : : Imprint