From d41748d2deab1ea07cc44b86b9a3b3a3013155c6 Mon Sep 17 00:00:00 2001 From: harshgounder Date: Sat, 8 Aug 2026 02:18:06 +0530 Subject: [PATCH] docs: clarify 'How does TUF secure updates?' for first-time readers Restructures the dense paragraph into four concrete questions the metadata chain answers (trusted keys, version, hashes, expiry), addressing #164. Signed-off-by: Harsh Gounder --- content/en/docs/overview.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/content/en/docs/overview.md b/content/en/docs/overview.md index cb04fb1..1b293e7 100644 --- a/content/en/docs/overview.md +++ b/content/en/docs/overview.md @@ -85,16 +85,24 @@ updater weaknesses that TUF is designed to defend against. ### How does TUF secure updates? -In a sense, TUF enhances security by adding verifiable records about the state -of a repository or application. By adding metadata containing information about -which signing keys are trusted, the cryptographic hashes of files, signatures on -the metadata, metadata version numbers, and the date after which the metadata -should be considered expired, it creates a record that can be checked to verify -the authenticity of update files. - -Your software update system never has to deal with this additional metadata or -understand what's going on underneath. TUF identifies the updates, downloads -them, and checks them against the metadata that it also downloads from the -repository. If the downloaded target files are trustworthy, TUF hands them over -to your software update system. For more information and examples, see +TUF adds a small layer of verifiable metadata alongside the files your update +system downloads. Before any file is trusted, TUF checks a chain of signed +records that answer four questions: + +1. **Who is allowed to sign?** A root metadata file lists the trusted signing + keys, so an attacker cannot introduce their own key. +2. **What is the current version?** Every metadata file carries a version + number, so an attacker cannot roll you back to an older, vulnerable update. +3. **What was signed?** The metadata contains cryptographic hashes of the + update files, so a file that was tampered with will not match its signed + hash. +4. **Is it still valid?** Metadata is timestamped and expires, so a signed + update that is months old is rejected rather than silently trusted. + +Your software update system never has to deal with this metadata directly. +TUF identifies the updates, downloads them, and checks them against the +metadata that it also downloads from the repository. If the downloaded target +files are trustworthy, TUF hands them over to your software update system. + +For more information and examples, see [Roles and metadata](docs/metadata/)