Skip to content

GitLab

Commit c8b0b172 authored by EJ Finneran's avatar EJ Finneran
Browse files

Merge branch 'develop' into 'master' 

Draft version

See merge request documentation/a71ch-usage!1
parents b7f59329 a54403b8
Hide whitespace changes
Inline Side-by-side
Showing with 582 additions and 1 deletion
.gitignore 0 → 100644
View file @ c8b0b172
# Created by https://www.gitignore.io/api/intellij+all
# Edit at https://www.gitignore.io/?templates=intellij+all
### Intellij+all ###
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
# User-specific stuff
.idea/**/workspace.xml
.idea/**/tasks.xml
.idea/**/usage.statistics.xml
.idea/**/dictionaries
.idea/**/shelf
# Generated files
.idea/**/contentModel.xml
# Sensitive or high-churn files
.idea/**/dataSources/
.idea/**/dataSources.ids
.idea/**/dataSources.local.xml
.idea/**/sqlDataSources.xml
.idea/**/dynamic.xml
.idea/**/uiDesigner.xml
.idea/**/dbnavigator.xml
# Gradle
.idea/**/gradle.xml
.idea/**/libraries
# Gradle and Maven with auto-import
# When using Gradle or Maven with auto-import, you should exclude module files,
# since they will be recreated, and may cause churn. Uncomment if using
# auto-import.
# .idea/modules.xml
# .idea/*.iml
# .idea/modules
# *.iml
# *.ipr
# CMake
cmake-build-*/
# Mongo Explorer plugin
.idea/**/mongoSettings.xml
# File-based project format
*.iws
# IntelliJ
out/
# mpeltonen/sbt-idea plugin
.idea_modules/
# JIRA plugin
atlassian-ide-plugin.xml
# Cursive Clojure plugin
.idea/replstate.xml
# Crashlytics plugin (for Android Studio and IntelliJ)
com_crashlytics_export_strings.xml
crashlytics.properties
crashlytics-build.properties
fabric.properties
# Editor-based Rest Client
.idea/httpRequests
# Android studio 3.1+ serialized cache file
.idea/caches/build_file_checksums.ser
### Intellij+all Patch ###
# Ignores the whole .idea folder and all .iml files
# See https://github.com/joeblau/gitignore.io/issues/186 and https://github.com/joeblau/gitignore.io/issues/360
.idea/
# Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
*.iml
modules.xml
.idea/misc.xml
*.ipr
# Sonarlint plugin
.idea/sonarlint
# End of https://www.gitignore.io/api/intellij+all
\ No newline at end of file
README.md
View file @ c8b0b172
# a71ch-usage
# NXP A71CH secure element usage on Cascade-500 (ubuntu-core)
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)
#### OpenSSL Docs
* [Introduction to OpenSSL Engine](https://www.openssl.org/blog/blog/2015/10/08/engine-building-lesson-1-a-minimum-useless-engine/)
## 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]
* [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)
* **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`_
You can find sources [here](https://git.rigado.com/documentation/rigado-hsm-server).
* **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)
Please browse client snap example: [a71ch-aws-client](https://git.rigado.com/documentation/a71ch-aws-client) (C++)
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.
Client entry point is [PubSub.cpp](https://git.rigado.com/documentation/a71ch-aws-client/blob/master/Client/PubSub/PubSub.cpp)
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
```
You can find example of **snapcraft.yaml** file [here](https://git.rigado.com/documentation/a71ch-aws-client/blob/master/snap/snapcraft.yaml).
Assembled engine files located in the [jrcp_host/lib](jrcp_host/lib) folder.
#### Engine & client configuration
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
```
- `JRCP_HOSTNAME` and `JRCP_PORT` link to `rigado-hsm-server` snap. _You can target engine to specific JRCP server_
- `OPENSSL_CONF` env variable used by OpenSSL. _You can find example of `opensslA71CH.cnf` [here](./opensslA71CH.cnf)._
_Note: Some libraries can ignore `OPENSSL_CONF` and skip the loading of the engine. Please validate that your transport first._
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).
[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"
opensslA71CH.cnf 0 → 100644
View file @ c8b0b172
# this is completely broken!!! expecting errors!
#
# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.
#
# This definition stops the following lines choking if HOME isn't
# defined.
HOME = .
RANDFILE = $ENV::HOME/.rnd
openssl_conf = nxp_engine
# Extra OBJECT IDENTIFIER info:
#oid_file = $ENV::HOME/.oid
oid_section = new_oids
# To use this configuration file with the "-extfile" option of the
# "openssl x509" utility, name here the section containing the
# X.509v3 extensions to use:
# extensions =
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)
[ new_oids ]
# We can add new OIDs in here for use by 'ca', 'req' and 'ts'.
# Add a simple OID like this:
# testoid1=1.2.3.4
# Or use config file substitution like this:
# testoid2=${testoid1}.5.6
# Policies used by the TSA examples.
tsa_policy1 = 1.2.3.4.1
tsa_policy2 = 1.2.3.4.5.6
tsa_policy3 = 1.2.3.4.5.7
####################################################################
[ ca ]
default_ca = CA_default # The default ca section
####################################################################
[ CA_default ]
dir = ./demoCA # Where everything is kept
certs = $dir/certs # Where the issued certs are kept
crl_dir = $dir/crl # Where the issued crl are kept
database = $dir/index.txt # database index file.
#unique_subject = no # Set to 'no' to allow creation of
# several ctificates with same subject.
new_certs_dir = $dir/newcerts # default place for new certs.
certificate = $dir/cacert.pem # The CA certificate
serial = $dir/serial # The current serial number
crlnumber = $dir/crlnumber # the current crl number
# must be commented out to leave a V1 CRL
crl = $dir/crl.pem # The current CRL
private_key = $dir/private/cakey.pem# The private key
RANDFILE = $dir/private/.rand # private random number file
x509_extensions = usr_cert # The extentions to add to the cert
# Comment out the following two lines for the "traditional"
# (and highly broken) format.
name_opt = ca_default # Subject Name options
cert_opt = ca_default # Certificate field options
# Extension copying option: use with caution.
# copy_extensions = copy
# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
# so this is commented out by default to leave a V1 CRL.
# crlnumber must also be commented out to leave a V1 CRL.
# crl_extensions = crl_ext
default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = default # use public key default MD
preserve = no # keep passed DN ordering
# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy = policy_match
# For the CA policy
[ policy_match ]
countryName = match
stateOrProvinceName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
# For the 'anything' policy
# At this point in time, you must list all acceptable 'object'
# types.
[ policy_anything ]
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
####################################################################
[ req ]
default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca # The extentions to add to the self signed cert
# Passwords for private keys if not present they will be prompted for
# input_password = secret
# output_password = secret
# This sets a mask for permitted string types. There are several options.
# default: PrintableString, T61String, BMPString.
# pkix : PrintableString, BMPString (PKIX recommendation before 2004)
# utf8only: only UTF8Strings (PKIX recommendation after 2004).
# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
# MASK:XXXX a literal mask value.
# WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.
string_mask = utf8only
# req_extensions = v3_req # The extensions to add to a certificate request
[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Some-State
localityName = Locality Name (eg, city)
0.organizationName = Organization Name (eg, company)
0.organizationName_default = Internet Widgits Pty Ltd
# we can do this but it is not needed normally :-)
#1.organizationName = Second Organization Name (eg, company)
#1.organizationName_default = World Wide Web Pty Ltd
organizationalUnitName = Organizational Unit Name (eg, section)
#organizationalUnitName_default =
commonName = Common Name (e.g. server FQDN or YOUR name)
commonName_max = 64
emailAddress = Email Address
emailAddress_max = 64
# SET-ex3 = SET extension number 3
[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
unstructuredName = An optional company name
[ usr_cert ]
# These extensions are added when 'ca' signs a request.
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE
# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server
# For an object signing certificate this would be used.
# nsCertType = objsign
# For normal client use this is typical
# nsCertType = client, email
# and for everything including object signing:
# nsCertType = client, email, objsign
# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment
# This will be displayed in Netscape's comment listbox.
nsComment = "OpenSSL Generated Certificate"
# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren't
# deprecated according to PKIX.
# subjectAltName=email:move
# Copy subject details
# issuerAltName=issuer:copy
#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName
# This is required for TSA certificates.
# extendedKeyUsage = critical,timeStamping
[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
[ v3_ca ]
# Extensions for a typical CA
# PKIX recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
# This is what PKIX recommends but some broken software chokes on critical
# extensions.
#basicConstraints = critical,CA:true
# So we do this instead.
basicConstraints = CA:true
# Key usage: this is typical for a CA certificate. However since it will
# prevent it being used as an test self-signed certificate it is best
# left out by default.
# keyUsage = cRLSign, keyCertSign
# Some might want this also
# nsCertType = sslCA, emailCA
# Include email address in subject alt name: another PKIX recommendation
# subjectAltName=email:copy
# Copy issuer details
# issuerAltName=issuer:copy
# DER hex encoding of an extension: beware experts only!
# obj=DER:02:03
# Where 'obj' is a standard or added object
# You can even override a supported extension:
# basicConstraints= critical, DER:30:03:01:01:FF
[ crl_ext ]
# CRL extensions.
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
# issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always
[ proxy_cert_ext ]
# These extensions should be added when creating a proxy certificate
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE
# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server
# For an object signing certificate this would be used.
# nsCertType = objsign
# For normal client use this is typical
# nsCertType = client, email
# and for everything including object signing:
# nsCertType = client, email, objsign
# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment
# This will be displayed in Netscape's comment listbox.
nsComment = "OpenSSL Generated Certificate"
# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren't
# deprecated according to PKIX.
# subjectAltName=email:move
# Copy subject details
# issuerAltName=issuer:copy
#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName
# This really needs to be in place for it to be a proxy certificate.
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo
####################################################################
[ tsa ]
default_tsa = tsa_config1 # the default TSA section
[ tsa_config1 ]
# These are used by the TSA reply generation only.
dir = ./demoCA # TSA root directory
serial = $dir/tsaserial # The current serial number (mandatory)
crypto_device = builtin # OpenSSL engine to use for signing
signer_cert = $dir/tsacert.pem # The TSA signing certificate
# (optional)
certs = $dir/cacert.pem # Certificate chain to include in reply
# (optional)
signer_key = $dir/private/tsakey.pem # The TSA private key (optional)
default_policy = tsa_policy1 # Policy if request did not specify it
# (optional)
other_policies = tsa_policy2, tsa_policy3 # acceptable policies (optional)
digests = md5, sha1 # Acceptable message digests (mandatory)
accuracy = secs:1, millisecs:500, microsecs:100 # (optional)
clock_precision_digits = 0 # number of digits after dot. (optional)
ordering = yes # Is ordering defined for timestamps?
# (optional, default: no)
tsa_name = yes # Must the TSA name be included in the reply?
# (optional, default: no)
ess_cert_id_chain = no # Must the ESS cert id chain be included?
# (optional, default: no)
[nxp_engine]
engines = engine_section
[engine_section]
e2a71ch = e2a71ch_section
[e2a71ch_section]
engine_id = e2a71ch
dynamic_path = $ENV::SNAP/jrcp_host/lib/libsss_a71ch_engine.so
default_algorithms = RAND,ECDSA,ECDH
init = 1
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment