README.md 7.26 KB
Newer Older
1
# NXP A71CH secure element usage on Cascade-500 (ubuntu-core)
EJ Finneran's avatar
EJ Finneran committed
2

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
This repo contains notes and guides for developers which want to use features of the A71CH module built-in Rigado Cascade-500 gateways.

_Disclaimer: This guide based on A71CH OpenSSL Engine and OpenSSL example scripts which you can find in [A71CH Host Software Package: Bash Installer for e.g. Linux or Cygwin](https://www.nxp.com/webapp/Download?colCode=A71CH_01.06.00_20190318)_

## Please Read First 

#### NXP A71CH Docs

* [NXP A71CH: Product overview](https://www.nxp.com/products/security-and-authentication/authentication/plug-and-trust-the-fast-easy-way-to-deploy-secure-iot-connections:A71CH)
* [AN12133: A71CH Host software package documentation](https://www.nxp.com/docs/en/application-note/AN12133.pdf)
* [A71CH Host Software Package: Bash Installer for e.g. Linux or Cygwin](https://www.nxp.com/webapp/Download?colCode=A71CH_01.06.00_20190318)

#### Snap Docs

* [Snapcraft: Getting started](https://snapcraft.io/docs/getting-started)
* [Snapcraft: snapcraft.yaml reference](https://snapcraft.io/docs/snapcraft-yaml-reference)
* [Snapcraft: Slots and plugs](https://snapcraft.io/docs/interface-management)
* [Snapcraft: interface type `content`](https://forum.snapcraft.io/t/the-content-interface/1074)

22
23
24
25
26

#### OpenSSL Docs

* [Introduction to OpenSSL Engine](https://www.openssl.org/blog/blog/2015/10/08/engine-building-lesson-1-a-minimum-useless-engine/)

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
## Components Overview

#### A71CH Host API usage example using A71CH Host API functions

![alt text][A71CH Host API usage]

* **A71CH microcontroller** - The A71CH is a ready-to-use solution enabling ease-of-use security for IoT device makers. It is a secure element capable of securely storing and provisioning credentials, securely connecting IoT devices to public or private clouds and performing cryptographic device authentication
* **Host Library** - A71CH Host Library behaves as the interface between a host microcontroller application and the A71CH security IC. The A71CH executes the different APDUs and gives back the results to the Host Library through the same interface. The complete set of A71CH Host Library functions can be called from communication stacks like TLS or an application running on the host.
* **A71CH Host API** - It is the implementation of the API dealing with A71CH security IC specific functionality. These source files implement the core functionality of the Host Library and provide a C interface abstracting the underlying APDU exchange mechanism between the Host MCU and the A71CH security module.
* **APDU layer** - It is the layer in charge of translating the A71CH Host API function calls to the APDU commands that are delivered to the A71CH via the host interface.
* **OpenSSL** - is a software library for applications that secure communications over computer networks against eavesdropping or need to identify the party at the other end.
* **OpenSSL engine** - With OpenSSL 0.9.6, a new component was added to support alternative cryptography implementations, most commonly for interfacing with external crypto devices (eg. accelerator cards).

#### Secure client use OpenSSL with A71CH

![alt text][OpenSSL client call-stack]

#### A71CH Host API Usage via Snaps on Cascade-500

![alt text][Snaps Host API usage]

Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
48
49
* [rigado-hsm-server snap](https://git.rigado.com/documentation/rigado-hsm-server) - NXP A71CH JRCP server and configuration tools for Rigado gateway. This snap implements A71CH Host API functions and configuration tools.
* **a71ch-custom snap** - custom snap which want to use AC71CH features (with OpenSSL). Example: [a71ch-aws-client](https://git.rigado.com/documentation/a71ch-aws-client)
50
51
52
53
54
55
* **a71ch device** - i2c device/interface in linux devicetree connected to AC71CH hardware module.

#### rigado-hsm-server snap

_Disclaimer: For now `rigado-hsm-server` snap is require `devmode`_

Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
56
You can find sources [here](https://git.rigado.com/documentation/rigado-hsm-server).
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

* **rigado-hsm-server.jrcp-server** - system daemon which implements  A71CH Host API via sockets (by default tcp://127.0.0.1:8050).
* **rigado-hsm-server.A71CHConfigToolSCI2C** - a command-line utility which allow get/set sci2c configuration. Use `--help` option to get additional info
* **rigado-hsm-server.A71CHConfigToolJRCP** - a command-line utility which allow get/set JRCP server configuration. Use `--help` option to get additional info
* **rigado-hsm-server.init_A71CH_openssl** - the script which erases chip and generates new keypair inside a71ch, reference key and new cert (3650 days) signed by reference key.
* **apdu_player** - command-line utility which allows playing APDU layer files such as `initialize.jcsh`. Needs for pre-provisioning of a71ch chip.
* `lib-cert` slot - mount point for files which required for provisioning procedure.
* `lib-engine` slot - mount point for shared library (*.so) files of custom openssl engine.

#### a71ch linux device

There several i2c devices available from host OS on Cascade-500 gateway. A71CH settings:

* Path `/dev/i2c-3`
* Address `0x49`

## How to develop client snap (OpenSSL)

Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
75
Please browse client snap example: [a71ch-aws-client](https://git.rigado.com/documentation/a71ch-aws-client) (C++)
76
77
78

This snap implement connectivity example which is scan BLE beacons (via HCI interface), transform scan results as JSON and send payloads via MQTTs to AWS IoT Core.

Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
79
Client entry point is [PubSub.cpp](https://git.rigado.com/documentation/a71ch-aws-client/blob/master/Client/PubSub/PubSub.cpp)
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

Due to client snap init OpenSSL session all required files such as custom OpenSSL config and engine shared libraries should be available both in client and server snaps.

For that purpose, it makes sense to use `content` plugs and slots.

**snapcraft.yaml**  should implement following plugs:
```
plugs:
  lib-cert: # store openssl config and etc
    interface: content
    content: lib-cert
    target: certs
  lib-engine: # store engine so files
    interface: content
    content: lib-engine
    target: jrcp/lib
```

Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
98
You can find example of **snapcraft.yaml** file [here](https://git.rigado.com/documentation/a71ch-aws-client/blob/master/snap/snapcraft.yaml).
99
100
101
102
103

Assembled engine files located in the [jrcp_host/lib](jrcp_host/lib) folder.

#### Engine & client configuration

104
105
106
107
108
109
110
To use NXP A71CH via OpenSSL you should load OpenSSL Engine. Use the following environment variables to load Engine.

```bash
export JRCP_HOSTNAME=127.0.0.1
export JRCP_PORT=8050
export OPENSSL_CONF=$SNAP/certs/opensslA71CH.cnf
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/jrcp/lib
111
```
112
113
 
- `JRCP_HOSTNAME` and `JRCP_PORT` link to `rigado-hsm-server` snap. _You can target engine to specific JRCP server_
Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
114
- `OPENSSL_CONF` env variable used by OpenSSL. _You can find example of `opensslA71CH.cnf` [here](./opensslA71CH.cnf)._
115
116
117

_Note: Some libraries can ignore `OPENSSL_CONF` and skip the loading of the engine. Please validate that your transport first._

Vladimir Kiryakov's avatar
Vladimir Kiryakov committed
118
After configuring OpenSSL Engine we can generate keypair and certificate request. You can find example [here](https://git.rigado.com/documentation/rigado-hsm-server/blob/master/rootfs/bin/init_A71CH_openssl).
119

120
121
122
123

[Snaps Host API usage]: images/snaps.png "A71CH Host API Usage via Snaps on Cascade-500"
[A71CH Host API usage]: images/nxp.png "A71CH Host API usage example using A71CH Host API functions"
[OpenSSL client call-stack]: images/flow.png "OpenSSL Client Call-Stack"