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).
- About
- System Requirements
- Build Rendezvous Service War File
- Trust Management
- Generate Keystores
- Run Rendezvous Service
- Rendezvous Service Docker Deployment
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.
- 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)
- 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
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
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.
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 |
- To use external Verification service from behind proxy set the following JVM flags, more info here:
https.proxyPort
https.proxyHost
http.proxyPort
http.proxyHost
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"
}