Keep the colleague's microbu-esp32c5 tree in this repository

obu-firmware builds against vanetza-idf from microbu-esp32c5/external, but
that tree was gitignored, so a clone of this repository could not build the
firmware it ships. It is now committed here as ordinary files in its own
folder, microbu-esp32c5/: the colleague's commit cf4b99f plus the V2X2MAP
bridge's signature verification (--trust) used on the bench. Nothing is
fetched from or pushed to the colleague's repository; this repository and
its remotes carry everything. The folder's own .gitignore keeps build output,
downloaded components and private key material out, as it did there; the
committed file set is identical to that repository's tracked files.

The ESP32-C5 is still flashed from obu-firmware/, which only takes
vanetza-idf from microbu-esp32c5/, so the two stay separate folders.
FLASHING.md says how to take a newer version of the colleague's tree (copy
it over the folder, rebuild, test, commit).

microbu-esp32c5/external/vanetza-idf/docs/tools/benchmark.md

@@ -0,0 +1,19 @@
+# Benchmark
+
+*Benchmark* is a tool to benchmark some components of Vanetza.
+At the moment, benchmarks for signing and validating packets exist.
+
+## Installation
+
+Benchmarks are not built by default, so you need to enable them explicitly.
+Run `cmake -D BUILD_BENCHMARK=ON ..` in your build directory to do so and start the build process again.
+You should be able to find `bin/benchmark` in your build directory afterwards.
+
+## Running
+
+You can run `bin/benchmark --help` to get a list of available benchmarks.
+You can run these with `bin/benchmark <name>` then.
+
+## Acknowledgement
+
+This application has been initially developed [Niklas Keller](https://github.com/kelunik).

microbu-esp32c5/external/vanetza-idf/docs/tools/certify-pqc.md

@@ -0,0 +1,125 @@
+# Certify PQC
+
+`certify-pqc` creates and checks experimental V3 certificate chains. It is a
+separate executable so enabling PQC does not change existing `certify` commands
+or their V2 output.
+
+Certificate generation accepts `--profile ecc` or `--profile hybrid`. The
+default is `hybrid`. The ECC profile exists to test interoperability against a
+classical-only V3 chain within the experimental ASN.1 profile, encoded without
+the alternative-key and signature fields.
+
+Build it with both options enabled:
+
+```shell
+cmake -S . -B build-pqc -DVANETZA_WITH_PQC=ON -DBUILD_CERTIFY=ON
+cmake --build build-pqc --target certify certify-pqc
+```
+
+## Generate a Chain
+
+Use the existing tool for ECC keys:
+
+```shell
+build-pqc/bin/certify generate-key root.key
+build-pqc/bin/certify generate-key aa.key
+build-pqc/bin/certify generate-key ticket.key
+```
+
+Generate FN-DSA key pairs for the authorities. The command appends
+`.pqc.key` and `.pqc.pub` to each base path automatically:
+
+```shell
+build-pqc/bin/certify-pqc generate-key root
+build-pqc/bin/certify-pqc generate-key aa
+```
+
+Generate the Root, AA, and AT in that order:
+
+```shell
+build-pqc/bin/certify-pqc generate-root \
+  --profile hybrid \
+  --output root.cert \
+  --subject-key root.key \
+  --subject-pqc-key root
+
+build-pqc/bin/certify-pqc generate-aa \
+  --profile hybrid \
+  --output aa.cert \
+  --sign-key root.key \
+  --sign-cert root.cert \
+  --sign-pqc-key root \
+  --subject-key aa.key \
+  --subject-pqc-key aa
+
+build-pqc/bin/certify-pqc generate-ticket \
+  --profile hybrid \
+  --output ticket.cert \
+  --sign-key aa.key \
+  --sign-cert aa.cert \
+  --sign-pqc-key aa \
+  --subject-key ticket.key
+```
+
+Root and AA certificates contain an FN-DSA public key and signature. The AT
+contains the FN-DSA signature but no FN-DSA public key.
+
+When `--aid` is omitted, authority certificates retain the established V3
+issue-permission defaults for CA, DEN, CP, GN management, and IPv6 routing,
+including their SSP ranges. Tickets default to CA and DEN application
+permissions. The AA also carries its subject ECC key as the public encryption
+key, matching the existing V3 certificate-generation behavior.
+
+The existing `certify generate-key` command writes PKCS#8 DER. The generated
+`.key` files are used directly as subject and issuer ECC keys by
+`certify-pqc`.
+
+### ECC-Only V3 Chain
+
+Use the same ECC keys without generating FN-DSA keys:
+
+```shell
+build-pqc/bin/certify-pqc generate-root \
+  --profile ecc --output root.cert --subject-key root.key
+
+build-pqc/bin/certify-pqc generate-aa \
+  --profile ecc --output aa.cert \
+  --sign-key root.key --sign-cert root.cert --subject-key aa.key
+
+build-pqc/bin/certify-pqc generate-ticket \
+  --profile ecc --output ticket.cert \
+  --sign-key aa.key --sign-cert aa.cert --subject-key ticket.key
+```
+
+These certificates contain only the standard ECC verification keys and
+signatures, but they are still encoded with the experimental ASN.1 profile.
+They are intended for ECC/hybrid comparisons between PQC-capable builds. They
+are not interchangeable with credentials encoded by a strict build because
+the profiles have different OER extension preambles.
+
+## Inspect and Verify
+
+```shell
+build-pqc/bin/certify-pqc show ticket.cert
+
+build-pqc/bin/certify-pqc verify-chain \
+  --profile hybrid \
+  --root root.cert \
+  --aa aa.cert \
+  --ticket ticket.cert \
+  --aid 36
+```
+
+`verify-chain` performs existing V3 certificate policy checks, verifies every
+outer ECC signature, requires the expected hybrid material, and verifies every
+inner FN-DSA signature.
+
+The optional `--aid` selects the ITS-AID checked against the chain's
+permissions and defaults to Cooperative Awareness (`36`). Use the same AID
+when generating and verifying a chain with custom permissions.
+
+Use `--profile ecc` to verify an ECC-only V3 chain. This additionally rejects
+the chain if any alternative PQC material is present.
+
+Use `certify-pqc COMMAND --help` to see optional subject names, validity, and
+ITS-AID arguments.

microbu-esp32c5/external/vanetza-idf/docs/tools/certify.md

@@ -0,0 +1,47 @@
+# Certify
+
+*Certify* is a tool to create and view certificates and can be used to set up a test PKI for secured V2X communication based on TS 103 097 v1.2.1.
+
+## Installation
+
+You need to enable building this tool explicitly.
+Run `cmake -D BUILD_CERTIFY=ON ..` in your build directory and rebuild Vanetza.
+You should be able to find `bin/certify` in your build directory afterwards.
+
+## PKI Setup
+
+The following section describe how to setup a test PKI.
+We will generate a root certificate, an authorization authority certificate and an authorization ticket.
+
+### Generating Keys
+
+New private keys can be generated using `bin/certify generate-key root.key`.
+The corresponding public key can be extracted using `bin/certify extract-public-key --private-key root.key root.pub`, but this step usually isn't required.
+
+Please generate a `root.key` for the root certificate, a `aa.key` for the authorization authority and a `ticket.key` for the authorization ticket.
+
+### Generating Root Certificates
+
+A root certificate can be generated using `bin/certify generate-root --subject-key root.key root.cert`.
+
+### Generating Authorization Authorities
+
+An authorization authority certificate can be generated using `bin/certify generate-aa --sign-key root.key --sign-cert root.cert --subject-key aa.key aa.cert`.
+
+### Generating Authorization Tickets
+
+An authorization ticket can be generated using `bin/certify generate-ticket --sign-key aa.key --sign-cert aa.cert --subject-key ticket.key ticket.cert`.
+
+If you're generating a certificate for real V2X hardware, it will likely use a hardware security module (HSM), which will only expose the public key.
+You can export the given public key to a file and use `--subject-key` also with public keys.
+The public key needs to be encoded according to the rules specified by ETSI in TS 103 097 v1.2.1.
+
+## Other Options
+
+This guide only uses the required options.
+Further options may be available for certain commands.
+Use `bin/certify <command> --help` for further information.
+
+## Acknowledgement
+
+This application has been initially developed [Niklas Keller](https://github.com/kelunik).

microbu-esp32c5/external/vanetza-idf/docs/tools/fuzz-harness.md

@@ -0,0 +1,27 @@
+# fuzz-harness
+
+The fuzz harness for Vanetza is a testing tool designed to identify bugs, vulnerabilities, and unexpected behaviors within Vanetza's codebase. Fuzz testing, also known as fuzzing, involves providing invalid, unexpected, or random data as input to a program to uncover errors or security issues.
+
+## Requirements
+
+You will need AFL++ installed on your system.
+Please refer to the [AFL++ documentation](https://aflplus.plus/docs/install/) for installation instructions.
+Alternatively, you can use the scripts located at *tools/fuzz-harness* for running fuzz tests in a Docker container.
+
+## Usage
+
+Running the script *fuzz-harness/docker.sh* will build a suitable Docker container based on the official *aflplusplus/aflplusplus* image.
+As soon as the container is ready, the script launches the built container and maps your local user and some Vanetza directories into it.
+
+Within the container, you can compile the *fuzz-harness* using the AFL++ toolchain by invoking the *compile.sh* script.
+The *fuzz.sh* script is a convenient way to run the built harness with *afl-fuzz*.
+If it crashes immediately, try again a few times. 
+
+### Analyse
+
+Fuzzing is executing the *fuzzing-persistent* executable.
+You can use its sibling *fuzzing-run* to investigate a particular crash and get more information about the possible problems.
+The address sanitizer is enabled by default. If you're not interested in memory leaks, make sure to disable the leak sanatizer by setting the environment variable `ASAN_OPTIONS=detect_leaks=0`.
+
+You may also want to classify the found issues using *casr-afl*: `casr-afl -i output -o output/casr`
+The classification process also eliminates duplicate issues.

microbu-esp32c5/external/vanetza-idf/docs/tools/socktap.md

@@ -0,0 +1,199 @@
+# Socktap
+
+*socktap* is an example application demonstrating API usage of Vanetza libraries.
+You can run this demo application on commodity hardware, i.e. no special V2X or Car2X hardware is required.
+If you have an IEEE 802.11p compatible network interface card, though, socktap can also communicate with other ITS-G5 stations.
+
+Consider *socktap* as an experimental application showcasing some of Vanetza's features but not as a full-grown ITS-G5 station.
+However, *socktap* may be the starting point for your custom application.
+Just keep in mind that Vanetza supports more features than those integrated in *socktap*.
+For example, *socktap* omits *Decentralized Congestion Control* (DCC) entirely though Vanetza supports this feature.
+
+
+## Link layer
+
+At the moment, six link layer implementations exist for *socktap*.
+You can choose via the `--link-layer` argument which implementation to use:
+
+- *ethernet* runs on Linux raw packet sockets
+- *cube-evk* runs nfiniity's link-layer implementation for the cube-evk
+- *autotalks* uses the Autotalks API to run on Autotalks hardware
+- *cohda* employs Cohda's LLC API
+- *udp* runs GeoNetworking on top of IP/UDP multicast sockets
+- *tcp* runs GeoNetworking on top of IP/TCP sockets
+- *rpc* uses *Cap’n Proto* interchange format and RPC with external server
+
+
+### Ethernet
+
+The *ethernet* variant has been initially *socktap*'s only available link-layer implementation.
+In this mode, *socktap* will send and receiver Ethernet frames on the specified network interface (see `--interface` argument).
+
+Please be aware that *socktap* needs special privileges to access the raw sockets.
+Either run *socktap* as root user or set the `CAP_NET_RAW` capabilities on the *socktap* executable.
+You can do this via `sudo setcap cap_net_raw+ep bin/socktap`.
+When `CAP_NET_RAW` is attached to the *socktap* binary you can run it as an ordinary user.
+
+
+### CUBE-EVK
+
+If you have access to a cube-evk from [nfiniity](https://www.nfiniity.com/#portfolio) you can use socktap on your personal computer and connect to the EVK. In this mode the EVK is used as wireless remote radio. Moreover, you can use socktap on the EVK natively as well. Please refer to our [Running socktap on nfiniity devices](../recipes/cube-evk-build.md) for more details.
+
+
+### Cohda
+
+If you have access to V2X hardware from Cohda Wireless, you can also run *socktap* on their units.
+In the *cohda* mode, *socktap* uses Cohda's LLC API for sending and receiving data frames.
+This mode is similar to *ethernet* but depends on the Cohda SDK.
+Please refer to our [Cohda SDK building recipe](../recipes/cohda-sdk-build.md) for details.
+
+
+### Autotalks
+
+Another option involving dedicated V2X hardware uses the Autotalks API.
+Please have a look at our [Building for Autotalks devices](../recipes/autotalks-sdk-build.md) guide how to incorporate the Autotalks SDK.
+
+> [!WARNING]
+> Our Autotalks link layer integration is deprecated. Please use the RPC link layer as a superior replacement.
+
+
+### UDP
+
+A relatively new addition is the *udp* mode, which allows running *socktap* without any privileges.
+GeoNetworking packets are wrapped into UDP datagrams and sent to the IP multicast group **239.118.122.97** on UDP port **8947**.
+Further *socktap* instances within the same IP multicast network exchange GeoNetworking packets then.
+You can consider this as "GeoNetworking over IP/UDP".
+
+
+### TCP
+
+The TCP implementation is similiar to the UDP one.
+However, TCP adds the arguments `--tcp-accept` and `--tcp-connect`, which allow the user to accept incoming TCP connections or connect to open TCP sockets, respectively.
+Both arguments expect a comma separated list of `ip:port`.
+Outgoing GeoNetworking packets will then be sent to all active TCP connections.
+
+### RPC
+
+RPC link layer lets socktap connect to an external RPC server over [Cap’n Proto](https://capnproto.org/).
+You can refer to [MACH SYSTEMS's RPC link](https://github.com/mach-systems/RPC-link) for developing the server on your own V2X hardware, e.g. Autotalks EVKs.
+The [cube V2X devices](https://cubesys.io) ship a compatible *cube-radio-rpc* service with *cube:os* 1.4 and later.
+
+#### Command line flags
+- `--rpc-host <HOST>` –⁠⁠⁠⁠⁠ hostname or IP of the RPC server (default: `localhost`)
+- `--rpc-port <PORT>` –⁠⁠⁠⁠⁠⁠ TCP port on which the server is listening (default: `23057`)
+- `--rpc-radio-technology <TECH>` –⁠⁠⁠⁠ radio technology to advertise to the server; valid values:  
+  - `ITS-G5` –⁠⁠⁠⁠⁠⁠ 802.11p / bd
+  - `LTE-V2X|C-V2X` –⁠⁠⁠⁠⁠⁠ LTE-V2X / 5G-V2X
+- `--rpc-debug` –⁠⁠⁠⁠⁠⁠ enable debugging output
+
+
+## Positioning
+
+Many components of an ITS-G5 system depend on positioning data.
+Ideally, you have a GPS receiver attached to the computer running [gpsd](http://catb.org/gpsd) along with *socktap*.
+If you do not have a GPS receiver or no GPS signal in your environment, you can also set a static position manually.
+
+The `--positioning` argument controls if *gpsd* provides live GPS position fixes or if socktap shall use a *static* position fix.
+See also the `--latitude` and `--longitude` arguments for the latter option.
+
+
+## Applications
+
+Earlier, multiple variants of *socktap* existed as separate executables.
+Nowadays, *socktap* is the unified executable which can be configured in many ways.
+These configuration options substitute the deprecated executables.
+
+You can choose from three simple example V2X applications to run with *socktap* via the `--applications` argument:
+
+- *ca* sends Cooperative Awareness Messages (CAM)
+- *hello* sends simple BTP-B message with the binary payload `0xc0ffee`
+- *benchmark* counts the number of any received messages and prints the current message rate once per second
+
+
+## Hybrid-PQC Certificate Validation
+
+An experimental build configured with `VANETZA_WITH_PQC=ON` adds the
+`--enable-pqc-verification` option. With `--security certs-v3`, this verifies
+the outer ECC signatures in the configured Root-to-AT certificate chain and
+also verifies FN-DSA-512 alternative signatures whenever they are present.
+External certificate, key, and chain files are required; the option does not
+support socktap's built-in naive V3 credentials.
+
+Provide the authorization ticket and its PKCS#8 DER ECC private key with
+`--certificate` and `--certificate-key`. This is the format written by
+`certify generate-key`. Provide its issuer certificates with
+`--certificate-chain`, normally the AA followed by the trusted Root CA:
+
+```shell
+bin/socktap \
+  --link-layer udp \
+  --interface lo \
+  --mac-address 02:00:00:00:00:11 \
+  --applications ca \
+  --positioning static \
+  --latitude 48.7668616 \
+  --longitude 11.432068 \
+  --security certs-v3 \
+  --crypto-backend OpenSSL \
+  --enable-pqc-verification \
+  --certificate ticket.cert \
+  --certificate-key ticket.key \
+  --certificate-chain aa.cert root.cert
+```
+
+This DER behavior is limited to `--enable-pqc-verification`; normal V3
+operation retains upstream socktap's PEM key format.
+
+The option permits purely ECC chains for interoperability between nodes built
+with the experimental profile, but rejects invalid or inconsistent PQC
+material. It affects certificate-chain validation only; the secured CAM or
+other application message is still signed with ECC. An unmodified strict build
+cannot receive hybrid certificates because its ASN.1 model does not preserve
+the experimental fields needed for certificate canonicalization. An ECC-only
+chain produced by `certify-pqc` also retains the experimental profile's OER
+layout and therefore requires a PQC-profile build.
+
+ECC and hybrid certificates generated as separate chains normally have
+different Root CAs. A PQC-capable receiver must be given the AA and Root of
+every chain it is expected to trust; loading only its own chain does not make an
+independently generated peer chain trusted.
+
+
+## Building and Running
+
+You need to enable the CMake option `BUILD_SOCKTAP` so *socktap* will be built at all.
+Two further CMake options control which optional features are included into the *socktap* executable.
+
+
+### Build options
+
+First, the option `SOCKTAP_WITH_COHDA_LLC` enables the link-layer variant for operation on Cohda V2X devices.
+This option usually makes only sense if you are cross-compiling *socktap* for a Cohda device.
+
+If CMake finds *gpsd* on your system, the option `SOCKTAP_WITH_GPSD` is enabled by default.
+The integration of GPS receivers depends on this option.
+If this option is disabled, you can only configure static positions with *socktap*.
+
+
+!!! warning
+    A bug in gpsd<=3.15 causes a segmentation fault when *socktap* tries to fetch GPS data.
+    More recent versions include a bugfix, e.g. gpsd>=3.17 is known to work.
+    See also the corresponding [issue ticket #69](https://github.com/riebl/vanetza/issues/69).
+
+
+### First steps
+
+You can locate *socktap* in your build directory at **bin/socktap**.
+Run this executable with `--help` appended to see the list of available runtime configuration options.
+With the *ethernet* link-layer you should specify the network device on which *socktap* should send and receive packets via `--interface`.
+Usually, such devices are named *eth0* or *wlan0*. You can look up the available devices on your machine with the `ip link` command.
+
+If you want to use the local loopback device (usually `lo`) you need to override the used MAC address using `--mac-address` to receive packets.
+Otherwise, the MAC address is `00:00:00:00:00:00` for both sides and the router drops incoming packets matching its address.
+
+
+## Acknowledgement
+
+This demo application has been initially developed as part of a student's project at Hochschule Darmstadt in summer term 2016.
+Participating students were in alphabetical order: Sachin Kashyap Bukkambudhi Satyanarayana, Alvita Marina Menezes, Mrunmayi Parchure, Subashini Rajan and Deeksha Venkadari Yogendra.
+Since then, [@kelunik](https://github.com/kelunik) and [@glmax](https://github.com/glmax) have contributed a lot to *socktap*.