Update

Signed-off-by: Olle E. Johansson <[email protected]>

Author: oej

signatures/signature.md

@@ -1,26 +1,29 @@
-# Trusting digital signatures in TEA
+# Transparency Exchange API - 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.
+validated. In some vertical markets branch standards may require
+digital signatures.
 
-Within the
-API documents can be signed with an electronic
+Within the TEA API documents may be signed with an electronic
 signature. CycloneDX boms supports signatures within
 the JSON file, but other artefacts may need external
 signature files, a detached signature.
 
+## Requirements
+
+Digital signatures provide integrity and identity to published data.
+
 - __Integrity__: Documents dowloaded needs to be the same
   as documents published
-- __Identity__:
-  - Customers need to be able to verify the
+- __Identity__: Customers need to be able to verify the
   publisher of the documents and verify that it is
   the expected publisher.
-  - A TEA server may want to verify that published
+  A TEA server may want to verify that published
   documents are signed by the expected publisher
   and that signatures are valid.
 
@@ -30,7 +33,7 @@ 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
+or set up an internal PKI 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
@@ -45,15 +48,23 @@ and authentication, using the https:// URL scheme.
 
 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.
+the TLS server certificate to make sure
+
+- that the certificate name (CN or Subject Alt Name) matches the
+  host part of the URI.
+- that the certificate is valid, i.e. the not-before date and the
+  not-after date is not out of range
+- that the certificate is signed by a trusted CA
 
 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.
+given host name in the URL. 
+
+This trust can be used to implement trust in a private PKI
+used to sign documents delivered over the API. 
+
+In addition, trust anchors can be
+published in DNSsec as an extra level of validation.
 
 ## Getting trust anchors
 
@@ -70,6 +81,10 @@ 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.
 
+Note that the TEA api can host many years of documents for
+published versions. Old and expired trust anchors may be needed
+to validate digital signatures on old documents.
+
 ## Validating the trust anchors using DNSsec (DANE)
 
 ## Digital signatures
@@ -96,6 +111,11 @@ 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.
 
+Sigstore lends itself very well to Open Source projects but not really
+commercial projects. The Sigstore platform can be deployed internally
+for enterprise use, but in that case will have the same problem as any
+internal PKI with establishing trust.
+
 ## Suggested PKI setup
 
 ### Root cert