ubirch-protocol on a SIM

This repository contains example code, how to use the ubirch-protocol
in conjunction with the SIM application (SIGNiT) by
G+D (Giesecke+Devrient) and ubirch GmbH. The SIM card application wraps the required
functionality to run the ubirch-protocol on any (embedded) device that has access to a
modem or smart card capabilities.

The requirement is an interface that can send APDU commands to the SIM card application.
This most often will be a modem that supports the standard AT+CSIM command (3GPP TS 27.007).

• SIGNiT Customer Manual (PDF)
• Micropython Example Code (.py)
• Golang Example Code (.go)

Requirements

• a SIM card with the ubirch applet installed
• basic connectivity (via mobile network, wifi or other)
• a Modem that supports the AT+CSIM commands to send APDU commands to the SIM card
• registered ubirch account

Support

If you are having problems, please contact us using our help desk.

Signing/Chaining messages

The optimal way to work with the ubirch-protocol is to hash the actual data you want to
send and use the responding bytes as the payload of the UPP.
This hash can be used as a key to identify the message on the server side. The hash must
be unique per messages, it should optimally contain a sequence number or timestamp.

Examples

While it is possible to implement the full protocol without the need for additional
code, we have opted to provide an implementation in MicroPython, which can be used on
embedded devices, such as the Pycom GPy.

Additionally, other implementations provide an interface to the SIM application.

Go

The Go implementation can be compiled and cross compiled to a number of architectures.
This example also has a little micropython proxy that can be installed on a Pycom GPy or FiPy,
so it can be used instead of a directly connected modem.

MicroPython

The MicroPython implementation can be loaded on any GPy device and will do the following
steps:

Currently the generation will only work with Pycom devices, if the key ID is only
1 (one) byte long. This is due to a buffer length issue with the underlying python
implementation.

1. Initialize the SIM card and unlock the application with a PIN code.
2. Generate a new key pair and store it on the SIM card (fails if already generated).
3. Register the generated public key with the ubirch key server.
4. Create a signed UPP from some data ({"ts":1234,"data":"random"}).
5. Send the signed message to the ubirch backend (https://niomon.demo.ubirch.com).
6. Verify the signed UPP by feeding it back to the SIM card application.

TODO:

• Verify the UPP and check blockchain anchoring (//niomon.demo.ubirch.com/api/verify)*

* Sending data to the ubirch backend requires an API token.

Development

Key Generation

Generating a key, always use the UUID as the title of the key entry and use the key ID
to access the key (signing key and verifying key need two different IDs!). The UUID will
be automatically placed into the UPP
as the required identity id.

LICENSE

Copyright 2019 ubirch GmbH
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
   http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.