From e628c464127adb3704f0700fc8ccf5826ec30568 Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Thu, 21 Mar 2024 14:09:47 +0100 Subject: [PATCH] Fix workflows and links Previously no docker containers were published --- .github/actions/copy-from-oci/action.yml | 60 ------ .../post-container-location/action.yml | 24 --- .../workflows/kuksa_databroker-cli_build.yml | 11 +- .github/workflows/kuksa_databroker_build.yml | 29 +-- .github/workflows/pre-commit.yml | 6 +- .pre-commit-config.yaml | 13 ++ CONTRIBUTING.md | 32 +++ LICENSE | 201 ++++++++++++++++++ certificates/README.md | 39 ++++ data/vss-core/README.md | 88 +------- doc/protocol/README.md | 19 +- doc/system-architecture.md | 38 ++-- doc/terminology.md | 28 +-- doc/tls.md | 79 +++---- jwt/README.md | 2 +- 15 files changed, 376 insertions(+), 293 deletions(-) delete mode 100644 .github/actions/copy-from-oci/action.yml delete mode 100644 .github/actions/post-container-location/action.yml create mode 100644 .pre-commit-config.yaml create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 certificates/README.md diff --git a/.github/actions/copy-from-oci/action.yml b/.github/actions/copy-from-oci/action.yml deleted file mode 100644 index a82957b1..00000000 --- a/.github/actions/copy-from-oci/action.yml +++ /dev/null @@ -1,60 +0,0 @@ - -name: Extract from OCI image -description: Can copy files out of an OCI image - -inputs: - platform: - required: true - type: choice - description: Choose platform, e.g. linux/arm64 - options: - - linux/arm64 - - linux/amd64 - - linux/riscv64 - image: - required: true - type: string - description: The OCI image - src: - required: true - type: string - description: Path inside container - id: - required: true - type: string - description: | - This will be the name of the temporary container, making sure we do not leave any stale containers around - (we try deleting and before and after running this, so we can recover should a workflow for a given id fail before cleaning up) - Will be used for artifact name (if export=true) and to identify - This will also be created as directory in cwd. - !No special characters allowed "/" ! - export: - required: false - default: false - description: Archive dest and export as Action artifact - transform: - required: false - description: Optionally applying chosen --transform to tar when export is set to true - - -runs: - using: "composite" - steps: - - shell: bash - run: | - mkdir -p ${{ inputs.id }} - docker rm ${{ inputs.id }} || true - docker create --name ${{ inputs.id }} --platform ${{ inputs.platform }} ${{ inputs.image }} - docker cp ${{ inputs.id }}:${{ inputs.src }} ${{ inputs.id }} - docker rm ${{ inputs.id }} - - - - if: inputs.export == 'true' - shell: bash - run: tar -czf ${{ inputs.id }}.tar.gz -C ${{ inputs.id }} --transform "${{ inputs.transform }}" . - - - if: inputs.export == 'true' - uses: actions/upload-artifact@v4 - with: - name: ${{ inputs.id }} - path: ${{ inputs.id }}.tar.gz diff --git a/.github/actions/post-container-location/action.yml b/.github/actions/post-container-location/action.yml deleted file mode 100644 index 757b7c2b..00000000 --- a/.github/actions/post-container-location/action.yml +++ /dev/null @@ -1,24 +0,0 @@ - -name: Post container location -description: Post snippet to pull and run test container - - - - -inputs: - image: - required: true - type: string - description: The OCI image - -runs: - using: "composite" - steps: - - shell: bash - run: | - echo "## :hatching_chick: Moin!" >> $GITHUB_STEP_SUMMARY - echo "Something new is in the world" >> $GITHUB_STEP_SUMMARY - echo -e "\nImages for testing temporarily available at \`${{ inputs.image }}\`" >> $GITHUB_STEP_SUMMARY - echo -e "\n\`\`\`\ndocker pull ${{ inputs.image }}\n\`\`\`" >> $GITHUB_STEP_SUMMARY - echo -e "\n\`\`\`\ndocker run --rm -it --net=host ${{ inputs.image }}\n\`\`\`" >> $GITHUB_STEP_SUMMARY - diff --git a/.github/workflows/kuksa_databroker-cli_build.yml b/.github/workflows/kuksa_databroker-cli_build.yml index 268dcf49..76531199 100644 --- a/.github/workflows/kuksa_databroker-cli_build.yml +++ b/.github/workflows/kuksa_databroker-cli_build.yml @@ -15,7 +15,7 @@ name: Build kuksa-databroker-cli on: push: - branches: [ master ] + branches: [ main ] pull_request: paths: - ".github/workflows/kuksa_databroker-cli_build.yml" @@ -30,6 +30,10 @@ concurrency: group: ${{ github.ref }}-${{ github.workflow }} cancel-in-progress: true +# Needed as default_workflow_permissions is "read" +permissions: + packages: write + jobs: lint: name: Lint @@ -52,7 +56,7 @@ jobs: - name: cargo clippy working-directory: ${{github.workspace}} run: cargo clippy --all-targets -- -W warnings -D warnings - + check_ghcr_push: name: Check access rights uses: eclipse-kuksa/kuksa-actions/.github/workflows/check_ghcr_push.yml@2 @@ -152,9 +156,8 @@ jobs: # Same problem as described in https://github.com/orgs/community/discussions/45969 provenance: false - - name: Posting message - uses: ./.github/actions/post-container-location + uses: eclipse-kuksa/kuksa-actions/post-container-location@2 with: image: ttl.sh/eclipse-kuksa/kuksa-databroker-cli-${{github.sha}} diff --git a/.github/workflows/kuksa_databroker_build.yml b/.github/workflows/kuksa_databroker_build.yml index 32fa530f..7eca6b5f 100644 --- a/.github/workflows/kuksa_databroker_build.yml +++ b/.github/workflows/kuksa_databroker_build.yml @@ -15,7 +15,7 @@ name: Build kuksa-databroker on: push: - branches: [ master ] + branches: [ main] pull_request: workflow_call: workflow_dispatch: @@ -24,6 +24,10 @@ concurrency: group: ${{ github.ref }}-${{ github.workflow }} cancel-in-progress: true +# Needed as default_workflow_permissions is "read" +permissions: + packages: write + jobs: lint: name: Lint @@ -77,6 +81,8 @@ jobs: - name: Generate code coverage run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info - name: Upload coverage to Codecov + # To use v4 a token must be specifed by "token: ${{ secrets.CODECOV_TOKEN }}"" + # Uploaded result available at https://app.codecov.io/gh/eclipse-kuksa/kuksa-databroker uses: codecov/codecov-action@v3 with: files: lcov.info @@ -230,29 +236,10 @@ jobs: provenance: false - name: Posting message - uses: ./.github/actions/post-container-location + uses: eclipse-kuksa/kuksa-actions/post-container-location@2 with: image: ttl.sh/eclipse-kuksa/kuksa-databroker-${{github.sha}} - # - name: "Archiving AMD64 artifacts" - # uses: actions/upload-artifact@v4 - # with: - # name: databroker-amd64 - # path: ${{github.workspace}}/dist/amd64 - - # - name: "Archiving ARM64 artifacts" - # uses: actions/upload-artifact@v4 - # with: - # name: databroker-arm64 - # path: ${{github.workspace}}/dist/arm64 - - # - name: "Archiving RISCV64 artifacts" - # uses: actions/upload-artifact@v4 - # with: - # name: databroker-riscv64 - # path: ${{github.workspace}}/dist/riscv64 - - integration-test: name: Run integration test runs-on: ubuntu-latest diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index ec0a66f1..f8ba7ca8 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -16,7 +16,9 @@ jobs: with: # required to grab the history of the PR fetch-depth: 0 - - uses: actions/setup-python@v3 - - uses: pre-commit/action@v3.0.0 + - uses: actions/setup-python@v5 + with: + python-version: '3.10' + - uses: pre-commit/action@v3.0.1 with: extra_args: --color=always --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..3f9f18d7 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,13 @@ +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v3.2.0 + hooks: + - id: trailing-whitespace + exclude_types: ["dbc"] + - id: end-of-file-fixer + exclude_types: ["dbc", "json"] + exclude: \.token$ + - id: check-yaml + - id: check-added-large-files diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9b181ff6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,32 @@ +# Contributing to Eclipse Kuksa + +Thanks for your interest in this project. + +## Eclipse Contributor Agreement + +Before your code contribution can be accepted by the project team contributors must +electronically sign the Eclipse Contributor Agreement (ECA). + +* http://www.eclipse.org/legal/ECA.php + +Commits that are provided by non-committers must have a Signed-off-by field in +the footer indicating that the author is aware of the terms by which the +contribution has been provided to the project. The non-committer must +additionally have an Eclipse Foundation account and must have a signed Eclipse +Contributor Agreement (ECA) on file. + +For more information, please see the Eclipse Committer Handbook: +https://www.eclipse.org/projects/handbook/#resources-commit + +## Contact + +Contact the project developers via the project's "dev" list. + +* https://dev.eclipse.org/mailman/listinfo/kuksa-dev + +## Pre-commit set up +This repository is set up to use [pre-commit](https://pre-commit.com/) hooks. +Use `pip install pre-commit` to install pre-commit. +After you clone the project, run `pre-commit install` to install pre-commit into your git hooks. +Pre-commit will now run on every commit. +Every time you clone a project using pre-commit running pre-commit install should always be the first thing you do. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..261eeb9e --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/certificates/README.md b/certificates/README.md new file mode 100644 index 00000000..c679b0bf --- /dev/null +++ b/certificates/README.md @@ -0,0 +1,39 @@ +# Example Certificates and Tokens for KUKSA + +This directory contains example keys, tokens and certificates that can be used for testing clients and servers in this repository. +Many of the clients and servers in this repository use keys, tokens and certificates from this directory by default. + +*Note that the primary storage location for keys, tokens and certificates usable for KUKSA Databroker* +*is [kuksa-common](https://github.com/eclipse-kuksa/kuksa-common/tree/main).* +*Files that also exist here should be considered as copies.* + +## Keys and Certificates for TLS connections + +This directory contain a set of example certificates, used by the KUKSA-project during development and testing. +They may or may not be useful for your test environment. +If needed you can customize the [genCerts.sh](https://github.com/eclipse-kuksa/kuksa-common/blob/main/tls/genCerts.sh) script and generate keys and certificates that fits your environment. + +See the [KUKSA TLS documentation](../doc/tls.md) for general information on the KUKSA TLS concept. + +This directory contains the following files with cryptographical information. + + Component | Description | +| -------------- | ----------- | +| `CA.key` | Root key, not needed by KUKSA applications +| `CA.pem` | Root certificate, valid for 3650 days ( 10 years). | +| `Server.key` | Server key, needed by KUKSA Databroker for TLS. | +| `Server.pem` | Server certificate chain, valid for 365 days, needed by KUKSA Databroker for TLS. | +| `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 +the [genCerts.sh](https://github.com/eclipse-kuksa/kuksa-common/blob/main/tls/genCerts.sh) as described in kuksa-common [documentation](https://github.com/eclipse-kuksa/kuksa-common/blob/main/tls/README.md). + +## Java Web Tokens (JWT) + +KUKSA Databroker use Java Web Tokens (JWT) to validate that a client is authorized to read or write a specific datapoints. +Example root key exist in the [jwt](jwt) folder. +It contains a [jwt.key](jwt/jwt.key] file used to sign tokens. + +Two helper scripts exist for generating keys and tokens, please see +[kuksa-common documentation](https://github.com/eclipse-kuksa/kuksa-common/tree/main/jwt) diff --git a/data/vss-core/README.md b/data/vss-core/README.md index 6a3b9f46..550687c8 100644 --- a/data/vss-core/README.md +++ b/data/vss-core/README.md @@ -5,7 +5,9 @@ KUKSA.val is adapted to use Vehicle Signals Specification as defined by COVESA. The ambition is to always support the latest released version available at the [COVESA VSS release page](https://github.com/COVESA/vehicle_signal_specification/releases). -In addition older versions may be supported. This folder contains copies of all versions supported. +In addition older versions may be supported. This folder contains copies of all versions supported by Databroker. + +*The files in this folder also exists in [kuksa-common](https://github.com/eclipse-kuksa/kuksa-common/blob/main/vss/README.md)!* ## Supported VSS versions @@ -52,90 +54,6 @@ use the full name. When official release is created replace the copied *.json-fi ## Tests after update -### Kuksa-val-server unit tests -* Run kuksa-val-server unit tests according to [documentation](../../kuksa-val-server/test/unit-test/readme.md) - -### Kuksa-val-server smoke test -* Build and start kuksa-val-server with new VSS release as described in the [README](https://github.com/eclipse-kuksa/kuksa-databrokerblob/master/kuksa-val-server/README.md) -* If needed [generate new certificates](https://github.com/eclipse-kuksa/kuksa-databrokertree/master/certificates) -* [Start Kuksa Client](https://github.com/eclipse-kuksa/kuksa-python-sdk) and perform some basic tests that VSS changes are present - -Examples: - -Start and authorize with generated token: - -``` -$ python -m kuksa_client -Welcome to Kuksa Client version 0.2.1 - - `-:+o/shhhs+:` - ./oo/+o/``.-:ohhs- - `/o+- /o/ `.. :yho` - +o/ /o/ oho ohy` - :o+ /o/`+hh. sh+ - +o: /oo+o+` /hy - +o: /o+/oo- +hs - .oo` oho `oo- .hh: - :oo. oho -+: -hh/ - .+o+-`oho `:shy- - ./o/ohy//+oyhho- - `-/+oo+/:. - -Default tokens directory: /home/erik/.local/lib/python3.9/site-packages/certificates/jwt - -connect to wss://127.0.0.1:8090 -Websocket connected!! - -Test Client> authorize /home/user/.local/lib/python3.9/site-packages/certificates/jwt/super-admin.json.token - -``` - -Check that changes to the new version has taken effect, e.g. that new signals exist or that changed or added attributes are present. - -``` -Test Client> getMetaData Vehicle.Powertrain.Transmission.DriveType - -``` - -Do some set/get on new signals to verify that it works as expected. - -``` -Test Client> setValue Vehicle.CurrentLocation.Longitude 16.346734 - -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. - - -### 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. - -``` -gpsfake -t -P 2949 simplelog_example.nmea -``` - -If everything works as expected successful set requests with values similar to below shall be seen: - -``` -VERBOSE: SubscriptionHandler::publishForVSSPath: set value 48.811483333 for path Vehicle.CurrentLocation.Latitude -... -VERBOSE: SubscriptionHandler::publishForVSSPath: set value 8.927633333 for path Vehicle.CurrentLocation.Longitude -... -VERBOSE: SubscriptionHandler::publishForVSSPath: set value 12.244000434875488 for path Vehicle.Speed -``` - -The [Kuksa Python SDK](https://github.com/eclipse-kuksa/kuksa-python-sdk) can be used to verify that data actually is correctly interpreted. - -``` -Test Client> getValue Vehicle.CurrentLocation.Latitude -{"action":"get","data":{"dp":{"ts":"2022-08-19T14:04:43.339202324Z","value":"48.780133333"},"path":"Vehicle.CurrentLocation.Latitude"},"requestId":"025e5b10-d389-4a96-ba43-46f6a8c06b9e","ts":"2022-08-19T14:04:43.1660914283Z"} -``` - ### Kuksa_databroker smoke test diff --git a/doc/protocol/README.md b/doc/protocol/README.md index b83779af..f9185af5 100644 --- a/doc/protocol/README.md +++ b/doc/protocol/README.md @@ -1,9 +1,9 @@ ## Supported protocols -This file contains an overview what the KUKSA.val Server and databroker each supports. It focuses on gRPC and VISS support and also what feeders are supported. +This file contains an overview what the KUKSA Server and databroker each supports. It focuses on gRPC and VISS support and also what feeders are supported. -| Protocol | KUKSA.val server | KUKSA.val databroker | +| Protocol | KUKSA server | KUKSA databroker | |---------------------------|:----------------:|:--------------------:| | VISS V1 | - | - | | VISS V2 | x/- | x/- | @@ -16,7 +16,7 @@ x = supported; x/- = partially supported; - = not supported ### VISSv2 support (websocket transport) -| Feature | KUKSA.val server | KUKSA.val databroker | +| Feature | KUKSA server | KUKSA databroker | |-------------------------------|:-----------------:|:--------------------:| | Read | | | | - Authorized Read | x1,2 | x | @@ -44,14 +44,11 @@ x2 Relies on the non-standard `attribute` values which doesn't work w For a more detailed view of the supported JSON-schemas [click here](https://github.com/eclipse-kuksa/kuksa-databrokerblob/master/kuksa-val-server/include/VSSRequestJsonSchema.hpp) -### VISSv2 in KUKSA.val server -KUKSA.val server supports the semantics of [VISS v1](https://www.w3.org/TR/vehicle-information-service/) using the new syntax of [VISS v2](https://www.w3.org/TR/viss2-core/). It implements a modified version of VISSv2 which introduces the concept of `attributes` which makes it incompatible with standards compliant VISSv2 clients. -KUKSA.val server doesn't support the VISS V2 security model and there is currently no plan to support it. KUKSA.val server does support authenticated access to VSS resources. For details check [here.](../KUKSA.val_server/jwt.md). -### VISSv2 in KUKSA.val databroker -KUKSA.val databroker aims to provide a standards compliant implementation of VISSv2 (using the websocket transport). +### VISSv2 in KUKSA Databroker +KUKSA databroker aims to provide a standards compliant implementation of VISSv2 (using the websocket transport). -It supports authorization using the access token format specified in [authorization.md](../KUKSA.val_data_broker/authorization.md). +It supports authorization using the access token format specified in [authorization.md](../authorization.md). VISSv2 support in databroker is included by building it with the `viss` feature flag. ```shell @@ -72,8 +69,8 @@ $ kuksa-client ws://127.0.0.1:8090 TLS is currently not supported. -### KUKSA.val databroker gRPC API -The VISS Standard is not applicable for gRPC protocols. Here is an overview what the gRPC API in KUKSA.val databroker is capable of: +### KUKSA databroker gRPC API +The VISS Standard is not applicable for gRPC protocols. Here is an overview what the gRPC API in KUKSA databroker is capable of: * Read: Reading VSS datapoints * Reading current or target value for actuators diff --git a/doc/system-architecture.md b/doc/system-architecture.md index dc243790..15cd2bc6 100644 --- a/doc/system-architecture.md +++ b/doc/system-architecture.md @@ -1,20 +1,20 @@ -# KUKSA.val System Components and Deployment +# KUKSA System Components and Deployment -This document shows basic KUKSA.val deployments and gives examples for provider components. +This document shows basic KUKSA deployments and gives examples for provider components. Check the [terminology document](./terminology.md) to get a common understanding for the terms used in this document. -KUKSA.val aims to provide a consistent view of all signals inside a vehicle. The data model follows the [COVESA Vehicle Signal Specification](https://github.com/COVESA/vehicle_signal_specification) while the data is accessed using either a variant of the [W3C VISS protocol](https://github.com/w3c/automotive) or a [GRPC](https://grpc.io)-based protocol. The KUKSA.val contains two slightly different VSS servers - the [KUKSA.val databroker](../) and the [KUKSA.val server](../kuksa-val-server/). For the differences of the two go [here](./server-vs-broker.md). +KUKSA aims to provide a consistent view of all signals inside a vehicle. The data model follows the [COVESA Vehicle Signal Specification](https://github.com/COVESA/vehicle_signal_specification) while the data is accessed using either a variant of the [W3C VISS protocol](https://github.com/w3c/automotive) or a [GRPC](https://grpc.io)-based protocol. The KUKSA project develops a Rust VSS Server - the [KUKSA databroker](../). -The following picture shows the basic KUKSA.val system architecture: +The following picture shows the basic KUKSA system architecture: ![Basic architecture](./pictures/sysarch_basic.svg) -A KUKSA.val VSS server runs on a vehicle computer with a given VSS model. Applications can interact with the VSS model by setting, getting or subscribing to VSS datapoints. +A KUKSA VSS server runs on a vehicle computer with a given VSS model. Applications can interact with the VSS model by setting, getting or subscribing to VSS datapoints. -The VSS server exposes a network based API to let consumers interact with VSS datapoints. This is either W3C VISS (currently only available in KUKSA.val server) or the KUKSA.val GRPC API (currently supported by KUKSA.val databroker). +The VSS server exposes a network based API to let consumers interact with VSS datapoints. This is either W3C VISS (currently only available in KUKSA server) or the KUKSA GRPC API (currently supported by KUKSA databroker). -Connections to the VSS server can be protected via TLS. Authorization to access specific VSS data is managed via JWT tokens (in KUKSA.val server, KUKSA.val databroker implementation is ongoing). +Connections to the VSS server can be protected via TLS. Authorization to access specific VSS data is managed via JWT tokens (in KUKSA server, KUKSA databroker implementation is ongoing). To sync the VSS model to the actual state of the vehicle, providers are used. A data-provider might get its information directly from a sensor, from vehicle busses available to the provider, or from lower parts of the software stack. Historically, data-providers are often called "feeders". To sync the desired state in the VSS server to the Vehicle, actuation-providers are used. Similar to the data-provider, an actuation provider also needs to access lower-level Vehicle systems. @@ -24,45 +24,45 @@ Providers have the same protocol options of accessing the VSS server as consumer In the following we will provide some more specific example of consumer and provider components. ## Providers -Components providing data for leaves in the VSS tree are called *data-providers*. Technically they are just normal KUKSA.val clients. Sometimes you will see data-providers to be referred to as "feeders". +Components providing data for leaves in the VSS tree are called *data-providers*. Technically they are just normal KUKSA clients. Sometimes you will see data-providers to be referred to as "feeders". A data-provider will gather some data from a vehicle using whatever standard or proprietary protocol is needed to access the data. It will then convert the gathered data to the representation defined in a VSS model and provide those standard signals to the VSS server using the VISS or GRPC protocol. If a provider also supports affecting vehicle systems, based on a desired state being set via the VSS server, it is an *actuation-provider*. Depending on the system design, a provider can be designed to fulfil both the roles as data-provider and actuation-provider. -The following picture shows different kinds of possible KUKSA.val providers +The following picture shows different kinds of possible KUKSA providers ![Provider options](./pictures/sysarch_providers.svg) -We assume running a KUKSA.val VSS server on a vehicle computer. Some signals might originate in an embedded ECU only connected via CAN (e.g. ECU 1). If the Vehicle Computer running the VSS Server has access to the bus, it can run a provider component to map VSS Datapoints. +We assume running a KUKSA VSS server on a vehicle computer. Some signals might originate in an embedded ECU only connected via CAN (e.g. ECU 1). If the Vehicle Computer running the VSS Server has access to the bus, it can run a provider component to map VSS Datapoints. The [DBC Feeder](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) is an example of a CAN data-provider. It allows mapping of data from a CAN bus based on a DBC description and some mapping rules. -Other ECUs with Ethernet connectivity might publish data as SOME/IP (ECU 2 in the example) or DDS (ECU 3 in the example) services. The KUKSA.val project provides an [example SOME/IP provider](https://github.com/eclipse/kuksa.val.feeders/tree/main/someip2val) based on [vsomeip](https://github.com/COVESA/vsomeip) emulating a SOME/IP controllable wiper. +Other ECUs with Ethernet connectivity might publish data as SOME/IP (ECU 2 in the example) or DDS (ECU 3 in the example) services. The KUKSA project provides an [example SOME/IP provider](https://github.com/eclipse/kuksa.val.feeders/tree/main/someip2val) based on [vsomeip](https://github.com/COVESA/vsomeip) emulating a SOME/IP controllable wiper. The Vehicle Computer running the VSS server might run other (automotive) middlewares that provides raw data and signals. In this example we assume the Vehicle Computer runs an AUTOSAR Adaptive subsystem. In that case a provider using the APIs of the underlying system can be created, without the need to parse a specific serialization first. In case of AUTOSAR Adaptive, signals might be accessed using the `ara::com` API. Finally, there may be other processor based platforms in a vehicle such as another vehicle computer (VCU in the example), a domain, or zone controller or an infotainment system. These systems can run any kind of provider themselves and connect to a VSS server running on a different compute unit directly through the VISS or GRPC directly. -A provider can be implemented directly against the KUKSA.val GRPC or VISS specification using any programming language. For Python-based providers you can make use of the [KUKSA Python SDK](https://github.com/eclipse-kuksa/kuksa-python-sdk). +A provider can be implemented directly against the KUKSA GRPC or VISS specification using any programming language. For Python-based providers you can make use of the [KUKSA Python SDK](https://github.com/eclipse-kuksa/kuksa-python-sdk). ## Consumers -Consumers are usually different kind of applications that are accessing VSS signals through KUKSA.val. The following figure shows common consumer patterns: +Consumers are usually different kind of applications that are accessing VSS signals through KUKSA. The following figure shows common consumer patterns: ![Application patterns](./pictures/sysarch_consumers.svg) A standard consumer ("Application)" will interact with VSS datapoints from the VSS server to realize a vehicle functionality. A simple example is gathering some signals and visualizing them. -Another common use case is providing telemetry to the cloud. With cellular networks, being hidden behind NATs or using dynamic IP addresses, the VISS/GRPC pattern of contacting a VSS server is not a suitable. The common pattern is, that the vehicle pushes relevant data, using suitable IoT protocols and potentially dealing with buffering and connection loss. This is the "Cloud Adapter" pattern. An example is the [KUKSA.val S3 uploader](../kuksa_apps/s3/). +Another common use case is providing telemetry to the cloud. With cellular networks, being hidden behind NATs or using dynamic IP addresses, the VISS/GRPC pattern of contacting a VSS server is not a suitable. The common pattern is, that the vehicle pushes relevant data, using suitable IoT protocols and potentially dealing with buffering and connection loss. This is the "Cloud Adapter" pattern. As a VSS data catalogue can contain signals of different abstraction levels, often higher level signals depend on lower level ones. Thus an application might use data from some signals to calculate the value of of others ("Signal Refinement"). An example is, taking current battery voltage and other low level signals from the battery system to calculate a state-of-charge and pushing it back. Another service might use state of-charge, system and ambient temperature to calculate remaining range. Such a client combines the roles of consumer and data-provider. -A consumer can be implemented directly against the KUKSA.val GRPC or VISS specification using any programming language. For Python-based consumers you can make use of the [KUKSA Python SDK](https://github.com/eclipse-kuksa/kuksa-python-sdk). +A consumer can be implemented directly against the KUKSA GRPC or VISS specification using any programming language. For Python-based consumers you can make use of the [KUKSA Python SDK](https://github.com/eclipse-kuksa/kuksa-python-sdk). -## (Distributed) KUKSA.val deployment +## (Distributed) KUKSA deployment -The idea behind VSS and KUKSA.val is, to provide a single entry point to all vehicle data. As in a real vehicle data is distributed and not all domains need access to all data. Therefore, you might opt to run several VSS servers, each providing a subset of all vehicle data. This can also increase resiliency of the system and allows to separate safety domains. +The idea behind VSS and KUKSA is, to provide a single entry point to all vehicle data. As in a real vehicle data is distributed and not all domains need access to all data. Therefore, you might opt to run several VSS servers, each providing a subset of all vehicle data. This can also increase resiliency of the system and allows to separate safety domains. What is considered a suitable deployment is very much dependent on the vehicle architecture and the scope of data managed in VSS. @@ -70,9 +70,9 @@ The following figure shows several possible patterns: ![Deployment patterns](./pictures/sysarch_deployment.svg) -The simplest expected deployment assumes that the primary vehicle computer contains the fully populated VSS model for a vehicle. This is the only possible deployment in vehicles, that only have one computer capable to run KUKSA.val and protocols such as GRPC or VISS. +The simplest expected deployment assumes that the primary vehicle computer contains the fully populated VSS model for a vehicle. This is the only possible deployment in vehicles, that only have one computer capable to run KUKSA and protocols such as GRPC or VISS. -In a redundancy scenario there may be a backup vehicle computer with a KUKSA.val instance that is kept in sync, so that in case of a failover, the last known data is immediately available for all VSS datapoints. We assume an optimized VSS Sync component to be used that might deal with one-way or two-way syncs. Currently KUKSA.val does not include a sync mechanism. +In a redundancy scenario there may be a backup vehicle computer with a KUKSA instance that is kept in sync, so that in case of a failover, the last known data is immediately available for all VSS datapoints. We assume an optimized VSS Sync component to be used that might deal with one-way or two-way syncs. Currently KUKSA does not include a sync mechanism. A vehicle can have additional domain controllers such as the powertrain controller. The Powertrain controller might use VSS to manage private internal datapoints not relevant to other domains. At the same time it is accessing VSS signals relevant to powertrain functionality provided by the VSS server on the central vehicle computer as well as providing higher level powertrain signals to the vehicle computer. diff --git a/doc/terminology.md b/doc/terminology.md index eb763312..501cbc6d 100644 --- a/doc/terminology.md +++ b/doc/terminology.md @@ -24,14 +24,14 @@ This pages gives an overview about the terms we use, when talking about KUKSA co ![In-vehicle KUKSA.val components](./pictures/terminology.svg) -KUKSA.val helps you provide and interact with VSS data in-vehicle. The figure above depicts the required components. We will describe each of their roles in the following sections. +KUKSA.val helps you provide and interact with VSS data in-vehicle. The figure above depicts the required components. We will describe each of their roles in the following sections. ## VSS Server This is a server that provides the KUKSA.val APIs to interact with VSS signals. - + Usually, for KUKSA.val this is the KUKSA.val databroker. The server keeps the current state of all known VSS signals and enables clients to get information regarding those signals or changing their state. It is also responsible of for checking whether a client has sufficient authorization to access or modify certain signals. -Architecture-wise, most things in this document should apply to other VSS server implementations such as for example the older KUKSA.val val-server as well. (see [here](./server-vs-broker.md) for technical differences between these two VSS servers). +Architecture-wise, most things in this document should apply to other VSS server implementations such as for example the older KUKSA.val val-server as well. (See [here](https://github.com/eclipse/kuksa.val/blob/master/doc/server-vs-broker.md) for technical differences between these two VSS servers). Databroker's API is GRPC-based, which means it can also be accessed over the network by other programs or systems. @@ -41,7 +41,7 @@ Any application that connects to the server and uses the KUKSA.VAL APIs is a cli From an architecture point of view, there are different types of clients, depending on their role in the system. -The following picture shows a taxonomy of different client types, which will be discussed in the following. +The following picture shows a taxonomy of different client types, which will be discussed in the following. ![KUKSA client taxonomy](./pictures/client-taxonomy.svg) @@ -50,26 +50,26 @@ For specific examples of components fulfilling certain client roles also check [ ## Clients: VSS Consumers VSS Consumers can also be seen as northbound clients of the VSS server. A VSS consumer intends to interact with the vehicle represented by the VSS model served by the server: A consumer typically wants to read sensors representing vehicle state available in VSS or affecting changes in the vehicle hardware by interacting with actuators available in VSS. -Examples for VSS consumers might be "apps" or functions running on vehicle computers, the infotainment system, or maybe even a user's personal device. +Examples for VSS consumers might be "apps" or functions running on vehicle computers, the infotainment system, or maybe even a user's personal device. ## Clients: VSS Providers VSS Providers can also be seen as southbound clients of the VSS server. A VSS provider intends to sync the state of the physical vehicle with the VSS model of the server. -Therefore, a VSS provider will always connect two interfaces: Northbound it uses the KUKSA.val API to interact with a VSS server, southbound it will interact with some other system, typically an in-vehicle bus or API. +Therefore, a VSS provider will always connect two interfaces: Northbound it uses the KUKSA.val API to interact with a VSS server, southbound it will interact with some other system, typically an in-vehicle bus or API. -There are two classes of VSS providers: data-providers and actuation-providers. In practice, a single component might combine both roles. +There are two classes of VSS providers: data-providers and actuation-providers. In practice, a single component might combine both roles. ### data-provider A data-provider intends to make sure that the actual state of a vehicle is currently represented in the VSS model of the server. A data-provider will update the current value of a VSS signal (sensor, actuator or attribute) in the server. A data-provider for the VSS sensor `Vehicle.Speed` will update that VSS signal in the server based on the actual speed of the vehicle. A data-provider for the VSS actuator `Vehicle.Body.Trunk.Rear.IsOpen` would update that VSS signal in the server based on the _currently_ observed state of the vehicle's trunk. Historically you also may still find the term "feeder", when referring to a data-provider. ### actuation-provider -An actuation-provider is trying to ensure that the target value of a VSS actuator is reflected by the actual state of a vehicle. +An actuation-provider is trying to ensure that the target value of a VSS actuator is reflected by the actual state of a vehicle. -To this end, an actuation-provider can subscribe to the target value of a VSS actuator in the server. +To this end, an actuation-provider can subscribe to the target value of a VSS actuator in the server. If a VSS consumer requests the _desired_ state of the VSS actuator `Vehicle.Body.Trunk.Rear.IsOpen` to be `true`, the actuation-provider for `Vehicle.Body.Trunk.Rear.IsOpen` would try to interact with a vehicle's system trying to unlock and open the trunk. -While from the server's point of view, an actuation provider is just a client, actuation-providers can not be passive towards other in-vehicle systems. Therefore, considering safety in an actuation-provider or underlying systems is very important. +While from the server's point of view, an actuation provider is just a client, actuation-providers can not be passive towards other in-vehicle systems. Therefore, considering safety in an actuation-provider or underlying systems is very important. # Vehicle Signal Specification (VSS) KUKSA handles datapoints that are defined using the COVESA Vehicle Signal Specification (VSS). @@ -78,7 +78,7 @@ While from the server's point of view, an actuation provider is just a client, a * A syntax for defining vehicle signals in a structured manner. * A catalog of standard signals (VSs standard catalogue) related to vehicles. -It can be used as standard in automotive applications to communicate information around the vehicle, which is semantically well defined. +It can be used as standard in automotive applications to communicate information around the vehicle, which is semantically well defined. See the [the official VSS documentation](https://covesa.github.io/vehicle_signal_specification/) for all details. Here we will summarizes the terms and concepts most relevant for KUKSA. @@ -87,13 +87,13 @@ A signal in VSS is an entity identified by a dot-separated string in VSS, i.e. ` A signal can be of different types. VSS defines the following signal types: -### Sensor +### Sensor Signals of this type represent sensors in the vehicle. The value of a sensor typically changes over time. Reading a sensor will return the current actual value of the related property, e.g. the current speed of a vehicle. Example: `Vehicle.Speed`. [[Source]](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/) ### Actuator Actuators are signals that are used to control the desired value of a property. _Every Actuator in VSS is also a Sensor_. Some properties in a vehicle cannot change instantly. A typical example is position of a seat. Reading a value of an actuator shall return the current actual value (i.e. the sensor trait of that actuator signal), e.g. the current position of the seat, rather than the wanted/desired position. Example: `set Vehicle.Cabin.Seat.Row1.Pos1.Position`. [[Source]](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/) -### Attribute +### Attribute Attributes are signals that have a default value, specified by its default member in VSS. Like sensors, attribute values can also change, similar to sensor values. The latter can be useful for attribute values that are likely to change during the lifetime of the vehicle. However, attribute values should typically not change more than once per ignition cycle. Example: `Vehicle.VehicleIdentification.VIN`. [[Source]](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/attributes/) ## Value @@ -107,4 +107,4 @@ VSS has the concept of layering different signal trees on top of each other. Thi Currently, KUKSA.val supports loading a stack of VSS models enabling applying overlays during startup. ## Datapoint -A datapoint is the value of a signal at a specific time (i.e. value + timestamp). This can generally be retrieved through the various APIs offered by databroker. \ No newline at end of file +A datapoint is the value of a signal at a specific time (i.e. value + timestamp). This can generally be retrieved through the various APIs offered by databroker. diff --git a/doc/tls.md b/doc/tls.md index c07c3534..2c834a30 100644 --- a/doc/tls.md +++ b/doc/tls.md @@ -1,21 +1,21 @@ -# KUKSA.val TLS concept +# KUKSA TLS concept -This page describes the TLS support in KUKSA.val +This page describes the TLS support in KUKSA ## Security concept -KUKSA.val supports TLS for connection between KUKSA.val Databroker/Server and clients. +KUKSA supports TLS for connection between KUKSA Databroker and clients. General design concept in short: -* KUKSA.val Server and KUKSA.val Databroker supports either connections secured with TLS or insecure connections. -* You can use configuration settings to control whether Server or databroker shall require secure connections. +* KUKSA Databroker supports either connections secured with TLS or insecure connections. +* You can use configuration settings to control whether 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 +* Mutual authentication is not supported, i.e. KUKSA Databroker does not authenticate clients * A set of example certificates and keys exist in the [certificates](../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 +* KUKSA 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 @@ -25,40 +25,40 @@ For more information see the [README.md](../certificates/README.md). ## Examples using example certificates -This section intends to give guidelines on how you can verify TLS functionality with KUKSA.val. +This section intends to give guidelines on how you can verify TLS functionality with KUKSA. It is based on using the example certificates. -## KUKSA.val Databroker +## KUKSA Databroker -KUKSA.val Databroker supports TLS, but not mutual authentication. -As of today, if TLS is not configured, KUKSA.val Databroker will accept insecure connections. +KUKSA Databroker supports TLS, but not mutual authentication. +As of today, if TLS is not configured, KUKSA Databroker will accept insecure connections. ``` -~/kuksa.val/kuksa_databroker$ cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json +~/kuksa-databroker$ cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json ``` The default behavior may change in the future. By that reason, it is recommended to use the `--insecure` argument if you want to use insecure connections. ``` -~/kuksa.val/kuksa_databroker$ cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json --insecure +~/kuksa-databroker$ cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json --insecure ``` To use a secure connection specify both `--tls-cert`and `--tls-private-key` ``` -~/kuksa.val/kuksa_databroker$ cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json --tls-cert ../certificates/Server.pem --tls-private-key ../certificates/Server.key +~/kuksa-databroker$ cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json --tls-cert ../certificates/Server.pem --tls-private-key ../certificates/Server.key ``` -Default certificates and keys are not included in the default KUKSA.val Databroker container, -so if running KUKSA.val Databroker from a default container you need to mount the directory containing the keys and certificates. +Default certificates and keys are not included in the default KUKSA Databroker container, +so if running KUKSA Databroker from a default container you need to mount the directory containing the keys and certificates. ``` -~/kuksa.val/kuksa_databroker$ docker run --rm -it -p 55555:55555/tcp -v /home/user/kuksa.val/certificates:/certs databroker --tls-cert /certs/Server.pem --tls-private-key /certs/Server.key +~/kuksa-databroker$ docker run --rm -it -p 55555:55555/tcp -v /home/user/kuksa.val/certificates:/certs databroker --tls-cert /certs/Server.pem --tls-private-key /certs/Server.key ``` -## KUKSA.val databroker-cli +## KUKSA databroker-cli Can be run in TLS mode like below. @@ -66,50 +66,25 @@ Can be run in TLS mode like below. ~/kuksa.val/kuksa_databroker$ cargo run --bin databroker-cli -- --ca-cert ../certificates/CA.pem ``` -Default certificates and keys are not included in the default KUKSA.val Databroker-cli container, -so if running KUKSA.val Databroker-cli from a default container you need to mount the directory containing the keys and certificates. +Default certificates and keys are not included in the default KUKSA Databroker-cli container, +so if running KUKSA Databroker-cli from a default container you need to mount the directory containing the keys and certificates. ``` docker run --rm -it --net=host -v /home/user/kuksa.val/certificates:/certs databroker-cli --ca-cert /certs/CA.pem ``` -## KUKSA.val Server - -KUKSA.val Server uses TLS by default, but does not support mutual TLS. -By default it uses KUKSA.val example certificates/keys `Server.key`, `Server.pem` and `CA.pem`. - -``` -~/kuksa.val/kuksa-val-server/build/src$ ./kuksa-val-server --vss ./vss_release_4.0.json -``` - -It is possible to specify a different certificate path, but the file names must be the same as listed above. - -``` -~/kuksa.val/kuksa-val-server/build/src$ ./kuksa-val-server --vss ./vss_release_4.0.json -cert-path ../../certificates -``` - -In KUKSA.val Server the default certificates and keys are included in the container, so no need to -mount a directory if you want to use default certificates and keys. - -``` -docker run -it --rm -p 127.0.0.1:8090:8090 -e LOG_LEVEL=ALL kuksa-val:latest -``` - -If using the default KUKSA.val Server Docker container there is no mechanism to use different certificates, -as the [Dockerfile](../kuksa-val-server/docker/Dockerfile) specifies that the default shall be used. - -## KUKSA.val Client (command line) +## KUKSA Client (command line) See [KUKSA Python SDK](https://github.com/eclipse-kuksa/kuksa-python-sdk). -## KUKSA.val Client (library) +## KUKSA Client (library) -Clients like [KUKSA.val CAN Feeder](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) -that use KUKSA.val Client library must typically set the path to the root CA certificate. +Clients like [KUKSA CAN Provider](https://github.com/eclipse-kuksa/kuksa-can-provider) +that use KUKSA Client library must typically set the path to the root CA certificate. If the path is set the VSSClient will try to establish a secure connection. ``` -# Shall TLS be used (default False for Databroker, True for KUKSA.val Server) +# Shall TLS be used (default False for Databroker, True for KUKSA Server) # tls = False tls = True @@ -117,7 +92,7 @@ tls = True # Path to root CA, needed if using TLS root_ca_path=../../kuksa.val/certificates/CA.pem # Server name, typically only needed if accessing server by IP address like 127.0.0.1 -# and typically only if connection to KUKSA.val Databroker -# If using KUKSA.val example certificates the names "Server" or "localhost" can be used. +# and typically only if connection to KUKSA Databroker +# If using KUKSA example certificates the names "Server" or "localhost" can be used. # tls_server_name=Server ``` diff --git a/jwt/README.md b/jwt/README.md index 1663983c..13ba5eb1 100644 --- a/jwt/README.md +++ b/jwt/README.md @@ -4,7 +4,7 @@ This directory contains example tokens for demo and test purposes for KUKSA.val Databroker. -For more information on token format see [documentation](../doc/KUKSA.val_data_broker/authorization.md). +For more information on token format see [documentation](../doc/authorization.md). ## Available tokens