PR cBRSKI updates - v0.3

GUIDE.md

@@ -6,134 +6,159 @@ All setup commands assume you are starting in the project's root directory.
 
 1. Bootstrap
 
-    Install the [java](https://openjdk.java.net/), [maven](https://maven.apache.org/), and [ace-java](https://bitbucket.org/marco-tiloca-sics/ace-java) packages:
+    Install the required packages ([java](https://openjdk.java.net/), [maven](https://maven.apache.org/)):
 
     ```bash
     ./script/bootstrap.sh
     ```
 
 2. Build
 
-    Run unit tests and build the OT Registrar JAR package:
+    Build and run unit tests for the OT Registrar JAR package:
 
     ```bash
     mvn package
     ```
 
-    To skip the tests:
+    Or, to skip the tests:
 
     ```bash
     mvn -DskipTests package
     ```
 
-    This creates a JAR file at `target/ot-registrar-0.1-SNAPSHOT-jar-with-dependencies.jar`.
+    Either of these creates a JAR file at `target/ot-registrar-0.3-jar-with-dependencies.jar`.
 
 ## Run services
 
-The OT Registrar JAR file includes the Registrar, TBD [MASA](https://tools.ietf.org/id/draft-ietf-anima-bootstrapping-keyinfra-16.html#rfc.section.1.2) server, and a simulated [Pledge](https://tools.ietf.org/id/draft-ietf-anima-bootstrapping-keyinfra-16.html#rfc.section.1.2).
+The OT Registrar JAR file includes the Registrar, MASA server, and a simulated Pledge. These 3 components are sufficient to do a test run of the system.
 
 ### Credentials
 
 To run the registrar or MASA server, we need a structured keystore file (in PKCS#12 format) containing the credentials.
 
-See [credentials/README.md](credentials/README.md) for details on how to generate credentials. For this guide, we'll use the
-`threadgroup-5f9d307c.p12` credentials provided with OT Registrar.
+Details on how to generate credentials will be added at a later time. For this guide, we'll use 
+credentials provided with OT Registrar in the `credentials` directory.
 
 ### Run the registrar
 
-Start the registrar at port 5684, using the `threadgroup-5f9d307c.p12` credentials:
+Start the registrar at default CoAPS port 5684, using the default credentials:
 
 ```bash
-java -cp target/ot-registrar-0.1-SNAPSHOT-jar-with-dependencies.jar com.google.openthread.registrar.RegistrarMain -d Thread -f credentials/threadgroup-5f9d307c.p12 -p 5684
+$ ./script/run -registrar
 ```
 
 Use the `-h` option to learn what arguments are available:
 
-```bash
-java -cp target/ot-registrar-0.1-SNAPSHOT-jar-with-dependencies.jar com.google.openthread.registrar.RegistrarMain -h
-# usage: registrar -d <domain-name> -f <keystore-file> -p <port>
-#  -d,--domainname <domain-name>   the domain name
-#  -f,--file <keystore-file>       the keystore file in PKCS#12 format
-#  -h,--help                       print this message
-#  -p,--port <port>                the port to listen on
-#  -v,--verbose                    verbose mode with many logs
+```text
+$ ./script/run -h
+usage: [-registrar | -masa | -pledge] [-h] [-v] [-d <domain-name>] [-f
+                   <keystore-file>] [-p <udp-port>]
+ -d,--domainname <domain-name>       the domain name
+ -f,--keyfile <keystore-file>        the keystore file in PKCS#12 format
+ -h,--help                           print this message
+ -m,--masaUri <forced-masa-uri>      force the given MASA URI instead of
+                                     the default one
+ -masa                               start as cBRSKI/BRSKI MASA
+ -p,--port <server-port>             the server CoAPS or HTTPS port to
+                                     listen on
+ -pledge                             start as cBRSKI Pledge
+ -r,--registrarUri <registrar-uri>   for a Pledge, the Registrar to
+                                     connect to
+ -registrar                          start as cBRSKI Registrar
+ -v,--verbose                        verbose mode with many logs
 ```
 
 ### Run the MASA server
 
-Start the MASA server at port 5685, using the `threadgroup-5f9d307c.p12` credentials:
-
-```bash
-java -cp target/ot-registrar-0.1-SNAPSHOT-jar-with-dependencies.jar com.google.openthread.masa.MASAMain -f credentials/threadgroup-5f9d307c.p12 -p 5685
-```
-
-Use the `-h` option to learn what arguments are available:
+Start the MASA server in another window or tab at port 9443, using the default credentials:
 
 ```bash
-java -cp target/ot-registrar-0.1-SNAPSHOT-jar-with-dependencies.jar com.google.openthread.masa.MASAMain -h
-# usage: masa -a <alias> -f <keystore-file> -p <port>
-#  -a,--alias <alias>          the masa keystore alias
-#  -f,--file <keystore-file>   the keystore file in PKCS#12 format
-#  -h,--help                   print this message
-#  -p,--port <port>            the port to listen on
-#  -v,--verbose                verbose mode with many logs
+$ ./script/run -masa -p 9443
+...
 ```
 
 ### Run the pledge
 
 Use a simulated pledge to test the Registrar.
 
-Start the pledge:
+Start the pledge in another shell window or tab, connecting to a specific host and port where the Registrar is expected:
 
 ```bash
-java -cp target/ot-registrar-0.1-SNAPSHOT-jar-with-dependencies.jar com.google.openthread.pledge.PledgeMain -f credentials/threadgroup-5f9d307c.p12 -r "[::1]:5684"
-# ...
-# >
+$ ./script/run -pledge -r "[::1]:5684"
+...
 ```
 
 The pledge enters interactive mode and waits for user commands. Press **Enter** or type `help` to get a list of all available commands:
 
 ```text
 > help
-token    -  request commissioning token
-rv       -  request voucher
-attrs    -  request CSR attributes
-enroll   -  simple enrollment
-reenroll -  simple reenrollment
-reset    -  reset to initial state
+rv       -  request voucher to Registrar (cBRSKI)
+enroll   -  simple enrollment with Registrar (EST)
+reenroll -  simple reenrollment with Registrar (EST)
+reset    -  reset Pledge to initial state
 exit     -  exit pledge CLI
 help     -  print this help message
-
-done
+Done
 >
 ```
 
 Use the `exit` command to exit or **Ctrl+c** to force exit.
 
-### Run the Thread Registrar Interface (TRI)
+Use `rv` to let the Pledge attempt a cBRSKI Voucher Request:
 
-A TRI is needed to connect Thread devices with a registrar. Please see the [TRI project](https://bitbucket.org/threadgroup/tce-registrar-java) for instructions.
+```text
+> rv
+19:30:24.606 [DTLS-Connection-Handler-5] INFO com.google.openthread.pledge.PledgeCertificateVerifier - registrar provisionally accepted without verification!
+Done
+```
 
-> Note: Only Thread Group members can access the TRI project.
+Now the Voucher is obtained from MASA, via the Registrar. Mutual trust is established for the active DTLS connection. Use `enroll` to perform the EST-CoAPS enrollment:
 
-There is script [script/run-servers.sh](script/run-servers.sh) that starts all those servers in the background with the default arguments.
+```text
+> enroll
+19:34:58.825 [main] INFO com.google.openthread.pledge.Pledge - enrolled with operational certificate, subject: C=US,ST=CA,L=San Ramon,O=TestVendor,2.5.4.5=#130a41383544333330303031,CN=TestVendor IoT device
+19:34:58.827 [main] INFO com.google.openthread.pledge.Pledge - operational certificate (PEM): 
+-----BEGIN CERTIFICATE-----
+MIICEDCCAbegAwIBAgIBAzAKBggqhkjOPQQDAjBTMREwDwYDVQQDDAhkb21haW5j
+YTETMBEGA1UECwwKT3BlblRocmVhZDEPMA0GA1UECgwGR29vZ2xlMQswCQYDVQQH
+DAJTSDELMAkGA1UEBhMCQ04wHhcNMjQwODI4MTkzNDU4WhcNMjkwODI3MTkzNDU4
+WjB4MR4wHAYDVQQDDBVUZXN0VmVuZG9yIElvVCBkZXZpY2UxEzARBgNVBAUTCkE4
+NUQzMzAwMDExEzARBgNVBAoMClRlc3RWZW5kb3IxEjAQBgNVBAcMCVNhbiBSYW1v
+bjELMAkGA1UECAwCQ0ExCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0D
+AQcDQgAEGwAmAr657PJ63qBg2axjNTK0FhT0pI11qn5mUq6TQFF6RjU22zqqbJZl
+a7EbDmVRouS+6jIM/8yycqE2NrwQ3aNXMFUwCQYDVR0TBAIwADAfBgNVHSMEGDAW
+gBSe2sIzlf9yKOt9rsh9GC356FdvVzAnBgNVHREEIDAeoBwGCSsGAQQBgt8qAaAP
+Fg1EZWZhdWx0RG9tYWluMAoGCCqGSM49BAMCA0cAMEQCIDD63H5wYJVvo+sKgt3S
+U38XMON3cYz/5KlF1PmxnmJjAiBKujydxak63+L2aZB/H3YoYq0M53xRQMRUGRku
+75pjeg==
+-----END CERTIFICATE-----
+
+19:34:58.829 [main] INFO com.google.openthread.pledge.Pledge - operational private key (PEM): 
+-----BEGIN EC PRIVATE KEY-----
+MHcCAQEEIPPqdOhhBgm/RdVsd4SVQ2g3/U4KVC2mtP2RzCbgL0oNoAoGCCqGSM49
+AwEHoUQDQgAEGwAmAr657PJ63qBg2axjNTK0FhT0pI11qn5mUq6TQFF6RjU22zqq
+bJZla7EbDmVRouS+6jIM/8yycqE2NrwQ3Q==
+-----END EC PRIVATE KEY-----
+
+Done
+```
 
 ## The Docker service
 
-You can use `script/run-servers.sh` to run all services in a local host. To avoid having to frequently start and stop all three servers, OT Registrar provides a Docker image to start all services with a single command.
+You can use `script/run-servers.sh` to run both Registrar and MASA on the local host. To avoid having to frequently start and stop servers, OT Registrar provides a Docker image to start all services with a single command.
 
 _**Note:** Only supported on Linux._
 
-1. Complete the [setup](#setup) if you haven't already.
+1. Do the bootstrap script if you haven't already.
 
 2. Build the Docker image:
 
     ```bash
     ./script/build-docker-image.sh
     ```
 
-3. Start all services:
+3. Start all services in a Docker:
 
     ```bash
-    ./script/start-services.sh
+    ./script/start-service.sh
     ```

README.md

@@ -18,6 +18,7 @@ Contributors are required to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Versioning
 
+Release notes for versions are kept in MD files in [releases](releases).
 OT Registrar follows the [Semantic Versioning guidelines](http://semver.org/) for release cycle transparency and to maintain backwards compatibility. OT Registrar's versioning is independent of the Thread protocol specification version.
 
 ## License

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>com.google.openthread</groupId>
   <artifactId>ot-registrar</artifactId>
-  <version>0.2</version>
+  <version>0.3</version>
 
   <name>OT Registrar</name>
   <url>https://openthread.io/</url>
@@ -94,12 +94,6 @@
       <version>2.2.8.Final</version>
     </dependency>
 
-    <dependency>
-      <groupId>com.fazecast</groupId>
-      <artifactId>jSerialComm</artifactId>
-      <version>[2.0.0,3.0.0)</version>
-    </dependency>
-
   </dependencies>
 
   <build>

releases/ot-registrar-0.2-readme.md

@@ -0,0 +1,22 @@
+# OT Registrar 0.2
+
+This is the Registrar, MASA and Pledge release optimized for testing the cBRSKI protocol.
+See [cBRSKI draft](https://datatracker.ietf.org/doc/html/draft-ietf-anima-constrained-voucher-25).
+It is an initial release made in July 2024 by IoTconsultancy.nl.
+
+## Platform
+
+Written in Java, the registrar runs where Java does:
+
+- Linux
+- Windows
+- macOS
+- Raspberry Pi
+
+## Certificates / Credentials
+
+Various sets of credentials for testing are present in the `credentials` directory.
+
+### Hosted Resources of the MASA and Registrar.
+
+Details can be found in the cBRSKI draft.

releases/ot-registrar-0.3-readme.md

@@ -0,0 +1,23 @@
+# OT Registrar 0.3
+
+This is the Registrar, MASA and Pledge release optimized for testing the cBRSKI protocol.
+See [cBRSKI draft](https://datatracker.ietf.org/doc/html/draft-ietf-anima-constrained-voucher-25).
+It is a follow-up release made in TBD 2024 by IoTconsultancy.nl for testing cBRSKI Thread devices
+in a Github branch of the [OTNS2 simulator](https://github.com/EskoDijk/ot-ns).
+
+## Platform
+
+Written in Java, the registrar runs where Java does:
+
+- Linux
+- Windows
+- macOS
+- Raspberry Pi
+
+## Certificates / Credentials
+
+Various sets of credentials for testing are present in the `credentials` directory.
+
+### Hosted Resources of the MASA and Registrar.
+
+Details can be found in the cBRSKI draft.

script/build.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+#
+#  Copyright (c) 2024, The OpenThread Registrar Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+mvn package -DskipTests

script/helper-cp-run.sh

@@ -27,7 +27,7 @@
 #  POSSIBILITY OF SUCH DAMAGE.
 #
 
-readonly JAR_FILE=./target/ot-registrar-0.2-jar-with-dependencies.jar
+readonly JAR_FILE=./target/ot-registrar-0.3-jar-with-dependencies.jar
 
 # test if OT Registrar JAR exists
 if [ ! -f  "${JAR_FILE}" ]; then

script/run

@@ -27,11 +27,11 @@
 #  POSSIBILITY OF SUCH DAMAGE.
 #
 
-readonly JAR_FILE=./target/ot-registrar-0.2-jar-with-dependencies.jar
+readonly JAR_FILE=./target/ot-registrar-0.3-jar-with-dependencies.jar
 
 # test if OT Registrar JAR exists
 if [ ! -f  "${JAR_FILE}" ]; then
-  echo "Please build using 'mvn -DskipTests package' before running."
+  echo "Please build project using 'mvn -DskipTests package' before running."
   exit 1
 fi