pyqcicada’s documentation!

This is the documentation for pyqcicada, version 0.1.1.

This package provides the extension modules and cli that are specific to the Crypta Labs QCicada QRNG, specifically Signed Read mode.

This package is dependant on pyqcc, which must be present on the system.

Check the documentation for the basic pyqcc package here: pyqcc documentation

Indices

Index
Device class reference
OEM Certificate Authority
Usage examples
Command Line Interface

Device class reference

This class inherits from the basic pyqcc.cmdctrl.device class, see pyqcc device class reference .

class pyqcicada.cmdctrl.device(device_name)

Bases: device

QCicada Cmd&Ctrl Device class

This is the class that implements the custom Cmd&Ctrl commands for Crypta Labs Qcicada devices. It also provides some functions to read PEM files. It is an extension of the base pyqcc cmdctrl device class.

Parameters:: device_name (str) – Device serial port device (e.g "COM3" on Windows, "/dev/ttyUSB0" on Linux)

get_dev_certificate()

Get the device certificate signature

It returns the raw 64 bytes of the signature, the signature is done using ECDSA algorithm. The first 32 bytes are the r point and the last 32 bytes are the s component of the signature.

Note

This function return the raw device certificate signature, use the method get_dev_pub_key_verified() that also verify the certificate before returning the public key.

Returns:: Returns the raw signature of the device certificate if success. None if failure.
Return type:: bytes | None

get_dev_pub_key() → bytes | None

Get the device public key

Read the device public key, the key is in raw format, the first 32 bytes are the r

Note

This function returns the raw device public key without verifying it, use the method get_dev_pub_key_verified() instead to also verify the certificate before returning the public key.

Returns:: Returns the raw public key of the device certificate if success. None if failure.
Return type:: bytes | None

get_dev_pub_key_verified(ca_pubkey_pem_file)

Get the verified device public key

Return the raw device public key after verifying it with the certificate authority public key passed as PEM file (ca_pubkey_pem_file). The raw device public key can be then passed as parameter to the function read_signed_and_verify().

Note

The certificate authority public key shall be the public part of the same keypair used to create the device certificate during device initialization, see set_device_certificate()

Parameters:: ca_pubkey_pem_file (str) – Path of the PEM file that contains the certificate authority public key.
Returns:: Returns the raw public key of the device if success. None if failure.
Return type:: bytes | None

read_signed_and_verify(length: int, dev_pub_key_raw: bytes) → bytes | None

Read data and verify its signature

Parameters:

length (int) – How many bytes to read, the maximum allowed length depends on how many bytes are available, see get_status().
dev_pub_key_raw (bytes) – Device public key, previously extracted from the device with the function get_dev_pub_key_verified()

Returns:

Returns the raw public key of the device if success. None if failure.

Return type:

bytes | None

set_device_certificate(ca_privkey_pem, passphrase, program=0)

Set the device certificate

This function sets the device certificate, which is the signature of the following device information:

Device serial number
HW revision
Device public key

The certificate is signed with the so called “Certificate Authority private key” from the PEM file passed as parameter ca_pem_file, the key used should be an Elliptic Curve key (NIST P-256 curve) and the user shall provide also the passphrase to extract the private key.

The certificate is stored on the device in a one-time programmable area, it is primarily used to verify the device public key, see get_dev_pub_key_verified()

Check the guide to generate the certificate authority private key PEM file: OEM Certificate Authority

Parameters:

ca_privkey_pem (str) – Certificate authority private key PEM file path, protected with passphrase.
passphrase (str) – Passphrase for the certificate authority private key PEM file.
program (int) – Set to 1 to actually write the device certificate on the device (0 is the default and is used for testing purpose).

Returns:

Returns True if success. None if failure.

Return type:

True | None

OEM Certificate Authority

Generate CA key pair

The Certificate Authority key pair is a NIST P256 EC key pair.

This can be generated with openssl with the following steps:

Create a new unencrypted EC key:

openssl ecparam -genkey -param_enc named_curve -name prime256v1 -noout -out key_unencrypted.pem

Encrypt the private key:

openssl ec -aes-256-cbc -in key_unencrypted.pem -out ca_privkey.pem

The utility will ask twice for the encryption passphrase.

Erase unencrypted EC key:
```
shred key_unencrypted.pem
```

The corresponding public key PEM file can be generated with the command:

openssl ec -in ca_privkey.pem -passin pass:<you chosen passphrase> -pubout -out ca_pubkey.pem

Warning

It is the OEM Users responsibility to keep the certificate authority private key securely stored! If the private key is compromised, a malicious actor can fake a genuine device and send a forged random number!

The private key PEM file (ca_privkey.pem) it used to generate the device certificate when writing it to the device, this operation can be done with the pyqcicada-cli command:

pyqcicada-cli --set-dev-certificate ca_privkey.pem

The user will be asked to input the PEM passphrase during execution.

Warning

The device certificate can be set just once per device, so pay extreme attention when doing this operation as it cannot be undone!

The public key PEM file (ca_pubkey.pem) can be distributed with your software and will be used to verify the authenticity of a device and perform a verified data read, see Read signed data and verify

Usage examples

The following are some examples on how to use the pyqcicada device class, for base class examples refer to pyqcc device examples .

Device certificate provisioning

# Open the device
qcicadadev = pyqcicada.cmdctrl.device("/dev/ttyACM0")
res = qcicadadev.set_device_certificate("path/to/ca_privkey.pem", "PEM passphrase", 1)
if(res):
   print("Certificate set DONE!")
else:
   print("ERROR Setting device certificate!")

Read signed data and verify

# Open the device
qcicadadev = pyqcicada.cmdctrl.device("/dev/ttyACM0")
# Read the raw device public key, verified with the CA public key
dev_pubkey_verified = qcicadadev.get_dev_pub_key_verified("path/to/ca_pubkey.pem")
if(dev_pubkey_verified):
   print("Device public key valid: " + dev_pubkey_verified.hex())

   data = cc.read_signed_and_verify(args.read_verify, dev_pubkey_verified)
   if(data):
      print("OK: Data signature is valid!")
      print("Data: {:02X} ... {:02X}".format(data[0], data[args.read_verify-1]))
   else:
      print("Error reading signed data")
else:
   print("Device key not valid")

Command Line Interface

The pyqcicada-cli tool is installed with the package and provides some specific QCicada QRNG operations. For basic operations refer to the basic pyqcc-cli included with the pyqcc package, see pyqcc cli documentation .

Command help:

usage: pyqcicada-cli.exe [-h] [-d DEVICE] [--set-certificate QCICADA-CA-PRIVATE] [--reboot] [--get-dev-key]
                      [--get-dev-cert] [--read-verify READ_VERIFY] [--ca-public QCICADA_CA_PUB]

Qcicada Command and Control host utility

optional arguments:
-h, --help            show this help message and exit
-d DEVICE, --device DEVICE
                        Device interface name (default: /dev/ttyACM0)
--set-certificate QCICADA-CA-PRIVATE
                        Certificate Authority private key PEM file, used to set device certificate
--reboot              Reboot Qcicada
--get-dev-key         Read device public key (used to verify signed data)
--get-dev-cert        Read device certificate (used to verify device public key)
--read-verify READ_VERIFY
                        Read Signed random data and verify the signature with the device key
--ca-public QCICADA_CA_PUB
                        QCicada Certificate Authority public key PEM file, used to verify device certificate