Repository files navigation

Note: The support for this product has been discontinued from Mar 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).

SDO is written inJava* 11 and uses theApache Maven* software. The instructions which follow describe a simplebuild and assume familiarity withthe Maven build lifecycle.

To build SDO, runmvn package from the root directory of the SDO source.The build creates files which will be used in the rest of this guide, including:

device/target/device-1.10.8.jar

An implementation of the SDO Device described in the Secure Device Onboard ProtocolSpecification v1.13b, section 2.3. referred to in this document as 'the device', this JARcan be executed via thejava -jar command.

owner/target/owner-1.10.8.war

An implementation of the SDO Owner Server described in the Secure Device Onboard ProtocolSpecification v1.13b, section 2.3. referred to in this document as 'the owner server', this WARcan be deployed in a servlet container likeApache Tomcator executed via thejava -jar command.

rendezvous/target/rendezvous-1.10.8.war

An implementation of the SDO Rendezvous Server described in the Secure Device Onboard ProtocolSpecification v1.13b, section 2.3. Referred to in this document as 'the rendezvous server', thisWAR can be deployed in a servlet container likeApache Tomcator executed via thejava -jar command.

to0client/target/to0client-1.10.8.jar

An implementation of the SDO Owner Client described in the Secure Device Onboard ProtocolSpecification v1.13b, section 2.3. Referred to in this document as 'the owner client', this JARcan be executed via thejava -jar command.

In order to follow the steps in this guide, you must have the SDO Manufacturer Toolkitinstalled and active. See that product's documentation for details.You will need this information in order to proceed:

• the toolkit's database hostname, user, and password
• the address of the toolkit's web server

This guide describes a toolkit configured with aMariaDB* database.You must have theMariaDB command-line clientinstalled to follow the steps in this README.

The device and owner require a key and certificate for identification and attestation (signing).This software supports the following key types:

• ECDSAP-384
• ECDSAP-256
• RSA

This guide will use ECDSA P-384 keys.

Generate a key/certificate pair for the device and one for the owner.To do this withOpenSSL* 1.1.1g, type the following:

NOTE: This are example instructions. Appropriate security measures need to be taken while generatingproduction keys.

openssl ecparam -name secp384r1 -genkey -noout -out <YOUR KEY FILENAME HERE>openssl req -new -x509 -key <YOUR KEY FILENAME HERE> -out <YOUR CERTIFICATE FILENAME HERE> -days <YOUR CERTIFICATE VALIDITY PERIOD HERE> -batch

Replace the text<YOUR KEY FILENAME HERE> with the name of the key file to create.

Replace the text<YOUR CERTIFICATE FILENAME HERE> with the name of the certificate file to create.

Replace the text<YOUR CERTIFICATE VALIDITY PERIOD HERE> with the certificate's desired validityperiod, in days.

Do this twice: once to create the files for the device, and once to create the files for the owner.When this task is complete you will have four new files in total.

For example:

NOTE: This are example instructions. Appropriate security measures need to be taken while generatingproduction keys.

$ openssl ecparam -name secp384r1 -genkey -noout -out device.key$ openssl req -new -x509 -key device.key -out device.crt -days 7 -batch$ openssl ecparam -name secp384r1 -genkey -noout -out owner.key$ openssl req -new -x509 -key owner.key -out owner.crt -days 7 -batch$ lsdevice.crt  device.key  owner.crt  owner.key

The SDO Manufacturer's toolkit needs the owner's public key in order to completedevice initialization. Add the owner's public key to the toolkit's database.

Type the following to add the owner's public key to a MariaDB* database:

mysql --host=<YOUR MANUFACTURER TOOLKIT DATABASE HOST HERE> \      --user=<YOUR MANUFACTURER TOOLKIT DATABASE USER HERE> \      --password=<YOUR MANUFACTURER TOOLKIT DATABASE PASSWORD HERE> << EOFcall rt_add_customer_public_key("README owner", "<YOUR OWNER PUBLIC KEY HERE>");EOF

Replace the text<YOUR MANUFACTURER TOOLKIT DATABASE HOST HERE> with the hostname or addressof your SDO Manufacturer Toolkit database server.

Replace the text<YOUR MANUFACTURER TOOLKIT DATABASE USER HERE> with your ManufacturerToolkit database username.

Replace the text<YOUR MANUFACTURER TOOLKIT DATABASE PASSWORD HERE> with your ManufacturerToolkit database password.

Replace the text<YOUR OWNER PUBLIC KEY HERE> with your PEM-encoded owner public key.

For example:

mysql --host=sdo.example --user=sdo --password=never_use_this_password << EOFcall rt_add_customer_public_key("README owner", "<UNIFIED KEY BLOB>");EOF

For the<UNIFIED KEY BLOB>, keys can be generated by the command below

openssl x509 -in owner.crt -pubkey -noout

Make sure that the keys being assigned in the<UNIFIED KEY BLOB> are in the correct format.

For Example:

ec_256:-----BEGIN PUBLIC KEY-----YOUR KEY GOES HERE-----END PUBLIC KEY-----,ec_384:-----BEGIN PUBLIC KEY-----YOUR KEY GOES HERE-----END PUBLIC KEY-----,rsa_2048:-----BEGIN PUBLIC KEY-----YOUR KEY GOES HERE-----END PUBLIC KEY-----

The SDO device and owner will not output files unless provided a location to do so.Create or select a directory to store SDO data files.

For example:

mkdir sdo-data

The SDO source distribution includes the fileapplication.properties.sample. This filecontains detailed information about each of the Java properties which control the SDOsoftware. This guide assumes familiarity with that document.

Copy the following into a text file namedapplication.properties:

org.sdo.device.cert = <YOUR DEVICE CERTIFICATE HERE>org.sdo.device.key = <YOUR DEVICE KEY HERE>org.sdo.device.output-dir = <YOUR DEVICE OUTPUT HERE>org.sdo.di.uri = <YOUR MANUFACTURER URL HERE>org.sdo.owner.cert = <YOUR OWNER CERTIFICATE HERE>org.sdo.owner.key = <YOUR OWNER KEY HERE>org.sdo.owner.output-dir = <YOUR OWNER OUTPUT HERE>org.sdo.owner.proxy-dir = <YOUR OWNER INPUT HERE>org.sdo.pkix.revocation-checking-enabled = falseorg.sdo.secure-random = SHA1PRNGorg.sdo.to0.ownersign.to1d.bo.port1 = 8042

Replace the text<YOUR DEVICE CERTIFICATE HERE> with the path of your device certificate file.

Replace the text<YOUR DEVICE KEY HERE> with the path of your device key file.

Replace the text<YOUR DEVICE OUTPUT HERE> with the path of your working directory.

Replace the text<YOUR MANUFACTURER URL HERE> with the address of your SDO ManufacturerToolkit web server.

Replace the text<YOUR OWNER CERTIFICATE HERE> with the path of your owner certificate file.

Replace the text<YOUR OWNER KEY HERE> with the path of your owner key file.

Replace the text<YOUR OWNER OUTPUT HERE> with the path of your working directory.

Replace the text<YOUR OWNER INPUT HERE> with the path of your working directory.

For example:

org.sdo.device.cert = ./device.crtorg.sdo.device.key = ./device.keyorg.sdo.device.output-dir = ./sdo-dataorg.sdo.di.uri = http://sdo.example:8039/org.sdo.owner.cert = ./owner.crtorg.sdo.owner.key = ./owner.keyorg.sdo.owner.output-dir = ./sdo-dataorg.sdo.owner.proxy-dir = ./sdo-dataorg.sdo.pkix.revocation-checking-enabled = falseorg.sdo.secure-random = SHA1PRNGorg.sdo.to0.ownersign.to1d.bo.port1 = 8042

More properties are available, but these are enough for basic operation.Advanced settings and information are available inapplication.properties.sample.

Type the following to start the SDO Rendezvous Server:

java -jar <YOUR RENDEZVOUS SERVER WAR HERE>

Replace the text<YOUR RENDEZVOUS SERVER WAR HERE> with the path of the rendezvous server WARyou built in a previous step.

For example:

$ java -jar rendezvous/target/rendezvous-1.10.8.war2020-03-13 11:52:49.981  INFO 12148 --- [           main] org.rendezvous.RendezvousApp   : Starting RendezvousApp...2020-03-13 11:52:55.170  INFO 12148 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8040 (http) with context path ''2020-03-13 11:52:55.180  INFO 12148 --- [           main] org.sdo.rendezvous.RendezvousApp   : Started RendezvousApp in 6.199 seconds (JVM running for 7.1)

Record the server port from the log messages for the next step.In the example above, the server port is 8040.

You can stop the rendezvous server by interrupting it (Ctrl-C on most platforms).

The SDO Manufacturer's toolkit needs the rendezvous server's address in order to generatevalid SDO vouchers. Add the rendezvous server's address to the toolkit's database.

Type the following to add the owner's public key to a MariaDB* database:

mysql --host=<YOUR MANUFACTURER TOOLKIT DATABASE HOST HERE> \      --user=<YOUR MANUFACTURER TOOLKIT DATABASE USER HERE> \      --password=<YOUR MANUFACTURER TOOLKIT DATABASE PASSWORD HERE> << EOFcall mt_add_server_settings("http://<YOUR RENDEZVOUS SERVER HOST>:<YOUR RENDEZVOUS SERVER PORT>", "P1D");EOF

Replace the text<YOUR MANUFACTURER TOOLKIT DATABASE HOST HERE> with the hostname or addressof your SDO Manufacturer Toolkit database server.

Replace the text<YOUR MANUFACTURER TOOLKIT DATABASE USER HERE> with your ManufacturerToolkit database username.

Replace the text<YOUR MANUFACTURER TOOLKIT DATABASE PASSWORD HERE> with your ManufacturerToolkit database password.

Replace the text<YOUR RENDEZVOUS SERVER HOST> with the name of the host on which you arerunning the rendezvous server.

Replace the text<YOUR RENDEZVOUS SERVER PORT> with the server port you recorded in the previousstep.

For example:

mysql --host=sdo.example --user=sdo --password=never_use_this_password << EOFcall mt_add_server_settings("http://sdo.example:8040", "P1D");EOF

Type the following to start the SDO Owner Server:

java -jar <YOUR OWNER SERVER WAR HERE>

Replace the text<YOUR OWNER SERVER WAR HERE> with the path of the owner server WARyou built in a previous step.

For example:

$ java -jar owner/target/owner-1.10.8.warPicked up _JAVA_OPTIONS: -Djava.net.preferIPv4Stack=true2020-03-13 12:08:16.769  INFO 3524 --- [           main] org.sdo.owner.OwnerApp             : Starting OwnerApp...2020-03-13 12:08:21.766  INFO 3524 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8042 (http) with context path ''2020-03-13 12:08:21.772  INFO 3524 --- [           main] org.sdo.owner.OwnerApp             : Started OwnerApp in 5.934 seconds (JVM running for 6.786)

You can stop the owner server by interrupting it (Ctrl-C on most platforms).

Type the following to initialize the SDO device:

java -jar <YOUR DEVICE JAR HERE>

Replace the text<YOUR DEVICE JAR HERE> with the path of the device JARyou built in a previous step.

The device will run the Device Initialization (DI) protocol and exit.

For example:

$ java -jar device/target/device-1.10.8.jarPicked up _JAVA_OPTIONS: -Djava.net.preferIPv4Stack=true2020-03-13 12:16:10.726  INFO 3032 --- [           main] org.sdo.device.DeviceApp           : Starting DeviceApp...2020-03-13 12:16:13.662  INFO 3032 --- [           main] org.sdo.device.DeviceApp           : Started DeviceApp in 3.741 seconds (JVM running for 4.493)...2020-03-13 12:16:12.103  INFO 3032 --- [           main] org.sdo.device.DeviceApp           : property org.sdo.device.serial = 12345678...2020-03-13 12:16:13.664  INFO 3032 --- [           main] org.sdo.device.DeviceApp           : device initialization begins...2020-03-13 12:16:17.371  INFO 3032 --- [           main] c.i.sdo.device.DeviceCredentialsStorage  : credentials saved to ./sdo-data/616d5ba0-d139-426f-9cbf-4997d644268a.oc2020-03-13 12:16:17.373  INFO 3032 --- [           main] org.sdo.device.DeviceApp           : device initialization ends

Record the device's serial number and the path of the stored device credentials from the log.You will need this information to onboard the device. In the example above, the deviceserial number is12345678 and the device credentials are in./sdo-data/616d5ba0-d139-426f-9cbf-4997d644268a.oc.

Run the procedurert_assign_device_to_customer to assign the generated voucher to the README owner you identified in the earlier steps.For example:

mysql --host=sdo.example --user=sdo --password=never_use_this_password << EOFcall rt_assign_device_to_customer('12345678', 'README owner');EOF

Once the device has been initialized, the SDO Manufacturer Toolkit can supply our owner'sOwnership Voucher.

To download the voucher usingcurl, type the following:

curl -G <YOUR MANUFACTURER TOOLKIT WEB SERVER HERE>/api/v1/vouchers/<YOUR DEVICE SERIAL NUMBER HERE> > <YOUR OWNER INPUT HERE>/readme.op

Replace the text<YOUR MANUFACTURER TOOLKIT WEB SERVER HERE> with the address of SDO Manufacturer Toolkit web server.

Replace the text<YOUR DEVICE SERIAL NUMBER HERE> with the serial number from the previous step.

Replace the text<YOUR OWNER INPUT HERE> with the path of your working directory.

For example:

$ curl -G http://sdo.example/api/v1/vouchers/12345678 > ./sdo-data/readme.op  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current                                 Dload  Upload   Total   Spent    Left  Speed100  2270  100  2270    0     0   6185      0 --:--:-- --:--:-- --:--:--  6305

Before the device can be onboarded, the owner must register its new voucher with the rendezvousserver. To register the owner's voucher, type:

java -jar <YOUR OWNER CLIENT JAR HERE> <YOUR OWNER INPUT HERE>/readme.op

Replace the text<YOUR OWNER CLIENT JAR HERE> with the path of the owner client jar froma previous step.

Replace the text<YOUR OWNER INPUT HERE> with the path of your working directory.

For example:

$ java -jar target/to0client-1.10.8.jar ./sdo-data/readme.opPicked up _JAVA_OPTIONS: -Djava.net.preferIPv4Stack=true2020-03-13 12:16:21.830  INFO 17300 --- [           main] org.sdo.to0client.To0ClientApp     : Starting To0ClientApp...2020-03-13 12:16:25.506  INFO 17300 --- [           main] c.i.sdo.OwnerTransferOwnershipClient     : HttpResponse: (POST http://localhost:8040/mp/113/msg/22) 200{content-length=[11], content-type=[text/plain;charset=UTF-8], date=[Fri, 13 Mar 2020 20:16:24 GMT]}{"ws":3600}

In the log above, the finalOK shows that the owner's voucher will be held by the rendezvousservice for one hour, or 3600 seconds. The Secure Device Onboard Protocol Specification namesthis value 'wait seconds' (ws).

Once the owner's voucher has been registered, the device can be onboarded. To onboard the device,type:

java -Dorg.sdo.device.credentials=<YOUR DEVICE CREDENTIALS HERE> -jar <YOUR DEVICE JAR HERE>

Replace the text<YOUR DEVICE CREDENTIALS HERE> with the path of the device credential filegenerated during device initialization.

Replace the text<YOUR DEVICE JAR HERE> with the path of the device JARyou built in a previous step.

For example:

$ java -Dorg.sdo.device.credentials=./sdo-data/616d5ba0-d139-426f-9cbf-4997d644268a.oc -jar device/target/device-1.10.8.jar2020-03-13 12:16:28.544  INFO 14368 --- [           main] org.sdo.device.DeviceApp           : Starting DeviceApp...2020-03-13 12:16:33.996  INFO 14368 --- [           main] org.sdo.device.DeviceApp           : device onboarding ends

The device is now onboarded.