/rendezvous-service

JAVA-based reference implementation for Rendezvous component defined in SDO protocol.

Primary LanguageJavaApache License 2.0Apache-2.0

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).

Table of Contents

  1. About
  2. System Requirements
  3. Build Rendezvous Service War File
  4. Trust Management
  5. Generate Keystores
  6. Run Rendezvous 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:

Java Option Description
Hosts
redis.host Redis database hostname for RV service to connect to - default localhost
redis.port Redis database port for RV service to connect to - default 6379
redis.ssl Redis traffic through an SSL tunnel with stunnel - default false
server.port Rendezvous Service host port for HTTPS - default 8000. To configure HTTP port (default: 8001) for the service, update application.properties
rendezvous.verificationServiceHost Verification service host address (https://verify.epid-sbx.trustedservices.intel.com or https://verify.epid.trustedservices.intel.com)
Keystores You can use default keystore and trustore or you can generate your own, please review section keystores
javax.net.ssl.trustStore truststore file - default rendezvous-keystore.jks
javax.net.ssl.trustStorePassword truststore password - default password: 123456
server.ssl.key-store keystore file - default rendezvous-trustedRootCA.jks
server.ssl.key-store-password keystore password - default password: 123456
Modes
rendezvous.signatureVerification If set to false Intel EPID and ECDSA signatures will not be verified
rendezvous.opKeyVerification If set to false the whole Ownership Voucher will not be verified
Miscellaneous
rendezvous.tOTokenExpirationTime The expiration time for JWT counted in minutes
rendezvous.ownershipVoucherMaxEntries It is the maximum number of entries accepted in the Ownership Voucher
rendezvous.waitSecondsLimit Upper bound in seconds. It is the time the Internet location is waiting for a Device to connect
spring.profiles.active Rendezvous service spring profile (production, development, onprem)
rendezvous.hmacSecret The BASE64-encoded algorithm-specific signing key to use to digitally sign the JWT

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"
}