Gossamer
Verifiable supply-chain security for open source software.
Gossamer combines cryptographic signatures with transparency logs to ensure software updates are trustworthy.
The World Today
From NotPetya in 2017 to the SolarWinds hack of 2020, one unfortunate reality of the security of the Internet is this:
If an unauthorized third party can hack into one of the important servers on the Internet, they can instantly pivot into compromising millions of machines.
The software vulnerable to this type of attack includes package/dependency managers and automatic update features, including (but not limited to):
- WordPress's Automatic Updates for Themes and Plugins
- Composer (PHP dependency manager)
- NPM (Node.js dependency manager)
- Maven (Java dependency manager)
...many others (including most of your favorite programming languages' package managers).
Gossamer is our proposal for preventing these attacks.
How Gossamer Works
1. Digital Signatures
Every individual, team, or company that produces software will generate at least one keypair, consisting of two keys:
Signing Keys
- MUST be kept secret
- Secure at the 128-bit level
- a.k.a. Ed25519 secret keys
Verification Keys
- MUST be shared with users
- Mathematically bound to a specific Signing Key
- a.k.a. Ed25519 public keys
Software updates under Gossamer will be signed with the Signing Key to produce a Digital Signature.
Anyone (but especially users applying updates) can use the Verification Key to verify the Digital Signature is correct for each Software Update. If it's not correct, the update will not be installed.
Without significant cryptanalysis breakthroughs against the algorithm we use (Ed25519, from RFC 8032) or pilfering the Signing Key, nobody can forge a valid Digital Signature.
2. Transparency Log
Gossamer's use of Digital Signatures is reinforced by publishing all transactions on an append-only Cryptographic Ledger.
In total, there are many types of transactions that can be published:
- Appending a Key: Associates a new Verification Key with your identity.
- Revoking a Key: Removes an existing Verification Key from your identity. (Useful if keys are lost or stolen.)
- Publishing an Update: Includes the Digital Signature along with relevant metadata about your Software Update.
- Revoking an Update: Removes an existing Software Update from the list of versions trusted by end users.
- Attesting Something About an Update: See the next section.
Everything published on the Cryptographic Ledger is immutable and public.
Through Gossamer, your users not only be confident in the authenticity of your software updates, but also prove exactly when they were publicly available (and by whom).
3. Third-Party Attestations
Attestations are all about enabling immutable third-party verification.
In the spirit of open source, Attestations allow Third-Party Providers to assert some property about other Software Updates published by other Providers.
Given enough eyeballs, all bugs are shallow.— Linus's Law
Attestations can be any of the following:
- Successfully reproduced the built deliverable from the source code.
- Passed a quick spot check against malware injections.
- The code within this update has been peer-reviewed.
- A full security audit has been conducted against this update, with no outstanding issues found.
In short, Attestations allow us to mechanize Linus's Law and verify that people are looking at the code. Additionally, Attestations can be used as acceptance criteria before applying an update automatically.
Developer Experience
This might seem complicated, but the API that developers will need to learn is quite simple:
/**
 * @var GossamerClient $gossamer
 * @var string|resource|Psr\Http\Message\StreamInterface $file
 */

// Get the update record data:
$record = $gossamer->getUpdate('symfony/polyfill-php80', 'v1.20.0');

// If it's valid...
if ($record->isFileValid($file)) {
 // Install it!
 my_custom_installer($file);
}
It's that simple! The essential complexity of Gossamer is entirely under-the-hood.
To learn how to configure and use the Gossamer client in detail, click here.
Source Code and Documentation
Gossamer is permissively licensed open source software available on Github:
- libgossamer (PHP library that implements the specification)
- Gossamer CLI (command-line interface)
- Gossamer Server (HTTP REST API)
Documentation
Project Status
To learn more about a specific project and our current progress, click on its name.
Project Name | Status | Description |
---|---|---|
Developer Tools | In Progress (67%) | Specification, Library, Command Line Interface, etc. |
WordPress Integration | Pending | Gossamer for WordPress themes/plugins |
Composer Integration | Pending | Gossamer for PHP dependencies via Composer |
Special Thanks
We would like to offer our gratitude to some of the people who—one way or another—contributed to or inspired Gossamer over the years.
- Matt Barry (@poutine_hero)
- Discovered and disclosed a critical vulnerability in WordPress's update servers that could have been leveraged to take over every WordPress site on the Internet (via the automatic update feature).
- Frank Denis (@jedisct1)
- Developed and maintains libsodium and the PHP extension which continues to improve the cryptographic security of web applications every day.
- Taylor Hornby (@DefuseSec)
- Author of the Triangle of Secure Code Delivery, which served as a starting point for this entire project.
- Filippo Valsorda (@FiloSottile)
- Proposed a transparency log for securing Go package releases (which is approximately very similar to our design) and provided helpful documentation feedback based on his feedback with that project.
- SwiftOnSecurity (@SwiftOnSecurity)
-
Aside from years of being a fierce advocate of security for everyone
(which is awesome on its own right), they're always a great person to talk to—especially when you want
to know the questions that most users will think as they read your documentation.
If you found this webpage easy to understand, a lot of the thanks for that belongs to them.
This is far from an exhaustive list, and doesn't include any of the core developers or companies driving the Gossamer integration projects.