Documentation update

Fixes eclipse#659

Also clarifies jwt token naming for server and
need to specify servername for tls

NOTICE.md

@@ -17,7 +17,7 @@ source code repository logs.
 ## Declared Project Licenses
 
 This program and the accompanying materials are made available under the terms
-of the  Apache License, Version 2.0 
+of the  Apache License, Version 2.0
 
 You may obtain a copy of the License at
 http://www.apache.org/licenses/LICENSE-2.0
@@ -47,7 +47,7 @@ archaius-core (0.6.6)
 autobahn-python (18.9.2)
 
 * License: MIT
-* Project: https://crossbar.io/autobahn/
+* Project: https://github.com/crossbario/autobahn-python
 * Source: https://github.com/crossbario/autobahn-python/releases/tag/v18.9.2
 
 bcpkix-jdk15on (1.60)
@@ -747,7 +747,7 @@ springfox-spring-web (2.7.0)
 springfox-swagger-ui (2.6.1)
 
 * License: MIT AND Apache-2.0 AND BSD-3-Clause AND CC-BY-SA-2.5 AND (MIT OR
-   GPL-2.0) 
+   GPL-2.0)
 
 springfox-swagger-ui (2.7.0)
 

data/vss-core/README.md

@@ -39,7 +39,7 @@ This is the process for introducing support for a new VSS version:
 * If needed, adapt or extend test cases to use the new version instead of previous version
 * Remember to also integrate new version in [KUKSA Feeder](https://github.com/eclipse/kuksa.val.feeders) repository
     * Needed for [dbc2val](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/mapping/mapping.md)
-    * Needed for [dds2val](https://github.com/eclipse/kuksa.val.feeders/blob/main/dds2val/ddsproviderlib/idls/generate_py_dataclass.sh) 
+    * Needed for [dds2val](https://github.com/eclipse/kuksa.val.feeders/blob/main/dds2val/ddsproviderlib/idls/generate_py_dataclass.sh)
 
 ### Release Candidate Handling
 
@@ -108,12 +108,12 @@ Test Client> getValue Vehicle.CurrentLocation.Longitude
 
 ### Kuksa-val-server and dbc2val smoke test
 
-Run dbc2val as described in [documentation](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/Readme.md) using example [dump file](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/candump.log). Verify that no errors appear in kuksa-val-server log. Not all signals in the [mapping files](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/mapping/) are used by the example dump file, but it can be verified using Kuksa Client that e.g. `Vehicle.Speed` has been given a value.
+Run dbc2val as described in [documentation](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/README.md) using example [dump file](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/candump.log). Verify that no errors appear in kuksa-val-server log. Not all signals in the [mapping files](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/mapping/) are used by the example dump file, but it can be verified using Kuksa Client that e.g. `Vehicle.Speed` has been given a value.
 
 
 ### Kuksa-val-server and gps2val smoke test
 
-Run gps2val as described in [documentation](https://github.com/eclipse/kuksa.val.feeders/blob/main/gps2val/readme.md) using example log. If gpsd already is running at port 2947 a different port like 2949 may be used. Then [gps2val config file](https://github.com/eclipse/kuksa.val.feeders/blob/main/gps2val/config/gpsd_feeder.ini) must also be updated to use that port. If device handling does not work on test platform `-t` can be used to uss TCP instead.
+Run gps2val as described in [documentation](https://github.com/eclipse/kuksa.val.feeders/blob/main/gps2val/README.md) using example log. If gpsd already is running at port 2947 a different port like 2949 may be used. Then [gps2val config file](https://github.com/eclipse/kuksa.val.feeders/blob/main/gps2val/config/gpsd_feeder.ini) must also be updated to use that port. If device handling does not work on test platform `-t` can be used to uss TCP instead.
 
 ```
 gpsfake -t -P 2949 simplelog_example.nmea
@@ -164,4 +164,3 @@ Run dbc2val as described in [documentation](https://github.com/eclipse/kuksa.val
 ./dbcfeeder.py --usecase databroker --address=127.0.0.1:55555
 ```
 Verify that no errors appear in kuksa-val-server log. Not all signals in the [mapping files](https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/mapping) are used by the example dump file, but it can be verified using Kuksa Client that e.g. `Vehicle.Speed` has been given a value.
-

doc/tls.md

@@ -12,14 +12,14 @@ General design concept in short:
 * You can use configuration settings to control whether Server or databroker shall require secure connections.
 * Default connection type may vary between tools, and may be changed in future releases.
 * Mutual authentication is not supported, i.e. KUKSA.val Server and KUKSA.val Databroker does not authenticate clients
-* A set of example certificates and keys exist in the [kuksa_certificates](kuksa_certificates) repository
+* A set of example certificates and keys exist in the [kuksa_certificates](../kuksa_certificates) repository
 * The example certificates are used as default by some applications
 * The example certificates shall only be used during development and re not suitable for production use
 * KUKSA.val does not put any additional requirements on what certificates that are accepted, default settings as defined by OpenSSL and gRPC are typically used
 
 ## Example certificates
 
-For more information see the [README.md](kuksa_certificates/README.md).
+For more information see the [README.md](../kuksa_certificates/README.md).
 
 **NOTE: The example keys and certificates shall not be used in your production environment!**
 
@@ -61,8 +61,6 @@ so if running KUKSA.val Databroker from a default container you need to mount th
 ## KUKSA.val databroker-cli
 
 Can be run in TLS mode like below.
-Note that [databroker-cli](kuksa_databroker/databroker-cli/src/main.rs) currently expects the certificate
-to have "Server" as subjectAltName.
 
 ```
 ~/kuksa.val/kuksa_databroker$ cargo run --bin databroker-cli -- --ca-cert ../kuksa_certificates/CA.pem

kuksa-client/README.md

@@ -90,15 +90,15 @@ There is actually no reason to specify client key and certificate, as mutual aut
 so the command can be simplified like this:
 
 ```
-kuksa-client  --cacertificate ./kuksa_certificates/CA.pem grpcs://localhost:55555
+kuksa-client --cacertificate ./kuksa_certificates/CA.pem grpcs://localhost:55555
 ```
 
 The example server protocol list 127.0.0.1 as an alternative name, but the TLS-client currently used does not accept it,
 instead a valid server name must be given as argument.
 Currently `Server` and `localhost` are valid names from the example certificates.
 
 ```
-kuksa-client  --cacertificate ../kuksa_certificates/CA.pem --tls-server-name Server grpcs://127.0.0.1:55555
+kuksa-client --cacertificate ../kuksa_certificates/CA.pem --tls-server-name Server grpcs://127.0.0.1:55555
 ```
 
 ### TLS with val-server
@@ -114,6 +114,9 @@ This corresponds to this call:
 kuksa-client --cacertificate ../kuksa_certificates/CA.pem wss://localhost:8090
 ```
 
+In some environments the `--tls-server-name` argument must be used to specify alternative server name
+if connecting to the server by numerical IP address like `wss://127.0.0.1:8090`.
+
 ### Authorizing against KUKSA Server
 If the connected KUKSA Server or KUKSA Databroker require authorization the first step after a connection is made is to authorize. KUKSA Server and KUKSA Databroker use different token formats.
 

kuksa-val-server/README.md

@@ -22,8 +22,8 @@ See [Supported Protocol](../doc/protocol/README.md) for a detailled overview of
 
 ## Quick start
 
-### Using  Docker Image
-If you prefer to build kuksa.val yourself skip to [Building KUKSA.val](#Building-kuksaval).
+### Using Docker Image
+If you prefer to build kuksa.val yourself skip to [Building KUKSA.val](#building-kuksaval).
 
 Download a current KUKSA.val server docker image from one of our container registry:
 
@@ -48,11 +48,11 @@ More information on using the docker images can be found [here](../doc/KUKSA.val
 
 To learn, how to build your own docker image see [doc/build-docker.md](../doc/KUKSA.val_server/build-docker.md).
 
-If this is succesful you can skip to [using kuksa.val](#using-kuksaval).
+If this is successful you can skip to [using kuksa.val](#using-kuksaval).
 
 ## Building kuksa.val
 
-First you need to fetch the source. ;ake sure you also get the needed submodules, e.g. by using the `--recursive` flag
+First you need to fetch the source. Make sure you also get the needed submodules, e.g. by using the `--recursive` flag
 
 ```
 git clone --recursive https://github.com/eclipse/kuksa.val.git
@@ -75,17 +75,15 @@ mkdir build
 cd build
 cmake ..
 ```
-If there are any missing dependencies, cmake will tell you. If everythig works fine, execute make
+If there are any missing dependencies, cmake will tell you. If everything works fine, execute make
 
 ```
 make
 ```
 
 (if you have more cores, you can speed up compilation with something like  `make -j8`
 
-Additional information about our cmake setup (in case you need adavanced options or intend to extend it) can be [found here](../doc/cmake.md).
-
-
+Additional information about our cmake setup (in case you need advanced options or intend to extend it) can be [found here](../doc/KUKSA.val_server/cmake.md).
 
 ### Running kuksa.val
 After you successfully built the kuksa.val server you can run it like this

kuksa_certificates/README.md

@@ -10,7 +10,7 @@ This directory contain a set of example certificates, used by the KUKSA-project
 They may or may not be useful for your test environment.
 If needed you can customize `genCerts.sh` and generate keys and certificates that fits your environment.
 
-See the [KUKSA.val TLS documentation](../tls.md) for general information on the KUKSA.val TLS concept.
+See the [KUKSA.val TLS documentation](../doc/tls.md) for general information on the KUKSA.val TLS concept.
 
 This directory contains the following files with cryptographical information.
 
@@ -20,7 +20,7 @@ This directory contains the following files with cryptographical information.
 | `CA.pem` | Root certificate, valid for 3650 days ( 10 years). |
 | `Server.key` | Server key, needed by KUKSA.val Databroker/Server for TLS. |
 | `Server.pem` | Server certificate chain, valid for 365 days, needed by KUKSA.val Databroker/Server for TLS. |
-| `CLient.key` | Client key, currently not needed as mutual authentication is not supported. |
+| `Client.key` | Client key, currently not needed as mutual authentication is not supported. |
 | `Server.pem` | Client certificate chain, valid for 365 days, currently not needed as mutual authentication is not supported. |
 
 If the certificates have expired or you by any other reason need to regenerate keys or certificates you can use

kuksa_certificates/jwt/README.md

@@ -0,0 +1,21 @@
+# KUKSA Server JWT Tokens
+
+This directory contains example tokens for communication with the KUKSA Server.
+Corresponding tokens for Databroker can be found [here](../../jwt).
+
+The script [createToken.py](createToken.py) can be used to generate new tokens if needed.
+
+For historical reasons KUKSA Server tokens use a different pattern for token names.
+If you generate new tokens for KUKSA Server you must first run the script and then rename the generated token.
+
+## Example: Re-generate token with new expiry date
+
+The current example tokens expire at 2025-12-31. To generate new ones you must first add a new expiry date in
+the corresponding `*.json files. Then do:
+
+```
+./createToken.py single-read.json
+mv single-read.token single-read.json.token
+```
+
+*Note: The renaming is only needed for KUKSA Server tokens, not for KUKSA Databroker tokens!*