Merge pull request #72 from oej/update-discovery

Discovery: Change to HTTPS DNS records

Author: oej

discovery/readme.md

@@ -12,26 +12,39 @@
 - [The TEA Version Index](#the-tea-version-index)
 - [References](#references)
 
-
 ## From product identifier to API endpoint
 
 TEA Discovery is the connection between a product identifier and the API endpoint.
+A "product" is something that the customer aquires or downloads. It can be a bundle
+of many digital devices or software applications. A "product" normally also has an
+entry in a large corporation's asset inventory system.
+
 A product identifier is embedded in a URN where the identifier is one of many existing
-identifiers or a random string - like an EAN bar code, product
+identifiers or a random string - like an EAN or UPC bar code, UUID, product
 number or PURL.
 
 The goal is for a user to add this URN to the transparency platform (sometimes with an
 associated authentication token) and have the platform access the required artifacts
 in a highly automated fashion.
 
+## Advertising the TEI
+
+The TEI for a product can be communicated to the user in many ways.
+
+- A QR code on a box
+- On the invoice or delivery note
+- For software with a GUI, in an "about" box
+
 ## TEA Discovery - defining an extensible identifier
 
 TEA discovery is the process where a user with a product identifier can discover and download
 artifacts automatically, with or without authentication. A globally unique identifier is
 required for a given product. This identifier is called the Transparency Exchange Identifier (TEI).
 
-The TEI identifier is based on DNS, which assures a uniqueness per vendor (or open source project) 
-and gives the vendor a name space to define product identifiers based on existing or new identifiers like EAN bar code, PURLs or other existing schemes. A given product may have multiple identifiers as long as they all resolve into the same destination.
+The TEI identifier is based on DNS, which assures a uniqueness per vendor (or open source project)
+and gives the vendor a name space to define product identifiers based on existing or new identifiers
+like EAN/UPC bar code, PURLs or other existing schemes. A given product may have multiple identifiers
+as long as they all resolve into the same destination.
 
 ## The TEI URN: An extensible identifier
 
@@ -42,12 +55,7 @@ to global uniqueness without new registries.
 The TEI can be shown in the software itself, in shipping documentation, in web pages and app stores.
 TEI is unique for a product, not a version of a software. The TEI consist of three core parts
 
-- The **`type`** which defines the syntax of the unique identifier part
-- The **`domain-name`** part does not have to exist as a web server (HTTPS), but may do
-  - The uniqueness of the name is the domain name part that has to be registred at creation of the TEI.
-- The **`unique-identifier`** has to be unique within the `domain-name`. Recommendation is to use a UUID but it can be an existing article code too
-
-A TEI belongs to a single product. A product can have multiple TEIs - like one with a EAN
+A TEI belongs to a single product. A product can have multiple TEIs - like one with a EAN/UPC
 barcode and one with the vendor's product number.
 
 ### TEI syntax
@@ -56,6 +64,12 @@ barcode and one with the vendor's product number.
 urn:tei:<type>:<domain-name>:<unique-identifier>
 ````
 
+- The **`type`** which defines the syntax of the unique identifier part
+- The **`domain-name`** part resolves into a web server, which may not be the API host.
+  - The uniqueness of the name is the domain name part that has to be registred at creation of the TEI.
+- The **`unique-identifier`** has to be unique within the `domain-name`.
+  Recommendation is to use a UUID but it can be an existing article code too
+
 **Note**: this requires a registration of the TEI URN schema with IANA - [see here](https://github.com/CycloneDX/transparency-exchange-api/issues/18)
 
 ### TEI types
@@ -75,6 +89,7 @@ urn:tei:purl:<domain-name>:<purl>
 ````
 
 Example:
+
 ```text
 urn:tei:purl:cyclonedx.org:pkg:pypi/cyclonedx-python-lib@8.4.0?extension=whl&qualifier=py3-none-any
 ```
@@ -95,9 +110,9 @@ Note that there is a TEI SWID type as well as a PURL SWID type.
 
 Where the `unique-identifier` is a Hash. Supports the following hash types:
 
-* SHA256
-* SHA384
-* SHA512
+- SHA256
+- SHA384
+- SHA512
 
 ```text
 urn:tei:hash:<domain-name>:<hashtype>:<hash>
@@ -132,58 +147,56 @@ urn:tei:uuid:cyclonedx.org:d4d9f54a-abcf-11ee-ac79-1a52914d44b1
 - GS1
 - STD
 
-
 ### TEI resolution using DNS
 
-The name part of the TEI is used in a DNS query to find one or multiple locations for product transparency exchange information.
-At the URL we need a well-known name space to find out more
+The `domain-name` part of the TEI is used in a DNS query to find one or multiple locations for
+product transparency exchange information.
+
+At the URL a well-known name space is used to find out where the API endpoint is hosted.
+This is solved by using the ".well-known" name space as defined by the IETF.
 
 - `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
 - Syntax: `urn:tei:uuid:<name based on domain>:<unique identifier>`
 
 The name in the DNS name part points to a set of DNS records.
-A TEI with name “tex.example.com" queries for `_tei._tcp.tex.example.com URI records`.
-These point to URIs for the transparency exchange data.
-If there are no records, try to resolve the name (using AAAA and A DNS records) and
-append the /.well-known/tei prefix
 
-```dns
-_tei._tcp.tex.example.com.   3600 IN URI 10 1 “https://www.example.com/transparency“
-```
+A TEI with name `tea.example.com` queries for `tea.example.com` `A` and `AAAA` records.
+These point to the hosts available for the Transparency Exchange API.
 
-Example response of DNS query including multiple URIs with a priority
+The TEA client connects to the host using HTTPS and validates the certificate.
+The URI is composed of the name with the `/.well-known/tea` prefix added.
+
+This results in the base URI (without the product identifier) 
+`https://tea.example.com/.well-known/tea/` 
 
-```dns
-_tei._tcp.tex.example.com.   3600 IN URI 10 1 “https://www.example.com/transparency“
-_tei._tcp.tex.example.com.   3600 IN URI 20 1 “https://backup.example.com/transparency“
-_tei._tcp.tex.example.com.   3600 IN URI 30 1 “https://thirdparty.example.org/example.com/transparency“
-```
 
-First try lowest priority then move up.
+## Connecting to the API
 
-It is recommended to have a third party external repository as the last priority.
-The URI in DNS does not have to belong to the same domain as the URI records. I.e.
-it is valid for "tex.example.com" to resolve to "thirdparty.example.org".
+When connecting to the `.well-known/tea` URI with the unique identifier
+a HTTP redirect is **required**.
 
-### Finding the Index using DNS result
+The server MUST redirect HTTP requests for that resource
+to the actual "context path" using one of the available mechanisms
+provided by HTTP (e.g., using a 301, 303, or 307 response).  Clients
+MUST handle HTTP redirects on the `.well-known` URI.  Servers MUST
+NOT locate the actual TEA service endpoint at the
+`.well-known` URI as per Section 1.1 of [RFC5785].
+
+### Overview: Finding the Index using DNS result
 
 Append the product part of the TEI to the URI found
 
 - TEI: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
-- DNS record: `_tei._tcp.products.example.com`
-- URI in DNS: `://www.example.com/transparency/`
-- URL: `https://www.example.com/transparency/d4d9f54a-abcf-11ee-ac79-1a52914d44b1/`
-
-If no DNS URI records are found the resolution defaults to A and AAAA records.
-IP address is not valid in the domain name field.
+- DNS record: `products.example.com`
+- URL: `https://products.example.com/.well-known/tea/d4d9f54a-abcf-11ee-ac79-1a52914d44b1/`
+- HTTP 302 redirect to "https://teapot02.consumer.example.com/tea/v2/product-index/d4d9f54a-abcf-11ee-ac79-1a52914d44b1'
 
-Append the URL prefix `/.well-known/tei/` of the TEI to the DNS name found
 Always prefix with the https:// scheme. http (unencrypted) is not valid.
 
 - TEI: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
-- URL: `https://products.example.com/.well-known/tei/d4d9f54a-abcf-11ee-ac79-1a52914d44b1/`
+- URL: `https://products.example.com/.well-known/tea/d4d9f54a-abcf-11ee-ac79-1a52914d44b1/`
 
-**NOTE:** The `/.well-known/tei`names space needs to be registred.
+**NOTE:** The `/.well-known/tea`names space needs to be registred.
 
 ## The TEA Version Index
 
@@ -193,6 +206,5 @@ has many identifiers. The redirect should not lead to a separate web server.
 
 ## References
 
-- [RFC 7553 - THE DNS URI record](https://datatracker.ietf.org/doc/html/rfc7553)
 - [IANA .well-known registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml)
 - [IANA URI registry](https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml#urn-namespaces-1)