Security Principles =================== This section describes the security principles that guide Shyft development, release handling, and operational trust. Core Principles ---------------- Shyft aims to establish a practical, transparent, and reviewable trust chain from developer identity to released artifacts. The core principles are: - identity must be bound to controlled cryptographic keys - signing keys used for release and repository control must be protected by hardware-backed key storage (e.g., Nitrokey or equivalent) - hardware-backed keys are strongly recommended for all maintainers and contributors, and are expected to become a baseline requirement over time - release-critical operations must not depend on a single unmanaged or unverifiable system; trusted environments must be explicitly controlled, hardened, and auditable - where a single-operator model is used, that operator assumes full responsibility for the integrity and security of the trusted environment - backups of secret keys must be encrypted, verified after creation, and stored with controlled and auditable access - governance must define who is allowed to sign, approve, revoke, and recover cryptographic identities and release authority - governance models may range from single-operator responsibility to multi-party approval ("two-person rule"), depending on the maturity and requirements of the deployment environment - procedures must be documented such that they can be independently reviewed, verified, and repeated These principles define the minimum requirements for maintaining the integrity of the Shyft trust chain. Threat model ------------ Shyft assumes a threat model where: - source code repositories, build systems, and distribution channels may be subject to compromise or unauthorized modification - individual developer environments may be partially trusted but not authoritative - downstream environments require independent verification of artifacts The security model is therefore designed to ensure that: - no single system implicitly defines trust - all critical actions are cryptographically verifiable - trust can be independently established by downstream consumers Upstream–downstream trust separation ------------------------------------ Shyft is designed to separate trust between upstream source control and downstream operational environments. The open-source Shyft project acts as an upstream reference for: - source code - versioning and release tags - development and review processes At the same time, many contributors and maintainers are part of larger organizations (e.g., energy companies, research institutions, or government entities) that operate their own controlled infrastructure. In these environments: - Shyft is typically built, validated, and deployed using internal systems - additional security, compliance, and operational requirements are applied - upstream artifacts are not required to be used directly in production To support this separation, Shyft establishes: - verifiable release tags and history - strong identity binding for contributors and maintainers - controlled release and signing procedures - a clear decoupling between upstream trust (source and tagging) and downstream trust (build, validation, and deployment) Release tags in the upstream repository serve as: - stable and auditable reference points - inputs to downstream build and packaging pipelines This enables organizations to: - independently verify and rebuild Shyft from source - integrate Shyft into regulated or security-sensitive environments - maintain full control over their own supply chain This separation ensures that downstream systems do not depend on a single upstream operational environment for trust, but can establish their own independent verification, build, and deployment processes. This model limits the impact of a potential upstream compromise, as downstream systems retain independent control over verification, build, and deployment decisions. Build and CI/CD systems ----------------------- Build systems and CI/CD infrastructure are not considered trust anchors. They may be used to automate builds and testing, but artifacts produced by such systems are not considered trusted unless independently verified and cryptographically signed. Release artifacts must be produced within a controlled, hardened, and auditable environment, signed using the designated release-signing key, and then published through suitable distribution channels. This ensures that compromise of CI/CD systems does not directly compromise the integrity of released artifacts. Bootstrapping organizational practices ---------------------------------------- Shyft aims to demonstrate practical and robust approaches to: - identity management (e.g., GPG-based signing) - controlled access and governance - reproducible and verifiable builds These practices are intentionally designed to be: - simple enough to adopt incrementally - compatible with corporate and governmental requirements - usable as a reference model for internal processes Since adoption within large organizations is often gradual, Shyft provides a working implementation of these principles that can be adapted and extended over time. Operational Maturity -------------------- The Shyft project currently operates with a small set of trusted maintainers and a primarily single-operator release model. Security principles defined in this document describe both: * requirements that are enforced in the current release process * practices that are expected to be adopted as the project and its governance mature This approach ensures transparency about the current trust model while providing a clear path toward stronger multi-party governance where required. The current model relies on: * hardware-backed key storage for release signing * controlled and hardened environments for release operations * clearly defined responsibility for release authority These properties provide a strong baseline for trust, while allowing the governance model to evolve as needed. Trust anchor ------------- The primary trust anchor in the Shyft security model is the release-signing key. Trust in distributed artifacts is established by verifying signatures produced by this key, which is bound to a controlled identity and protected using hardware-backed storage. All other elements (e.g., repositories, build systems, and distribution channels) are considered untrusted unless verified through this mechanism. Trust Chain ------------ The intended trust chain is: :: person -> hardware-backed key -> signed action -> signed artifact -> verified consumer Each step in this chain must be independently verifiable. The transition from reviewed source code to signed artifacts must occur within a controlled and auditable environment, ensuring that the signed artifact corresponds exactly to the intended source state (e.g., a tagged commit). For contributors, this typically means: - SSH authentication for source control access - GPG signing for commits or tags where applicable For release management, this additionally includes: - controlled and hardware-backed signing keys - governed release approval - signed release metadata and packages - independent verification by users or operators Relationship to Release Procedures ---------------------------------- The release procedures in the ``releases`` section build on the identity and key handling requirements documented in: :doc:`identity/gpg-ssh-keys` See also: * :doc:`../releases/release-process` * :doc:`../releases/signing-keys` * :doc:`../releases/package-verification`