Threat Exposure Notification Protocol
draft-yates-threat-exposure-notification-protocol-00

Abstract

This specification defines a protocol for an HTTP- and JSON-based Threat Exposure Notification by outlining how clients upload diagnosis keys, query exposure, revoke diagnosis keys and fetch diagnosis keys from a server.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on November 9, 2020.

Copyright Notice

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

Table of Contents

• 1. Introduction
• 1.1. Notational Conventions
• 1.2. Threat Exposure Notification
• 1.3. Tracking Exposures (Non-Normative)
• 1.4. Diagnosis (Non-Normative)
• 1.5. Terminology
• 2. Protocol Flow
• 3. Threat Exposure Notification Server Metadata
• 3.1. Threat Exposure Notification Server Configuration Document
• 3.2. Obtaining Threat Exposure Notification Server Configuration Document
• 3.2.1. Threat Exposure Notification Server Configuration Request
• 3.2.2. Threat Exposure Notification Server Configuration Response
• 3.2.3. Threat Exposure Notification Server Configuration Validation
• 4. Threat Descriptors
• 4.1. Threat Descriptor Properties
• 5. Assertions
• 6. Uploading Diagnosis Keys
• 6.1. Upload Request
• 6.2. Upload Validation
• 6.3. Upload Response
• 6.4. Upload Error Response
• 7. Querying Exposure
• 7.1. Query Request
• 7.2. Query Validation
• 7.3. Query Response
• 7.4. Query Error Response
• 8. Fetching Diagnosis Keys
• 8.1. Fetch Request
• 8.2. Fetch Validation
• 8.3. Fetch Response
• 8.4. Fetch Error
• 9. Revoking Diagnosis Keys
• 9.1. Revoke Request
• 9.2. Revoke Validation
• 9.3. Revoke Response
• 9.4. Revoke Error
• 10. Security Considerations
• 10.1. Authentication and Authorization
• 10.2. Privacy Considerations
• 10.3. TLS Requirements
• 11. IANA Considerations
• 11.1. Threat Exposure Notification Server Metadata Registry
• 11.1.1. Registration Template
• 11.1.2. Initial Registry Contents
• 11.2. Well-Known URI Registry
• 11.2.1. Registry Contents
• 12. References
• 12.1. Normative References
• 12.2. Informative References
• Appendix A. Configuration Examples (Non-normative)
• A.1. Example Configuration Request
• A.2. Example Configuration Response
• Appendix B. Upload Examples (Non-normative)
• B.1. Example Upload Request
• B.2. Example Upload Successful Response
• B.3. Example Upload Empty Response
• B.4. Example Upload Error Response
• Appendix C. Query Examples (Non-normative)
• C.1. Example Query Request
• C.2. Example Query Response
• C.3. Example Query Error Response
• Appendix D. Fetch Examples (Non-normative)
• D.1. Example Fetch Request
• D.2. Example Fetch Response
• D.3. Example Fetch Error Response
• Appendix E. Revoke Examples (Non-normative)
• E.1. Example Revoke Request
• E.2. Example Revoke Successful Response
• E.3. Example Revoke Empty Response
• E.4. Example Revoke Error Response
• Authors' Addresses

1. Introduction

Contact Tracing is a technique used by public health authorities to measure and contain the spread of infectious diseases ([who]). It requires gathering information from infected individuals about the people they've previously been in contact with. These individuals can then be notified by public health authorities to take appropriate safety measures, such as undertaking self-quarantine and getting tested.

Technology can play an important role in contact tracing efforts. Mobile devices can be used in an automated and scalable way to help determine who has been exposed to a person that later is deemed infectious and sending a notification with instructions on next steps. Health authorities can then use this information to help control the spread of infectious diseases.

For any such technology to work requires sufficient adoption in the population. Concerns about user data privacy and sovereignty may hamper adoption rates. It is therefore imperative that any such solution must include a robust framework for respecting user rights, complying with privacy regulations and protecting sensitive data.

The Threat Exposure Notification Protocol (TENP) is a simple HTTP- and JSON-based protocol for client-server communication of information to determine if a user has been exposed to a threat. It enables clients to upload and query such information from a server in an interoperable, secure, and REST-like manner with support for data privacy.

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] when, and only when, they appear in all capitals, as shown here.

Throughout this document, figures may contain spaces and extra line wrapping to improve readability and accommodate space limitations. Similarly, some URIs contained within examples have been shortened for space and readability reasons (as indicated by "...").

1.2. Threat Exposure Notification

                        Unexposed
                            +
                            |
                            v
                         Exposed
                          +  +
                          |  |
                  +-------+  +----------+
                  |                     |
                  v                     v
              Infected <----------+ Uninfected
               + + +
               | | |
    +----------+ | +---------------+
    |            |                 |
    v            v                 v
Deceased <--+ Diagnosed +----> Recovered

Figure 1: Exposure Flow

Threat Exposure Notification Service includes App, Client, Server, other enabling technologies and authorities.

Threat Exposure Notification App runs on a device operated by a user and leverages the protocol for communication between the Threat Exposure Notification Client it implements and the Threat Exposure Notification Server

User uses or accesses the Threat Exposure Notification Service via an app installed on their device

1.3. Tracking Exposures (Non-Normative)

This protocol does not specify a method by which clients trace potential exposures. Several established approaches exist varying in the underlying data and technology interface used. The two most common data sources used are Bluetooth proximity data, and geo location plus timestamp.

Privacy and security are a major concern and all established approaches ensure Personal Identifiable Information (PII) is protected by leveraging a combination of measures such as only storing such information locally on the client, encrypting information everywhere, and using cryptographically random keys where possible.

1.4. Diagnosis (Non-Normative)

This protocol does not specify a method for testing or diagnosis of a threat nor does it specify a process of authorization to upload diagnosis keys. Several approaches have been suggested elsewhere ranging from self declared to tightly controlled authorization managed by trusted authorities (for example [pact]).

1.5. Terminology

This specification defines the following terms:

Threat Exposure Notification Client

A client that implements this protocol.

Threat Exposure Notification Server

A server that implements this protocol.

Infected

A property of a person denoting that they are affected by a threat (although possibly not diagnosed).

Diagnosis

A property of a person denoting their status with respect to a registered threat based on the outcome of a registered procedure.

Exposure

The act of coming in contact with an infected user.

Threat

A harmful vector, contagion, infectious disease, or other concern for authorities.

Key

Keys belong to a device or app, that belong to a user.

Diagnosis Keys

Keys belonging to a device or app, that belongs to a diagnosed infected user.

Potential Exposure Keys

Keys belonging to other users (their device or app), with which a user have come in contact with.

2. Protocol Flow

+----------+                   +----------+
|          |                   |          |
|          |                   |          |
|          |--(A)- METADATA -->|          |
|          |--(B)- UPLOAD ---->|          |
|  Client  |--(C)- QUERY ----->|  Server  |
|          |--(D)- FETCH ----->|          |
|          |--(E)- REVOKE ---->|          |
|          |                   |          |
|          |                   |          |
+----------+                   +----------+
                

Figure 2: Abstract Protocol Flow

• (A) A client obtains the Threat Exposure Notification Server Configuration Document from server(s).
• (B) A client uploads diagnosed keys to server(s).
• (C) A client queries exposure from server(s).
• (D) A client fetches diagnosed keys from server(s).
• (E) A client revokes access to diagnosed keys from server(s).

3. Threat Exposure Notification Server Metadata

3.1. Threat Exposure Notification Server Configuration Document

A server MUST host a Threat Exposure Notification Server Configuration Document describing its configuration. The following server metadata values are used by this specification and are registered in the IANA "Threat Exposure Notification Servers Metadata" registry established in Section 11.1:

supports_query

REQUIRED. Boolean value indicating whether the server supports the Query operation.

query_endpoint

RECOMMENDED. URL of the server's Query endpoint.

supports_upload

REQUIRED. Boolean value indicating whether the server supports the Upload operation.

upload_endpoint

RECOMMENDED. URL of the server's Upload endpoint.

supports_fetch

REQUIRED. Boolean value indicating whether the server supports the Fetch operation.

fetch_endpoint

RECOMMENDED. URL of the server's Fetch endpoint.

supports_revoke

REQUIRED. Boolean value indicating whether the server supports the Revoke operation.

revoke_endpoint

RECOMMENDED. URL of the server's Revoke endpoint.

threats_supported

REQUIRED. An array of strings of the threats the server supports. Section 4

keys_supported

REQUIRED. An array of strings of the keys the server supports.

assertions_supported

RECOMMENDED. An array of strings of the Assertions the server supports.

Clients that do not recognize Metadata values SHALL ignore them and not generate an error.

3.2. Obtaining Threat Exposure Notification Server Configuration Document

Servers MUST make a JSON document [RFC8259] available at the path /.well-known/threat-exposure-configuration. The syntax and semantics of .well-known are defined in [RFC8615].

threat-exposure-configuration MUST point to a JSON document [RFC8259] compliant with this specification and MUST be returned using the application/json content type.

The well-known URI path suffix used MUST be registered in the IANA "Well-Known URIs" registry [IANA.well-known].

3.2.1. Threat Exposure Notification Server Configuration Request

A Threat Exposure Notification Server Configuration Document MUST be queried using an HTTP GET request at the previously specified path.

3.2.2. Threat Exposure Notification Server Configuration Response

The response is a JSON object [RFC8259] containing a set of claims about the server's configuration, including all necessary endpoints and supported information. A successful response MUST use the 200 OK HTTP status code and return a JSON object [RFC8259] using the application/json content type that contains a set of claims as its members that are a subset of the Metadata values defined in Section 3.

Other claims MAY also be returned and clients MUST ignore any claims not recognized.

Clients SHOULD follow redirected requests.

Claims that return multiple values are represented as JSON arrays.

Claims with zero elements MUST be omitted from the response.

An error response uses the applicable HTTP status code value.

3.2.3. Threat Exposure Notification Server Configuration Validation

If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used.

4. Threat Descriptors

This section describes a JSON document [RFC8259] format for describing threats. The format is based on the JRD document format specified in [RFC6415].

4.1. Threat Descriptor Properties

A Threat Descriptor has the following properties:

https://tenprotocol.org/props/threat/name

REQUIRED. The name of the threat.

https://tenprotocol.org/props/threat/description

REQUIRED. A short description of the threat.

https://tenprotocol.org/props/threat/symptoms

RECOMMENDED. A comma-separated list of string labels that describe symptoms of the threat.

5. Assertions

Assertions can be attached to Requests to provide additional information about the request. The key of an Assertion is a URI. Clients MUST NOT attempt to fetch the fetch the resource specified by the URI. New Assertions can be created by specifying new URI's. The specifier MUST control the URI space.

6. Uploading Diagnosis Keys

The client MAY upload to the server the diagnosis keys associated to a diagnosis of a threat.

The specification for how a client establishes connections to servers is covered in Section 3.2.

Information about the diagnosis, client, individual or scope can be attached to the upload using Assertions Section 5.

6.1. Upload Request

The client SHOULD retrieve the request URI from the Threat Exposure Notification Server Configuration Document as defined in Section 3.2.

The request object is a JSON object [RFC8259] with the following properties:

key_type

REQUIRED. A URI of a key type.

keys

REQUIRED. An array of strings representing the diagnosis keys for that key type.

diagnosis

REQUIRED. An object providing information about the diagnosis of a threat. It has the following properties:

threat

REQUIRED. A URI of a threat that has been diagnosed, as specified in Section 4.

diagnosed

REQUIRED. The time when the diagnosis was made formatted as specified in [RFC3339] with no time zone offset.

assertions

OPTIONAL. An object providing additional assertions related to the upload, diagnosis, individual or scope. The key is an Assertion defined as per Section 5. The client MUST ignore any assertions it does not recognize.

6.2. Upload Validation

The server SHOULD validate the request, including ensuring e.g., that the key_type is supported, threat is supported and diagnosed is a properly formatted time [RFC3339] occurring in the past.

The following Problem Detail Types [RFC7807] are defined for validation:

https://tenprotocol.org/errors/keys-required

The keys property is missing or is not an object or the value of one of the keys is not an array.

https://tenprotocol.org/errors/key-not-supported

One of the keys specified in the keys property is not supported by the server.

https://tenprotocol.org/errors/diagnosis-required

The diagnosis property is missing or is not an object.

https://tenprotocol.org/errors/threat-required

The threat property is missing or is not a string.

https://tenprotocol.org/errors/threat-not-supported

The threat specified in the threat property is not supported by the server.

https://tenprotocol.org/errors/diagnosed-required

The diagnosed property is missing or is not a string.

https://tenprotocol.org/errors/diagnosed-invalid

The diagnosed property is invalid.

6.3. Upload Response

If the server has validated the request and accepted the upload, the server will return either a 200 OK or 204 No Content response code. Clients MUST support either response as a successful upload.

6.4. Upload Error Response

If the request was not validated properly, the server MUST return a 400 Bad Request error response with a Problem Details Object [RFC7807] containing at least the type, status and detail as specified in [RFC7807].

7. Querying Exposure

A client MAY query a server to determine exposure to a threat.

The specification for how a client establishes connections to servers is covered in Section 3.2.

Information about the diagnosis, client, individual or scope can be attached to the upload using Assertions Section 5.

7.1. Query Request

The client SHOULD retrieve the request URI from the Threat Exposure Notification Server Configuration Document as defined in Section 3.2.

The request object is a JSON object [RFC8259] with the following properties:

key_type

REQUIRED. A URI of a key type.

keys

REQUIRED. An array of strings representing the potential exposure keys for that key type.

after

OPTIONAL. A time to search for diagnosis keys uploaded after, formatted as specified in [RFC3339] with no time zone offset. If omitted, the server SHOULD provide a reasonable default based on the specified threats. Searches SHOULD be done exclusive of this time.

before

OPTIONAL. A time to search for diagnosis keys uploaded up to and before, formatted as specified in [RFC3339] with no time zone offset. If omitted, the server SHOULD use latest. Searches SHOULD be done inclusive of this time.

threat

REQUIRED. A threat URI as defined in Section 4 specifying which threat to check for exposure.

assertions

OPTIONAL. An object providing additional assertions related to the upload, diagnosis, individual or scope. The key is an Assertion defined as per Section 5. The client MUST ignore any assertions it does not recognize.

7.2. Query Validation

The server SHOULD validate the request, including ensuring e.g., that the key is supported, threat is supported, and so on.

The following Problem Detail Types [RFC7807] are defined for validation:

https://tenprotocol.org/errors/keys-required

The keys property is missing or is not an array of strings.

https://tenprotocol.org/errors/key-not-supported

The key type specified in the key_type property is not supported by the server.

https://tenprotocol.org/errors/threats-required

The threat property is missing or is not a string.

https://tenprotocol.org/errors/threat-not-supported

The threat specified in the threat property is not supported by the server.

https://tenprotocol.org/errors/before-invalid

The before property is invalid.

https://tenprotocol.org/errors/after-invalid

The after property is invalid.

https://tenprotocol.org/errors/before-after-invalid

The before property denotes a time prior to the one denoted in the after property.

7.3. Query Response

If the server has validated the request and accepted the query, the server will return a 200 OK response with a Content-Type header equal to application/json.

The request object is a JSON object [RFC8259] with the following properties:

key_type

REQUIRED. A URI of a key type.

exposed

REQUIRED. A boolean denoting whether an exposure to the threat has been flagged.

exposures

OPTIONAL. An array of days when exposures happened formatted as per [RFC3339] without a time component.

before

REQUIRED. The time of the most recent upload across all diagnosis keys considered. This MAY be used in a subsequent query as "after" to page through results.

after

OPTIONAL. The time of the the oldest upload across all diagnosis keys considered.

threat

REQUIRED. A threat URI as defined in Section 4 specifying which threat to check for exposure.

message

A human-readable message to be displayed to the user.

links

A list of WebLinks for more information ( [RFC7033] [RFC8288]).

7.4. Query Error Response

If the request was not validated properly, the server MUST return a 400 Bad Request error response with a Problem Details Object [RFC7807] containing at least the type, status and detail as specified in [RFC7807].

8. Fetching Diagnosis Keys

A client MAY ask to remove diagnosis keys it previously uploaded to a server.

The specification for how a client establishes connections to servers is covered in Section 3.2.

Information about the diagnosis, client, individual or scope can be attached to the upload using Assertions Section 5.

8.1. Fetch Request

The client SHOULD retrieve the request URI from the Threat Exposure Notification Server Configuration Document as defined in Section 3.2.

The request object is a JSON object [RFC8259] with the following properties:

key_type

REQUIRED. A URI of a key type.

after

OPTIONAL. A time to fetch for diagnosis keys uploaded after, formatted as specified in [RFC3339] with no time zone offset. If omitted, the server SHOULD provide a reasonable default based on the specified threats. Searches SHOULD bedone exclusive of this time.

before

OPTIONAL. A time to fetch for diagnosis keys uploaded before, formatted as specified in [RFC3339] with no time zone offset. If omitted, the server SHOULD use latest. Searches SHOULD be done inclusive of this time.

threat

REQUIRED. Array of strings specifying which threats to check for exposure to Section 4.

assertions

OPTIONAL. An object providing additional assertions related to the upload, diagnosis, individual or scope. The key is an Assertion defined as per Section 5. The client MUST ignore any assertions it does not recognize.

8.2. Fetch Validation

The server SHOULD validate the request, including ensuring e.g., that the keys are supported, threats are supported, and so on.

The following Problem Detail Types [RFC7807] are defined for validation:

https://tenprotocol.org/errors/key-not-supported

The key type specified in the key_type property is not supported by the server.

https://tenprotocol.org/errors/threats-required

The threat property is missing or is not a string.

https://tenprotocol.org/errors/threat-not-supported

The threat specified in the threat property is not supported by the server.

https://tenprotocol.org/errors/before-invalid

The before property is invalid.

https://tenprotocol.org/errors/after-invalid

The after property is invalid.

https://tenprotocol.org/errors/before-after-invalid

The before property denotes a time prior to the one denoted in the after property.

8.3. Fetch Response

If the server has validated the request and accepted the fetch, the server will return a 200 OK response with a Content-Type header equal to application/json.

The client and server SHOULD support Chunked Transfer Encoding [RFC7230] as the resulting response entity may be large.

The request object is a JSON object [RFC8259] with the following properties:

key_type

REQUIRED. A URI of a key type.

keys

REQUIRED. An array of URI's for the requested key types.

before

REQUIRED. The time of the most recent upload across all diagnosis keys considered. This MAY be used in subsequent fetch requests to page through results.

after

OPTIONAL. The time of the the oldest upload across all diagnosis keys considered.

threat

REQUIRED. Array of strings specifying which threats to check for exposure to Section 4.

8.4. Fetch Error

If the request was not validated properly, the server MUST return a 400 Bad Request error response with a Problem Details Object [RFC7807] containing at least the type, status and detail as specified in [RFC7807].

9. Revoking Diagnosis Keys

A client MAY ask to remove diagnosis keys it previously uploaded to a server.

The specification for how a client establishes connections to servers is covered in Section 3.2.

Information about the diagnosis, client, individual or scope can be attached to the upload using assertions Section 5.

9.1. Revoke Request

The client SHOULD retrieve the request URI from the Threat Exposure Notification Server Configuration Document as defined in Section 3.2.

The request object is a JSON object [RFC8259] with the following properties:

key_type

REQUIRED. A URI of a key type.

keys

REQUIRED. An array of URI's for the requested key types.

assertions

OPTIONAL. An object providing additional assertions related to the upload, diagnosis, individual or scope. The key is an Assertion defined as per Section 5. The client MUST ignore any assertions it does not recognize.

9.2. Revoke Validation

The server SHOULD validate the request, including ensuring e.g., that the keys is supported.

The following Problem Detail Types [RFC7807] are defined for validation:

https://tenprotocol.org/errors/keys-required

The keys property is missing or is not an array.

https://tenprotocol.org/errors/key-not-supported

The key type specified in the key_type property is not supported by the server.

9.3. Revoke Response

If the server has validated the request and accepted the upload, the server will return either a 200 OK or 204 No Content response code. Clients MUST support either response as a successful upload.

9.4. Revoke Error

If the request was not validated properly, the server MUST return a 400 Bad Request error response with a Problem Details Object [RFC7807] containing at least the type, status and detail as specified in [RFC7807].

10. Security Considerations

10.1. Authentication and Authorization

This specification does not specify a method for authorizing calls to the server. Calls to the endpoints may even be unauthenticated, depending on the server configuration.

10.2. Privacy Considerations

While the Assertions mechanism allows the requests to be augmented, it is up to the client and server to ensure that any assertions provided to not expose any personally identifiable information (PII).

10.3. TLS Requirements

Implementations MUST support TLS. Which version(s) ought to be implemented will vary over time and depend on the widespread deployment and known security vulnerabilities at the time of implementation. The authorization server MUST support TLS version 1.2 [RFC5246] and MAY support additional TLS mechanisms meeting its security requirements. When using TLS, the client MUST perform a TLS/SSL server certificate check, per [RFC6125]. Implementation security considerations can be found in "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [RFC7525].

To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection.

11. IANA Considerations

The following registration procedure is used for the registry established by this specification.

Values are registered on a Specification Required [RFC8126] basis after a two-week review period on the tenp-ext-review@tenprotocol.org mailing list, on the advice of one or more Designated Experts. However, to allow for the allocation of values prior to publication, the Designated Experts may approve registration once they are satisfied that such a specification will be published.

Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register Threat Exposure Notification Server Metadata: example").

Within the review period, the Designated Experts will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. Registration requests that are undetermined for a period longer than 21 days can be brought to the IESG's attention (using the iesg@ietf.org mailing list) for resolution.

Criteria that should be applied by the Designated Experts include determining whether the proposed registration duplicates existing functionality, determining whether it is likely to be of general applicability or whether it is useful only for a single application, and whether the registration makes sense.

IANA must only accept registry updates from the Designated Experts and should direct all requests for registration to the review mailing list.

It is suggested that multiple Designated Experts be appointed who are able to represent the perspectives of different applications using this specification, in order to enable broadly-informed review of registration decisions. In cases where a registration decision could be perceived as creating a conflict of interest for a particular Designated Expert, that Designated Expert should defer to the judgment of the other Designated Experts.

11.1. Threat Exposure Notification Server Metadata Registry

This specification establishes the IANA "Threat Exposure Notification Server Metadata" registry for Threat Exposure Notification Server metadata names. The registry records the Threat Exposure Notification Server metadata member and a reference to the specification that defines it.

The Designated Experts must either:

(a) require that metadata names and values being registered use only printable ASCII characters excluding double quote ('"') and backslash ('\') (the Unicode characters with code points U+0021, U+0023 through U+005B, and U+005D through U+007E), or

(b) if new metadata members or values are defined that use other code points, require that their definitions specify the exact sequences of Unicode code points used to represent them. Furthermore, proposed registrations that use Unicode code points that can only be represented in JSON strings as escaped characters must not be accepted.

11.1.1. Registration Template

Metadata Name:

The name requested (e.g., "query_endpoint"). This name is case-sensitive. Names may not match other registered names in a case-insensitive manner (one that would cause a match if the Unicode toLowerCase() operation were applied to both strings) unless the Designated Experts state that there is a compelling reason to allow an exception.

Metadata Description:

Brief description of the metadata (e.g., "Query Endpoint URL").

Metadata Type:

Description of the metadata type (e.g., string, boolean, number) and whether multiple values are expected (e.g., array of strings, array of numbers).

Change Controller:

For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included.

Specification Document(s):

Reference to the document or documents that specify the parameter, preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required.

11.1.2. Initial Registry Contents

• Metadata Name: supports_query
• Metadata Type: boolean
• Metadata Description: Value indicating whether the server supports the Query operation.
• Change Controller: tenp-ext-review@tenprotocol.org
• Specification Document(s): Section 3 of this specification.

• Metadata Name: query_endpoint
• Metadata Type: string
• Metadata Description: URL of the server's Query endpoint.
• Change Controller: tenp-ext-review@tenprotocol.org
• Specification Document(s): Section 3 of this specification.

• Metadata Name: supports_upload
• Metadata Type: boolean
• Metadata Description: Value indicating whether the server supports the Upload operation.
• Change Controller: tenp-ext-review@tenprotocol.org
• Specification Document(s): Section 3 of this specification.

• Metadata Name: upload_endpoint
• Metadata Type: string
• Metadata Description: URL of the server"s Upload endpoint.
• Change Controller: tenp-ext-review@tenprotocol.org
• Specification Document(s): Section 3 of this specification.

• Metadata Name: keys_supported
• Metadata Type: array of string
• Metadata Description: Array of strings of URI's that designated which keys are supported.
• Change Controller: tenp-ext-review@tenprotocol.org
• Specification Document(s): Section 3 of this specification.

• Metadata Name: threats_supported
• Metadata Type: array of string
• Metadata Description: Array of strings of Threat Descriptors Section 4.
• Change Controller: tenp-ext-review@tenprotocol.org
• Specification Document(s): Section 3 of this specification.

11.2. Well-Known URI Registry

This specification registers the well-known URI defined in Section 3.2 in the IANA Well-Known URI registry defined in [RFC8615].

11.2.1. Registry Contents

• URI suffix: threat-exposure-configuration
• Change controller: IESG
• Specification document: Section 3.2 of this specification.
• Related information: (none)

12. References

12.1. Normative References

12.2. Informative References

Appendix A. Configuration Examples (Non-normative)

A.1. Example Configuration Request

GET /.well-known/threat-exposure-configuration HTTP/1.1
Accept: application/json
Host: example.com
                        

The client would make the following request to the server https://example.com to obtain its Configuration document:

A.2. Example Configuration Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "supports_query": true,
  "query_endpoint": "https://server.example.com/query",
  "supports_upload": true,
  "upload_endpoint": "https://server.example.com/upload",
  "keys_supported": ["https://tenprotocol.org/keys/btle"],
  "threats_supported": ["https://tenprotocol.org/threats/covid19"],
  "assertions_supported": ["https://tenprotocol.org/assertions/
    geo/country/1.0", "https://tenprotocol.org/assertions/geo/
    state/1.0"]
}
                        

The following is a non-normative example response:

Appendix B. Upload Examples (Non-normative)

B.1. Example Upload Request

POST /threat-exposure/upload HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
    "key_type" : "https://tenprotocol.org/keys/btle",
    "keys": [
        "1478E46F897749C691A28351F0B054F1",
        "20A7412C65A046DCB5538D7DA45A6B5D",
        "24BFE7A43563495BA36C79A96617A602",
        "371108A73B964915A62D81E49A783F85",
        "4075DB637A914896B5459EF3E377AF0D",
        "5F51F91099B84C9685CD268941A3DEEC",
        "67684C56F9A6407A99DB57E6B871EC1D",
        "AA0817D30C64407CB4F5DE1425336922",
        "CFC046DEF50244D58CA58A0AD7FED287",
        "D555096A727C49FEADD03488154E6152",
        "E48A37FB87924885AD6879857DC297B2"
    ],
    "diagnosis": {
        "threat": "https://tenprotocol.org/threats/diseases/covid19",
        "diagnosed": "2020-05-01T01:23:45"
    },
    "assertions": {
        "https://tenprotocol.org/assertions/geo/country/1.0": ["US"],
        "https://tenprotocol.org/assertions/geo/state/1.0": ["CA"]
    }
}
                        

B.2. Example Upload Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{}
                        

B.3. Example Upload Empty Response

HTTP/1.1 204 No Content
                        

B.4. Example Upload Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://tenprotocol.org/errors/key-not-supported",
    "status": "400",
    "detail": "The specified key is not supported."
}
                        

Appendix C. Query Examples (Non-normative)

C.1. Example Query Request

POST /threat-exposure/query HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
    "key_type" : "https://tenprotocol.org/keys/btle",
    "keys": [
        "1478E46F897749C691A28351F0B054F1",
        "20A7412C65A046DCB5538D7DA45A6B5D",
        "24BFE7A43563495BA36C79A96617A602",
        "371108A73B964915A62D81E49A783F85",
        "4075DB637A914896B5459EF3E377AF0D",
        "5F51F91099B84C9685CD268941A3DEEC",
        "67684C56F9A6407A99DB57E6B871EC1D",
        "AA0817D30C64407CB4F5DE1425336922",
        "CFC046DEF50244D58CA58A0AD7FED287",
        "D555096A727C49FEADD03488154E6152",
        "E48A37FB87924885AD6879857DC297B2"
    ],
    "after": "2020-04-01T01:23:45",
    "threat": "https://tenprotocol.org/threats/diseases/covid19",
    "assertions": {
        "https://tenprotocol.org/assertions/geo/country/1.0": ["US"],
        "https://tenprotocol.org/assertions/geo/state/1.0": ["CA"]
    }
}
                        

C.2. Example Query Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en

{
    "key_type" : "https://tenprotocol.org/keys/btle",
    "exposed": true,
    "exposures": ["2020-04-20"],
    "before": "2020-05-01T02:13:42",
    "threat": "https://tenprotocol.org/threats/diseases/covid19",
    "message": "You were exposed to COVID-19 on April 20th 2020.
       Please contact your local health authority.",
    "links": [
        {
            "href": "http://somehealth.org/covid19.html",
            "rel": "details"
        },
        {
            "href": "http://somehealth.org/privacy-policy.html",
            "rel": "privacy"
        },
    ]
}
                        

C.3. Example Query Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://tenprotocol.org/errors/key-not-supported",
    "status": "400",
    "detail": "The specified key is not supported."
}
                        

Appendix D. Fetch Examples (Non-normative)

D.1. Example Fetch Request

POST /threat-exposure/fetch HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
    "key_type": "https://tenprotocol.org/keys/btle",
    "after": "2020-04-01T00:00:00",
    "threat": "https://tenprotocol.org/threats/diseases/covid19",
    "assertions": {
        "https://tenprotocol.org/assertions/geo/country/1.0": ["US"],
        "https://tenprotocol.org/assertions/geo/state/1.0": ["CA"]
    }
}
                        

D.2. Example Fetch Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en

{
    "key_type" : "https://tenprotocol.org/keys/btle",
    "keys": [
        "1478E46F897749C691A28351F0B054F1",
        "20A7412C65A046DCB5538D7DA45A6B5D",
        "24BFE7A43563495BA36C79A96617A602",
        "371108A73B964915A62D81E49A783F85",
        "4075DB637A914896B5459EF3E377AF0D",
        "5F51F91099B84C9685CD268941A3DEEC",
        "67684C56F9A6407A99DB57E6B871EC1D",
        "AA0817D30C64407CB4F5DE1425336922",
        "CFC046DEF50244D58CA58A0AD7FED287",
        "D555096A727C49FEADD03488154E6152",
        "E48A37FB87924885AD6879857DC297B2"
    ],
    "before": "2020-08-01T02:22:10",
    "threat": "https://tenprotocol.org/threats/diseases/covid19",
}
                        

D.3. Example Fetch Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://tenprotocol.org/errors/key-not-supported",
    "status": "400",
    "detail": "The specified key is not supported."
}
                        

Appendix E. Revoke Examples (Non-normative)

E.1. Example Revoke Request

DELETE /threat-exposure/revoke HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
    "key_type" : "https://tenprotocol.org/keys/btle",
    "keys": [
        "1478E46F897749C691A28351F0B054F1",
        "20A7412C65A046DCB5538D7DA45A6B5D",
        "24BFE7A43563495BA36C79A96617A602",
        "371108A73B964915A62D81E49A783F85",
        "4075DB637A914896B5459EF3E377AF0D",
        "5F51F91099B84C9685CD268941A3DEEC",
        "67684C56F9A6407A99DB57E6B871EC1D",
        "AA0817D30C64407CB4F5DE1425336922",
        "CFC046DEF50244D58CA58A0AD7FED287",
        "D555096A727C49FEADD03488154E6152",
        "E48A37FB87924885AD6879857DC297B2"
    ],
    "assertions": {
        "https://tenprotocol.org/assertions/geo/country/1.0": ["US"],
        "https://tenprotocol.org/assertions/geo/state/1.0": ["CA"]
    }
}
                        

E.2. Example Revoke Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{}
                        

E.3. Example Revoke Empty Response

HTTP/1.1 204 No Content
                        

E.4. Example Revoke Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://tenprotocol.org/errors/key-not-supported",
    "status": "400",
    "detail": "The specified key is not supported."
}
                        

Authors' Addresses