Draft: Adding a first early draft on handling of digital signatures #21
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
Binary file not shown.
Binary file not shown.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,122 @@ | ||||||
| # Trusting digital signatures in TEA | ||||||
|
|
||||||
| Software transparency requires a trust platform so that users | ||||||
| can validate the information and artefacts published. Given | ||||||
| the situation today any information published is better than | ||||||
| none, so the framework for digital signatures will not | ||||||
| be mandatory for API compliance. Implementations may | ||||||
| require all published information to be signed and | ||||||
| validated. | ||||||
|
|
||||||
| Within the | ||||||
| API documents can be signed with an electronic | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| signature. CycloneDX boms supports signatures within | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| the JSON file, but other artefacts may need external | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| signature files, a detached signature. | ||||||
|
|
||||||
| - __Integrity__: Documents dowloaded needs to be the same | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| as documents published | ||||||
| - __Identity__: | ||||||
| - Customers need to be able to verify the | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| publisher of the documents and verify that it is | ||||||
| the expected publisher. | ||||||
| - A TEA server may want to verify that published | ||||||
| documents are signed by the expected publisher | ||||||
| and that signatures are valid. | ||||||
|
|
||||||
| In order to sign an object, a pair of asymmetric keys will be | ||||||
| needed. The public key is used to create a certificate, signed | ||||||
| by a certificate authority (CA). The private key is used for | ||||||
| signing and needs to be protected. | ||||||
|
|
||||||
| A software publisher may buy CA services from a commercial vendor | ||||||
| or set up an internal solution. The issue with internal PKIs is that | ||||||
| external parties do not automatically trust that internal PKI. | ||||||
|
|
||||||
| This document outlines a proposal on how to build that trust and | ||||||
|
There was a problem hiding this comment. The above statements imply that the publisher controls one or more pairs of asymmetric keys, but that is not immediately clear from lines 20 to 27. Who is to sign the BOM if the party uploading the BOM or related artifacts is not the original publisher of the software? (FYI: For this reason, a related IETF standard talks about Issuer as a key role in their architecture; the publisher of software is not always the Issuer as defined by the IETF SCITT WG, and vice versa.) There was a problem hiding this comment. I think signing has to be optional. But the question of a third party that publishes something is a bit out of scope for our work, while I understand it is part of SCITT. I will consider this and see what can be done. |
||||||
| make it possible for publishers to use an internal PKI. It is | ||||||
| of course important that this PKI is maintained according to | ||||||
| best current practise. | ||||||
|
|
||||||
| ## API trust | ||||||
|
|
||||||
| The TEA API is built on the HTTP protocol with TLS encryption | ||||||
| and authentication, using the https:// URL scheme. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| The TLS server certificate is normally issued by a public Certificate | ||||||
| Authority that is part of the Web PKI. The client needs to validate | ||||||
| the TLS server certificate to make sure that the certificate name | ||||||
| (CN or Subject Alt Name) matches the host part of the URI. | ||||||
|
|
||||||
| If the certificate validates properly, the API can be trusted. | ||||||
| Validation proves that the server is the right server for the | ||||||
| given host name in the URL. This trust can be used to | ||||||
| implement trust in a private PKI used to sign documents. In | ||||||
| addition, trust anchors can be published in DNS as an extra | ||||||
| level of validation. | ||||||
|
|
||||||
| ## Getting trust anchors | ||||||
|
|
||||||
| Much like the EST protocol, the TEA protocol can be used | ||||||
| to download trust anchors for a private PKI. These are | ||||||
| PEM-encoded certificates in one single text file. | ||||||
|
|
||||||
| The TEA API has a `/trust-anchors/` API that will download | ||||||
| the current trust anchor APIs. This file is not signed, | ||||||
|
There was a problem hiding this comment.
Is APIs the correct word here @oej ? |
||||||
| that would cause a chicken-and-egg problem. The certificates | ||||||
|
Comment on lines
+65
to
+66
There was a problem hiding this comment.
Should we exclude à priori the signing of trust anchors? In the future they might be signed by some authority, e.g. regulators. |
||||||
| in the file are all signed. | ||||||
|
|
||||||
| An implementation should download these and apply them only | ||||||
| for this service, not in global scope. A PKI valid for example.com | ||||||
| is not valid for example.net. | ||||||
|
|
||||||
| ## Validating the trust anchors using DNSsec (DANE) | ||||||
|
|
||||||
| ## Digital signatures | ||||||
|
|
||||||
| ### Digital signatures as specified for CycloneDX | ||||||
|
|
||||||
| > "Digital signatures may be applied to a BOM or to an assembly within a BOM. | ||||||
| > CycloneDX supports XML Signature, JSON Web Signature (JWS), and JSON Signature Format (JSF). | ||||||
| > Signed BOMs benefit by providing advanced integrity and non-repudiation capabilities." | ||||||
| <https://cyclonedx.org/use-cases/#authenticity> | ||||||
|
|
||||||
| ### External (detached) digital signatures for other documents | ||||||
|
|
||||||
| - indication of hash algorithm | ||||||
| - indicator of cert used | ||||||
| - intermediate cert and sign cert | ||||||
|
|
||||||
| ### Validating the digital signature | ||||||
|
|
||||||
| ## Using Sigstore for signing | ||||||
|
|
||||||
| Sigstore is an excellent free service for both signing of GIT commits as well | ||||||
|
There was a problem hiding this comment. Is it the responsibility of the Transparency API described in this specification to compute and verify such hashes from external sources like Sigstore and/or elsewhere? There was a problem hiding this comment. That is a good question. I think validation primarily is when someone downloads artefacts. But it can of course also apply to publication - a server implementation may not accept signed documents that the server can not validate. Good question. There was a problem hiding this comment. With OCI (Docker) images the producer generates and uploads the signature to the registry alongside the image artifact using the |
||||||
| as artefacts by using ephemeral certificates (very shortlived) and a | ||||||
| certificate transparency log for validation and verification. | ||||||
| Sigstore signatures contain timestamps from a timestamping service. | ||||||
|
|
||||||
| ## Suggested PKI setup | ||||||
|
|
||||||
| ### Root cert | ||||||
|
|
||||||
| #### Root cert validity and renewal | ||||||
|
|
||||||
| ### Intermediate cert | ||||||
|
|
||||||
| #### Intermediate cert validity and renewal | ||||||
|
|
||||||
| ### Signature | ||||||
|
|
||||||
| #### Time stamp services | ||||||
|
|
||||||
| ### DNS entry | ||||||
|
|
||||||
| ## References | ||||||
|
|
||||||
| - IETF RFC DANE | ||||||
| - IETF DANCE architecture (IETF draft) | ||||||
| - IETF Digital signature | ||||||
| - JSON web signatures (JWS) - <https://datatracker.ietf.org/doc/html/rfc7515> | ||||||
| - JSON signature format (JSF) - <https://cyberphone.github.io/doc/security/jsf.html> | ||||||
| - [IETF Enrollment over Secure Transport (EST) RFC 7030](https://www.rfc-editor.org/rfc/rfc7030) | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # The TEA Collection object | ||
|
|
||
| For each product and version there is a Tea Collection object, which is a list | ||
| of available artifacts for this specific version. The TEA Index is a list of | ||
| TEA collections. | ||
|
|
||
| The TEA collection is normally created by the TEA application server at | ||
| publication time of artifacts. | ||
|
|
||
| If there are any updates of artifacts within a collection for the same | ||
| version of a product, then a new TEA Collection object is created and signed. | ||
| This update will have the same UUID, but a new version number. A reason | ||
| for the update will have to be provided. This shall only be used to | ||
| correct mistakes, spelling errors and similar things. If the product | ||
| is modified, that is a new product version and that should generate | ||
| a new collection object with a new UUID and updated metadata. | ||
|
|
||
| ## Collection object | ||
|
|
||
| The TEA Collection object has the following parts | ||
|
|
||
| * Preamble | ||
| * UUID of collection object | ||
| * Product name | ||
| * Product version | ||
| * Product Release date (timestamp) | ||
| * TEA Collection object release date (timestamp) | ||
| * TEA Collection object version (integer starting with version 1) | ||
| * Reason for update/release of TCO - clear text | ||
| * "New product release" | ||
| * "Corrected dependency in SBOM that was faulty" | ||
| * "Added missing In-Toto build attestation" | ||
| * List of artifact objects (see below) | ||
| * Optional Signature | ||
|
|
||
| The artifact object has the following parts | ||
|
|
||
| * Artifact UUID | ||
| * Artifact name | ||
| * List of objects with the same content. The order of the list has no significance. | ||
| * UUID for subdoc | ||
| * Optional BOM identifier | ||
| * SPDX or CycloneDX reference to BOM | ||
| * MIME media type | ||
| * Artifact category (enum) | ||
| * https://cyclonedx.org/docs/1.6/json/#externalReferences_items_type | ||
| * Description in clear text | ||
| * URL for downloads | ||
| * Size in bytes | ||
| * SHA384 checksum |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See #64