From c1abdcd335597e789c469081529a8dbd303bb83b Mon Sep 17 00:00:00 2001 From: Paul Horton Date: Wed, 6 Nov 2024 16:06:15 +0000 Subject: [PATCH 1/5] Updated discovery/readme Update to consistently refer to the final portion of the TEI as `unique-identifier`. Signed-off-by: Paul Horton --- discovery/readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index 4ce3cc8..4c4c9a2 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -47,7 +47,7 @@ bar code and one with the vendor's product number. ``` -urn:tei::: +urn:tei::: ```` **Note**: this requires a registration of the TEI URN schema with IANA. @@ -114,7 +114,7 @@ The name part of the TEI is used in a DNS query to find one or multiple location At the URL we need a well-known name space to find out more - `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1` -- Syntax: `urn:tei:uuid::` +- Syntax: `urn:tei:uuid::` 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`. From 32387114fbba213ff1e9d9eb4b33ee6e8c6eea07 Mon Sep 17 00:00:00 2001 From: Paul Horton Date: Thu, 7 Nov 2024 12:51:36 +0000 Subject: [PATCH 2/5] doc: added TEI examples (for discussion) and made clearer that `unique-identifier` is required to be unique only within the `domain-name` scope Signed-off-by: Paul Horton --- discovery/readme.md | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index 4c4c9a2..86be57a 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -34,20 +34,19 @@ 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). -- 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. Recommendation is to use UUID, - but it can be an existing article code too. +- 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). + - 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 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 bar code and one with the vendor's product number. ### TEI syntax - ``` -urn:tei::: +urn:tei::: ```` **Note**: this requires a registration of the TEI URN schema with IANA. @@ -60,44 +59,64 @@ urn:tei::: ### TEI types +The below show examples of TEI where the types are specific known formats or types. + +Reminder: the `unique-identifer` component of the TEI needs only be unique within the `domain-name`. + #### PURL - Package URL +Where the `unique-identifier` is a PURL in it's canonical string form. + Syntax: ```text -urn:tei:purl:: +urn:tei:purl:: ```` +Example: +```text +urn:tei:org.cyclonedx:pkg:pypi/cyclonedx-python-lib@8.4.0?extension=whl&qualifier=py3-none-any +``` + #### SWID +Where the `unique-identifier` is a SWID. + Syntax: ```text -urn:tei:swid:: +urn:tei:swid:: ```` Note that there is a TEI SWID type as well as a PURL SWID type. #### HASH -Supports the following hash values: +Where the `unique-identifier` is a Hash. Supports the following hash types: * SHA256 * SHA384 * SHA512 ```text -urn:tei:hash::: +urn:tei:hash::: ```` +Example: +```text +urn:tei:org.cyclonedx:SAH256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9 +``` + The origin of the hash is up to the vendor to define. #### UUID +Where the `unique-identifier` is a UUID. + Syntax: ```text -urn:tei:uuid:: +urn:tei:uuid:: ```` Has to be a valid UUID. From 5449239a9c19f5ac2f2dcb13cc46da88be64c0f2 Mon Sep 17 00:00:00 2001 From: Paul Horton Date: Thu, 7 Nov 2024 13:43:52 +0000 Subject: [PATCH 3/5] doc: clarification around `unique-identifier` Signed-off-by: Paul Horton --- discovery/readme.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index 86be57a..f137b83 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -35,10 +35,9 @@ The TEI can be shown in the software itself, in shipping documentation, in web p 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). - - 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 UUID, but it can be an existing article code too. +- The **`domain-name`** part does not have to exist as a web server (HTTPS) + - 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` - see [TEI Types](#tei-types) A TEI belongs to a single product. A product can have multiple TEIs - like one with a EAN bar code and one with the vendor's product number. From 7cf2e563b2fc6fbb6b8c99679d6545bed68fbcf8 Mon Sep 17 00:00:00 2001 From: Paul Horton Date: Thu, 7 Nov 2024 13:44:50 +0000 Subject: [PATCH 4/5] corrected type Signed-off-by: Paul Horton --- discovery/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/discovery/readme.md b/discovery/readme.md index f137b83..02aa441 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -103,7 +103,7 @@ urn:tei:hash::: Example: ```text -urn:tei:org.cyclonedx:SAH256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9 +urn:tei:org.cyclonedx:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9 ``` The origin of the hash is up to the vendor to define. From 38fb8598bdd9ec32da14c15705b96f2d0196e726 Mon Sep 17 00:00:00 2001 From: Paul Horton Date: Wed, 13 Nov 2024 10:38:04 +0000 Subject: [PATCH 5/5] doc: drafted changes to move from `URL` to `SVCB` DNS records Signed-off-by: Paul Horton --- discovery/readme.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index 02aa441..63e7d1c 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -2,6 +2,17 @@ **NOTE**: _This is a proposal for the WG_ +- [From product identifier to API endpoint](#from-product-identifier-to-api-endpoint) +- [TEA Discovery - defining an extensible identifier](#tea-discovery---defining-an-extensible-identifier) +- [The TEI URN: An extensible identifier](#the-tei-urn-an-extensible-identifier) + - [TEI syntax](#tei-syntax) + - [TEI types](#tei-types) + - [TEI resolution using DNS](#tei-resolution-using-dns) + - [Finding the Index using DNS result](#finding-the-index-using-dns-result) +- [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. @@ -19,11 +30,8 @@ TEA discovery is the process where a user with a product identifier can discover 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 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 @@ -35,12 +43,12 @@ The TEI can be shown in the software itself, in shipping documentation, in web p 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) - - 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` - see [TEI Types](#tei-types) +- 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 -bar code and one with the vendor's product number. +barcode and one with the vendor's product number. ### TEI syntax @@ -48,13 +56,7 @@ bar code and one with the vendor's product number. urn:tei::: ```` -**Note**: this requires a registration of the TEI URN schema with IANA. - -### TEI examples - -- `urn:tei:uuid:` for a company specific name and product identifier as UUID -- Example: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1` -- Syntax: `urn:tei:uuid::` +**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 @@ -103,7 +105,7 @@ urn:tei:hash::: Example: ```text -urn:tei:org.cyclonedx:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9 +urn:tei:cyclonedx.org:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9 ``` The origin of the hash is up to the vendor to define. @@ -126,13 +128,14 @@ Has to be a valid UUID. - 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 - `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1` -- Syntax: `urn:tei:uuid::` +- Syntax: `urn:tei:uuid::` 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`. @@ -164,7 +167,7 @@ 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: `https://www.example.com/transparency/` +- 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.