Note: The support for this product has been discontinued from March 31, 2023. FIDO Device Onboard (FDO) is functionally compatible with Secure Device Onboard (SDO). We recommend users to switch to FDO components (https://github.com/secure-device-onboard/pri-fidoiot).
The SDO Supply Chain Tools include multiple web archives (.war files). Which one you select will depend upon your task:
-
Generating new vouchers by initializing devices with the SDO device initialization (DI) protocol and assigning those vouchers to another party is referred to in this README file as the role of manufacturer. Manufacturers use the
manufacturer-webappWAR. -
Accepting existing vouchers and re-assigning them to another party without accessing the device is referred to in this README file as the role of reseller. Resellers use the
reseller-webapp WAR.
To build the toolkits go to the supply-chain-tools directory and run: mvn install
Note: Towards the end of the build you may notice a couple of error messages. These occur due to cleanup of unit test artifacts and do not indicate any issue with the build itself. You can safely ignore these messages.
You will need some supporting software installed to use the SDO Toolkits.
This README file refers to the system running the servlet container as the web server.
The SDO Supply Chain web applications must be installed in a Java servlet container like Apache Tomcat*.
For testing, the WAR files are also executable via the Spring Boot* platform.
The SDO Supply Chain tools are configured via Java properties. In this README file, there are some properties which need to be updated based on servlet container mechanism. Your choice of servlet container will dictate how you set these properties. See your servlet container's documentation for specific instructions.
Common mechanisms include the following:
This README file refers to the system running the database as the database server.
The SDO Toolkits use an SQL database to provide access control, system configuration, and data persistence. The database is not intended for long-term storage of SDO artifacts. It is strongly encouraged to make external backups of generated SDO vouchers.
The SDO Toolkits were tested with MariaDB* server.
Two scripts are provided to initialize the database: mt_create.sql and rt_create.sql.
If you will be acting as a manufacturer, run both scripts to initialize your database.
If you will be acting as a reseller, run the rt_create.sql
script to initialize your database.
These scripts will install a schema named sdo which you
must include in your JDBC* connection string, below.
The SDO Supply Chain Tool Enablement Guides contain details about setting up your database and database users. To proceed, you'll need these things:
- Your database JDBC connection string.
- The name of the database account that the SDO Toolkit software will use.
- The password of that database account.
Place this data in the Spring Data Java properties to connect the web application to the database. For example:
spring.datasource.url=jdbc:mariadb://database.example.com:3306/sdo
spring.datasource.username=sdo_db_user
spring.datasource.password=sdo_db_password
If you will be using PKCS#11 hardware keystores, install a PKCS#11 smart card library on your web server.
The SDO Supply Chain Tools were tested with the OpenSC library.
SDO toolkits use the keys in Java keystores to generate cyptographic signatures. You'll need at least one. Hardware keystores are encouraged, but software keystores are also supported.
The SDO Toolkits were tested with YubiKey* 5 security keys.
Each SDO key algorithm (ECCP256, ECCP384, RSA2048) will need its own hardware key. For each algorithm you want to enable, you will need one hardware key. If you do not support a particular algorithm, you do not need to create a key for that algorithm.
If you are using YubiKey 5 keys with the SDO Toolkits, the ykinit.sh bash script can be used to initialize each key.
To use ykinit.sh, insert only one YubiKey security key into the computer and run ykinit.sh. The script requires one command-line argument: the algorithm of the key to generate. For example:
ykinit.sh ECCP384
As it runs, the script will generate Privacy-Enhanced Mail (PEM)-formatted key and certificate backup files. The names of these files will be printed to the console. Make sure to back these files up to a secure location in case you need to recreate the key in future.
Note: The ykinit script will reformat your YubiKey security key before it stores the new key. Don't use this script on YubiKey security keys that contain important data. It is strongly suggested that you use the YubiKey Manager tool to change the PIN on your YubiKey security key after it has been initialized.
After your YubiKey security keys have been initialized, plug them into your web server.
Set these Java properties in your servlet container to enable auto-detection of the keys when the servlet container starts:
sdo.keystore
Set this to the file: Uniform Resource Identifier (URI) of your installed PKCS#11 provider library.
Example:
sdo.keystore=file:///C:/Program Files/OpenSC Project/OpenSC/pkcs11/opensc-pkcs11.dll
sdo.keystore.password
Set this to the PIN or password of your PKCS#11 keystores.
Example:
sdo.keystore.password=changeit
A PKCS#12 software keystore may be used instead of PKCS#11 hardware keys.
The p12init.sh bash script can be used to generate a suitable PKCS#12 keystore. The script will print the filename of the generated keystore to the console. It is strongly suggested that you back this file up in a secure location.
It is also strongly suggested that you edit this script before use and customize the variables at the top to suit your needs:
CRT_VALID_DAYS: the validity period, in days, of the certificates
in the keystore.
KEYSTORE_PW: the created keystore's password.
Set these Java properties in your servlet container:
sdo.keystore
Set this to the file: URI of your PKCS#12 keystore file.
Example:
sdo.keystore=file:///usr/local/sdo/key.p12
sdo.keystore.password
Set this to the PIN or password of your PKCS#12 keystore.
Example:
sdo.keystore.password=changeit
The SDO Toolkits provide the following REpresentational State Transfer (REST) API:
Returns the web application's version.
Example:
$ curl -G http://sdo.example.com/api/version
{
"build":"5e74afb6e1e1ff5ec88dc9350dfebeaf977c30be",
"version":"1.6.0",
"timestamp":"2019-08-08T20:53:49Z"
}
Returns the web application's database connection status.
Example:
$ curl -G http://sdo.example.com/api/v1/status
{
"connection.databaseProductName":"MySQL",
"connection.databaseProductVersion":"10.4.7-MariaDB",
"connection.url":"jdbc:mariadb://sdodb.example.com:3306/sdo",
"connection.user":"sdo"
}
$ curl -G http://sdo.example.com/api/v1/vouchers/01020304
{"sz":1,"oh":{"pv":112,"pe":1,"r":[2,[4,{"dn"...
Returns the SDO voucher for the identified device.
The SDO Supply Chain Toolkits come with stored procedures which you'll use to control the toolkit. See the Enablement Guide for your toolkit for detailed information.
To use the manufacturer toolkit:
-
Before you start the servlet container, run the stored procedure
mt_add_server_settingsto configure the SDO engine. If you changed the data in this table, restart the servlet container. -
Start the web server.
-
Use the web server to initialize SDO-enabled devices via the SDO DI protocol.
-
Run the stored procedure
rt_add_customer_public_keyto install public keys for entities that will receive your generated SDO vouchers. -
Run the stored procedure
rt_assign_device_to_customerto assign generated vouchers to the entities you identified in the previous step. -
Use the toolkit REST API to download the generated vouchers.
To use the reseller toolkit:
-
Start the web server.
-
Run the stored procedure
rt_add_voucherto place received vouchers in the database. -
Run the stored procedure
rt_add_customer_public_keyto install public keys for entities that will receive your generated SDO vouchers. -
Run the stored procedure
rt_assign_device_to_customerto assign generated vouchers to the entities you identified in the previous step. -
Use the toolkit REST API to download the generated vouchers.
If supporting OnDie ECDSA devices, set the following Java properties in your servlet container. In typical environments, only sdo.ondiecache.cachedir is used. The cachedir is used to store CRL and cert files and can be populated by running the provided script (scripts/onDieCache.py) to load the directory with the files from the cloud.
To run the onDieCache.py script, python3 must be installed. Invoke as follows: python3 onDieCache.py CACHEDIR where CACHEDIR = target location to store CRL and cert files. Typically, this will match the value of sdo.ondiecache.cachedir. However, it is also possible to run the script on a different host and then copy the downloaded files into sdo.ondiecache.cachedir. The exact setup will vary depending on the runtime environment and user needs.
sdo.ondiecache.cachedir
Set this to the file: Uniform Resource Identifier (URI) of the directory that contains the cert and CRL files.
Example:
sdo.ondiecache.cachedir=file:///C:/SDO/ondiecache
sdo.ondiecache.revocations
Set this to true or false to enable revocation checking of OnDie ECDSA signatures. The default value is false. This should not be set to true in production environments and should only set to false when debugging or working with pre-production hardware.
Example:
sdo.ondiecache.revocations=true