diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..e02adda4 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# Default owners for everything in the repo. Review routing only — the +# main-branch ruleset does not currently require code-owner approval. +* @luminartech/luv diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..a81db8a6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,129 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +. All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla]. + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at +. + +[homepage]: https://www.contributor-covenant.org +[mozilla]: https://github.com/mozilla/inclusion diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..dd4afd1b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,87 @@ +# Contributing + +Pull requests are welcome, as are bug reports and questions in the issue +tracker. + +The crate implements ISO 14229-1:2020. The service table in +[`README.md`](README.md) tracks which services are supported, partially +supported, or not yet started — it is the place to look before adding one. + +## Building and testing + +The minimum supported Rust version is **1.85.0**, declared as `rust-version` in +`Cargo.toml`. + +`default = ["std"]`, and the feature graph is layered: `std` implies `alloc`, +and both `utoipa` and `clap` imply `std` because their derive macros expand to +`std::`, `String` and `Vec` paths. `utoipa` additionally implies `serde`, +because a `ToSchema` describes this crate's *serde* representation. `serde` is +the only optional integration usable on a bare-metal target. + +```sh +cargo test # default: std +cargo test --all-features # everything +cargo test --no-default-features # the no_std core alone +cargo test --no-default-features --features alloc,serde +``` + +The `no_std` core must keep building for a bare-metal target: + +```sh +rustup target add thumbv7em-none-eabihf +cargo check --no-default-features --target thumbv7em-none-eabihf +``` + +The integration tests each guard a different property: + +- `tests/spec_conformance.rs` — encodings against ISO 14229-1:2020. +- `tests/public_api.rs` — the public surface, so that additions to it are + deliberate rather than incidental. +- `tests/openapi_schema.rs` — the `utoipa` schemas, which must describe the + serde representation rather than the Rust shape. + +## Wire-format changes + +Several types serialize as a single protocol byte rather than as their Rust +shape. A round-trip test written against the crate's own output passes whenever +`encode` and `decode` share the same misreading, so a change that alters the +bytes on the wire should be pinned by a case in `tests/spec_conformance.rs` +with the specification's bytes written out literally. + +The fuzz targets in `fuzz/fuzz_targets/` cover request decoding, response +decoding, and round-tripping. A decode bug is best reported as a fuzz input. + +## Commits and pull requests + +Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/) +(`feat:`, `fix:`, `docs:`, `build:`, `chore:`, with a `!` for a breaking +change), because the changelog is organized around them. Say what changed and +why in the body. + +This repository merges with **merge commits** — squash and rebase are both +disabled — so the subjects of the commits on your branch are what land on +`main`, and those are what release-plz reads to build the changelog and compute +the next version. Keep them clean; a tidy PR title does not stand in for them +here. CI additionally lints the PR title for conventional-commit grammar. + +Installing the hooks checks the same grammar locally, before the push rather +than in CI: + +```sh +pre-commit install --install-hooks +``` + +## Releases + +[release-plz](https://release-plz.dev) owns versioning, the changelog, tags, +GitHub releases, and the crates.io publish. There is no release workflow in +this repository and no version to bump by hand: a push to `main` maintains an +open release PR, and merging that PR publishes. `release-plz.toml` holds the +configuration, shared with `simple_doip` and `automotive_wire_codec`. + +## Continuous integration + +CI is a thin caller for the org-wide reusable workflow in +[`luminartech/rust_workflow`](https://github.com/luminartech/rust_workflow); +`.github/workflows/main.yml` owns only the triggers and this crate's +configuration. Changes to the jobs themselves belong in that repository. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..e18d4adc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,49 @@ +# Security policy + +## Reporting a vulnerability + +Report security issues through GitHub's private vulnerability reporting: open +the [Security tab](https://github.com/luminartech/uds_protocol/security) and +choose **Report a vulnerability**. That opens a private advisory visible only +to the maintainers. + +Please do not open a public issue for a security report. + +A report is most useful with the crate version, the feature set enabled, and a +byte sequence or test case that reproduces the behavior. + +## Supported versions + +This crate is pre-1.0. Fixes land on the latest published version; there are no +maintained release branches. + +## Scope + +`uds_protocol` encodes and decodes ISO 14229-1:2020 messages. It is a codec: it +does not own a transport, a session, or a key. Three properties of UDS matter +when assessing a report, because they are the specification's design rather +than defects in this crate: + +- **UDS carries no transport security.** ISO 14229 defines a service layer. + Confidentiality and integrity, where they exist at all, belong to the + transport underneath it — DoIP, ISO-TP over CAN — and to the layers above. + A UDS message read off the wire in the clear is the protocol working as + specified. +- **`SecurityAccess` (0x27) is not authentication.** It is a seed/key unlock + whose strength lives entirely in the ECU's key algorithm, which this crate + neither generates nor validates — it encodes and decodes the exchange. The + services ISO 14229-1:2020 defines for actual cryptographic protection, + `Authentication` (0x29) and `SecuredDataTransmission` (0x84), are **not + implemented here**. A system built on this crate has no authenticated + diagnostic channel unless it provides one itself. +- **Several supported services write to the ECU by design.** + `RequestDownload` (0x34), `RequestUpload` (0x35), `TransferData` (0x36) and + `RequestFileTransfer` (0x38) exist to move memory and files. That this crate + will encode and decode them is the point; deciding who may send them is the + ECU's responsibility, not the codec's. + +What is in scope: anything that makes the crate misbehave on attacker-supplied +bytes — a panic, an out-of-bounds read, an unbounded allocation, a decode that +accepts a frame it should reject, or a hang reachable from the wire. The fuzz +targets in `fuzz/fuzz_targets/` cover request decoding, response decoding and +round-tripping; a reproducer expressed as a fuzz input is ideal.