asbaharoon / rendezvous-service Goto Github PK

Note: The support for this product will be discontinued from Mar 31, 2023. We recommend users to switch to FDO components (https://github.com/secure-device-onboard/pri-fidoiot).

Table of Contents

1. About
2. System Requirements
3. Build Rendezvous Service War File
4. Trust Management
5. Generate Keystores
6. Run Rendezvous Service
   • Rendezvous Service Settings
   • Proxy Settings
   • Run Service
7. Rendezvous Service Docker Deployment

About

This document can be used as a quick guide to build and run the Rendezvous service. Rendezvous service is a software service that permits the Device to find its current Owner.

System Requirements

• Ubuntu 20.04.
• Maven.
• Java 11.
• Docker Engine 19.03.15. (Optional)
• Docker-compose 1.21.2. (Optional)
• Redis database page
• Redis via SSL page - usage of stunnel to secure redis (optional)

Build Rendezvous Service War File

• To build rendezvous service, execute the following command:

$ mvn install

• To clean files generated by previous build, execute the following command:

$ mvn clean

• To generate java documentation, set the following environment variable and then execute the following command:

$ export JAVA_HOME=/path/to/java11
$ mvn javadoc:javadoc 

The documentation is stored in the directory ./target/site/apidocs

• To generate unit tests metrics, execute the following command:

$ mvn clean verify

The code coverage report is stored in the directory ./target/site/jacoco/test/html

Trust Management

Before you read this section please install and set up your Redis* database.

High level information:

The Rendezvous Service is able to trust one or more keys in the Ownership Voucher. This can be done using a back channel to supply public key hashes to the Rendezvous Service as they are created by cooperating supply-chain entities. It is imperative, for security reasons, that these keys are stripped of any associated data that identify the key holder before they are configured into the Rendezvous Service. The Rendezvous Service can block the whole Ownership Voucher by adding one of the keys into the denylist. The Rendezvous Service can block the whole Ownership Voucher by adding GUID into the denylist.

Prepare Ownership Voucher Keys Allowlist:

• Create Redis Hash OP_KEYS_ALLOWLIST
• Calculate SHA256 hash of an ownership voucher public key using command.
  NOTE: Input file cert.pem is an X509 certificate.
  (upper case, example: "0734FAC43DBE455D531930B6A8E024043356541BFFCC7A250E417EC38E217725")

$ openssl x509 -in cert.pem -pubkey -noout | openssl enc -base64 -d > example_allowlist_publickey.der 

• Add the calculated hash to the OP_KEYS_ALLOWLIST with the calculated hash as a key and "1" as a value, example:

$ cat example_allowlist_publickey.der | openssl dgst -sha256 | awk '/s/{print toupper($2)}'
0734FAC43DBE455D531930B6A8E024043356541BFFCC7A250E417EC38E217725

$ redis-cli
$ 127.0.0.1:6379> HSET OP_KEYS_ALLOWLIST "0734FAC43DBE455D531930B6A8E024043356541BFFCC7A250E417EC38E217725" 1
$ (integer) 1
$ 127.0.0.1:6379> HEXISTS OP_KEYS_ALLOWLIST "0734FAC43DBE455D531930B6A8E024043356541BFFCC7A250E417EC38E217725"
$ (integer) 1 

Prepare Ownership Voucher Keys Denylist:

• Create Redis Hash OP_KEYS_DENYLIST
• Calculate SHA256 hash of an ownership voucher public key (upper case, example "3055924C4AF1A77FD365C380F9B3CFC40C5F8C79B1EC6492F0D15648E9792CA2")
• Add the calculated hash to the OP_KEYS_DENYLIST with the calculated hash as a key and "1" as a value, example:

$ cat ./trustmanagement/example_denylist_publickey.der | openssl dgst -sha256 | awk '/s/{print toupper($2)}'

$ redis-cli
$ 127.0.0.1:6379> HSET OP_KEYS_DENYLIST "3055924C4AF1A77FD365C380F9B3CFC40C5F8C79B1EC6492F0D15648E9792CA2" 1
$ (integer) 1
$ 127.0.0.1:6379> HEXISTS OP_KEYS_DENYLIST "3055924C4AF1A77FD365C380F9B3CFC40C5F8C79B1EC6492F0D15648E9792CA2"
$ (integer) 1 

Prepare guid Denylist:

• Create Redis Hash GUIDS_DENYLIST
• Add the guid (upper case, without dashes, example "0000000000000000000000000000FFFF") to the GUIDS_DENYLIST with the guid as a key and "1" as a value, example:

$ redis-cli
$ 127.0.0.1:6379> HSET GUIDS_DENYLIST "0000000000000000000000000000FFFF" 1
$ (integer) 1
$ 127.0.0.1:6379> HEXISTS GUIDS_DENYLIST "0000000000000000000000000000FFFF"
$ (integer) 1 

Generate Keystores

Both keystore and truststore are used to store SSL certificates in the Java* programming language.

The examples of keystore and truststore can be found in the directory certs:

keystore - "rendezvous-keystore.jks"
truststore -  "rendezvous-trustedRootCA.jks"

Default passwords for both: 123456

To see how to generate keystore and truststore, visit page.

Important:

• rendezvous-trustedRootCA.jks must contain a Verification service certificate or root CA to enable communication between the Rendezvous service and the Verification service.
• in case you want to use the secure redis, rendezvous-trustedRootCA.jks must contain a certificate from the configured redis server page
• Keystore and Truststore provided here are example implementation using simplified credentials. This must be changed while performing production deployment.

Run Rendezvous Service

Rendezvous Service Settings

JVM options can be set to configure Rendezvous service:

Proxy Settings

• To use external Verification service from behind proxy set the following JVM flags, more info here:

https.proxyPort
https.proxyHost
http.proxyPort
http.proxyHost

Run Service

To run the Rendezvous service as a war you can use the prepared script rendezvousService.sh.

$ ./rendezvousService.sh

Or you can manually run Rendezvous service, more info here:

$ java [options] -jar ./target/rendezvous-service-*.war

To check whether the Rendezvous service is working properly run the following command:

$ curl --cacert ./certs/ca.cert.pem https://localhost:8000/mp/113/health/full

Expected result:

{
    "sdoComponents": {
        "database": {
            "status": "OK"
        },
        "rvService": {
            "status": "OK",
            "version": "9.99.999"
        },
        "verificationService": {
            "status": "OK",
            "version": "1.0.3096"
        }
    },
    "sdoStatus": "OK"
}