Published

OGC Engineering Report

Testbed-18: Secure Asynchronous Catalog Engineering Report
Yves Coene Editor Christophe Noel Editor
OGC Engineering Report

Published

Document number:22-018
Document type:OGC Engineering Report
Document subtype:
Document stage:Published
Document language:English

License Agreement

Use of this document is subject to the license agreement at https://www.ogc.org/license


I.  Executive Summary

This OGC Testbed-18 Engineering Report (ER) describes the results of the Secure, Asynchronous Catalogs Task in the Testbed-18 Catalogs, Filtering, and Moving Features (CMF) thread. This task explored the following.

The Engineering Report assumes that the reader has some familiarity with OGC CSW, ISO19115 and the draft OGC API-Records Standards. It summarizes the options investigated and describes in detail the following main achievements.

A major result of the activity is the genericity of the proposed solutions. Both the Data Centric Security and the asynchronous communication via subscription models apply equally well to other API, including other OGC (JSON) API or other catalog API including OpenSearch or SpatioTemporal Asset Catalogs (STAC) or other JSON(-LD)-based metadata encodings including GeoDCAT-AP, “OGC EO Dataset Metadata GeoJSON(-LD) Encoding Standard” OGC 17-003r2, “EO Collection GeoJSON(-LD) Encoding” OGC 17-084r1, Service metadata as per OGC 19-020r1, STAC Collection Specification and STAC Item Specification.

During the activity, several areas requiring further work were identified, which are documented in a Future Work chapter of the Engineering Report. The proposed future work items include the following.

II.  Keywords

The following are keywords to be used by search engines and document catalogues.

OGC, API-Records, Catalog, CSW, DCS, ISO-19115, security, web service

III.  Security considerations

No security considerations have been made for this document.

IV.  Submitting Organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

V.  Submitters

All questions regarding this submission should be directed to the editor or the submitters:

Name Affiliation Role
Yves Coene Spacebel s.a. Editor
Christophe Noël Spacebel s.a. Editor
Andreas Matheus Secure Dimensions GmbH Contributor
Eugene Yu George Mason University Contributor
Li Lin George Mason University Contributor
Philip Hawkins Helyx Contributor
Bart Cosyn agentschap Digitaal Vlaanderen Contributor
Loes Deventer agentschap Digitaal Vlaanderen Contributor
Geraldine Nolf agentschap Digitaal Vlaanderen Contributor

VI.  Abstract

This OGC Testbed-18 Engineering Report (ER) describes the results of the Secure, Asynchronous Catalogs Task in the Testbed-18 Catalogs, Filtering, and Moving Features (CMF) thread. This task explored the following.

Testbed-18: Secure Asynchronous Catalog Engineering Report

1.  Scope

This is the OGC Testbed-18 Engineering Report (ER) documenting the results of the Secure, Asynchronous Catalogs Task. It describes the following.

Secure, asynchronous catalogs are contributions to open science environments. Such catalogs help address challenges created by more and more data becoming available and the corresponding complexity of discovery and binding.

This Testbed-18 Engineering Report covers contributions in the following areas.

2.  Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

Open API Initiative: OpenAPI Specification 3.0.2, 2018 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee: IETF RFC 2616, Hypertext Transfer Protocol — HTTP/1.1. RFC Publisher (1999). https://www.rfc-editor.org/info/rfc2616.

A.B. Roach: IETF RFC 5989, A SIP Event Package for Subscribing to Changes to an HTTP Resource. RFC Publisher (2010). https://www.rfc-editor.org/info/rfc5989.

M. Nottingham: IETF RFC 8288, Web Linking. RFC Publisher (2017). https://www.rfc-editor.org/info/rfc8288.

J. Snell: IETF RFC 7240, Prefer Header for HTTP. RFC Publisher (2014). https://www.rfc-editor.org/info/rfc7240.

M. Jones, J. Bradley, N. Sakimura: IETF RFC 7515, JSON Web Signature (JWS). RFC Publisher (2015). https://www.rfc-editor.org/info/rfc7515.

M. Jones, J. Hildebrand: IETF RFC 7516, JSON Web Encryption (JWE). RFC Publisher (2015). https://www.rfc-editor.org/info/rfc7516.

M. Jones: IETF RFC 7517, JSON Web Key (JWK). RFC Publisher (2015). https://www.rfc-editor.org/info/rfc7517.

M. Jones, J. Bradley, N. Sakimura: IETF RFC 7519, JSON Web Token (JWT). RFC Publisher (2015). https://www.rfc-editor.org/info/rfc7519.

M. Jones: IETF RFC 7797, JSON Web Signature (JWS) Unencoded Payload Option. RFC Publisher (2016). https://www.rfc-editor.org/info/rfc7797.

M. Jones, J. Bradley, H. Tschofenig: IETF RFC 7800, Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs). RFC Publisher (2016). https://www.rfc-editor.org/info/rfc7800.

H. Butler, M. Daly, A. Doyle, S. Gillies, S. Hagen, T. Schaub: IETF RFC 7946, The GeoJSON Format. RFC Publisher (2016). https://www.rfc-editor.org/info/rfc7946.

A. Rundgren, B. Jordan, S. Erdtman: IETF RFC 8785, JSON Canonicalization Scheme (JCS). RFC Publisher (2020). https://www.rfc-editor.org/info/rfc8785.

Kellog G., Champin P., Longley D. : W3C JSON-LD 1.1, A JSON-based Serialization for Linked Data, W3C Recommendation 16 July 2020 https://www.w3.org/TR/json-ld11/

CEOS: CEOS-OPENSEARCH-BP-V1.3, CEOS OpenSearch Best Practice Document, Version 1.3 https://ceos.org/document_management/Working_Groups/WGISS/Documents/WGISS%20Best%20Practices/CEOS%20OpenSearch%20Best%20Practice.pdf

SEMIC: GeoDCAT-AP — Version 2.0.0, A geospatial extension for the DCAT application profile for data portals in Europe, Version 2.0 https://semiceu.github.io/GeoDCAT-AP/releases/2.0.0/

SEMIC: DCAT-AP — Version 2.1, DCAT Application Profile for data portals in Europe, Version 2.0 https://joinup.ec.europa.eu/collection/semantic-interoperability-community-semic/solution/dcat-application-profile-data-portals-europe/release/210

ISO: ISO19115:2003/Cor1:2006, Geographic Information – Metadata – Implementation specification http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=44361

ISO: ISO19115-1:2014, Geographic Information – Metadata – Part 1: Fundamentals https://www.iso.org/standard/53798.html

ISO: ISO19115-3, Geographic Information – Metadata – Part 3: XML schema implementation for fundamental concepts http://www.iso.org/iso/home/store/catalogue_ics/catalogue_detail_ics.htm?csnumber=32579

ISO: ISO 19139:2007, Geographic Information – Metadata XML, http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=32557

Uwe Voges, Kristian Senkler: OGC 07-045r2, OpenGIS® Catalogue Services Specification 2.0.2 — ISO Metadata Application Profile: Corrigendum. Open Geospatial Consortium (2022). https://portal.ogc.org/files/80534.

Richard Martell: OGC 07-110r4, CSW-ebRIM Registry Service — Part 1: ebRIM profile of CSW. Open Geospatial Consortium (2009). https://portal.ogc.org/files/?artifact id=31137.

Uwe Voges: OGC 08-197r4, INSPIRE Conformance Class of OGC Cataloguing of ISO Metadata (CIM) using the ebRIM profile of CS-W, 2011-10-11

Jerome Gasperi, Frédéric Houbie, Andrew Woolf, Steven Smolders: OGC 10-157r4, OGC® Earth Observation Metadata profile of Observations & Measurements. Open Geospatial Consortium (2016). https://docs.ogc.org/is/10-157r4/10-157r4.html.

Frédéric Houbie, Steven Smolders: OGC 11-035r1, EO Product Collection, Service and Sensor Discovery using the CS-W ebRIM Catalogue. Open Geospatial Consortium (2013). https://portal.ogc.org/files/?artifact id=53276.

Pedro Gonçalves, Uwe Voges: OGC 13-026r9, OGC OpenSearch Extension for Earth Observation, 2019 https://docs.opengeospatial.org/is/13-026r9/13-026r9.html

Uwe Voges, Frédéric Houbie, Nicolas Lesage, Marie-Lise Vautier: OGC 13-084r2, OGC I15 (ISO19115 Metadata) Extension Package of CS-W ebRIM Profile 1.0. Open Geospatial Consortium (2014). https://portal.ogc.org/files/?artifact id=56905.

Y. Coene, U. Voges, O. Barois: OGC 17-003r2, OGC EO Dataset Metadata GeoJSON(-LD) Encoding Standard. Open Geospatial Consortium (2020). https://docs.ogc.org/is/17-003r2/17-003r2.html.

Clemens Portele, Panagiotis (Peter) A. Vretanos, Charles Heazel: OGC 17-069r3, OGC API — Features — Part 1: Core. Open Geospatial Consortium (2019). https://docs.ogc.org/is/17-069r3/17-069r3.html.

Y. Coene, U. Voges, O. Barois: OGC 17-084r1, EO Collection GeoJSON(-LD) Encoding. Open Geospatial Consortium (2021). https://docs.ogc.org/bp/17-084r1/17-084r1.html.

Michael A. Leedahl: OGC 19-016r1, OGC Testbed-15: Data Centric Security. Open Geospatial Consortium (2019). https://docs.ogc.org/per/19-016r1.html.

Yves Coene: OGC 19-020r1, OGC Testbed-15: Catalogue and Discovery Engineering Report. Open Geospatial Consortium (2019). https://docs.ogc.org/per/19-020r1.html.

Panagiotis (Peter) A. Vretanos, Clemens Portele: OGC 19-079r1, OGC API — Features — Part 3: Filtering, https://docs.opengeospatial.org/DRAFTS/19-079r1.html

Panagiotis (Peter) A. Vretanos, Clemens Portele: OGC 20-002, OGC API — Features — Part 4: Create, Replace, Update and Delete, https://docs.ogc.org/DRAFTS/20-002.html

Panagiotis (Peter) A. Vretanos, Tom Kralidis, Charles Heazel: OGC 20-004, OGC API – Records – Part 1: Core, 2019 https://docs.ogc.org/DRAFTS/20-004.html

Aleksandar Balaban: OGC 20-021r2, OGC Testbed-16: Data Centric Security Engineering Report. Open Geospatial Consortium (2021). https://docs.ogc.org/per/20-021r2.html.

Charles Heazel: OGC 20-024, OGC API — Common — Part 2: Geospatial Data, 2022 https://docs.ogc.org/DRAFTS/20-024.html

Aleksandar Balaban, Andreas Matheus: OGC 21-020r1, OGC Testbed-17: Data Centric Security ER. Open Geospatial Consortium (2022). https://docs.ogc.org/per/21-020r1.html.

Panagiotis (Peter) A. Vretanos, Clemens Portele: OGC 21-065, Common Query Language (CQL2), https://docs.ogc.org/DRAFTS/21-065.html

Andreas Matheus: OGC 22-014, Testbed-18: Key Management Service API Engineering Report, http://ogc.pages.ogc.org/T18-Secure_Asynchronous_Catalogs/documents/D008/document.html

C. Lagoze, H. Van de Sompel et al.: OAI-PMH, Protocol Version 2.0, The Open Archives Initiative Protocol for Metadata Harvesting, 2015 https://www.openarchives.org/OAI/openarchivesprotocol.html

3.  Terms, Definitions, and Abbreviated Terms

3.1.  Terms and Definitions

3.1.1.  Access Token

A token that can be provided as part of a service request that grants access to the service being invoked on. This is part of the OpenID Connect and OAuth 2.0 specification [OGC 21-020r1].

3.1.2.  Data-Centric Security

Data-centric security emphasizes the dependability of the data itself rather than the security of networks, servers, or applications [Wikipedia].

3.1.3.  (Spatial) Data Set

Identifiable collection of (spatial) data [INSPIRE].

3.1.4.  (Spatial) Data Set Series

Collection of (spatial) data sets sharing the same product specification [INSPIRE].

3.1.5.  Discovery Service

Service that makes it possible to search for spatial data sets and services on the basis of the contents of the corresponding metadata and to display the contents of the metadata [INSPIRE].

3.1.6.  Granule

A granule is the finest granularity of data that can be independently managed. A granule usually matches the individual file of EO satellite data [CEOS-BP].

3.1.7.  STANAG

In NATO, Standardization Agreement defines processes, procedures, terms, and conditions for common military or technical procedures or equipment between the member countries of the alliance.

3.2.  Abbreviated terms

AP

Application Package

API

Application Programming Interface

CEOS

Committee on Earth Observation Satellites

CQL

Common Query Language

CSW

Catalogue Service for the Web

DCAT

Data Catalog Vocabulary

DCS

Data Centric Security

DEK

Data Encryption Key

DPoP

Demonstrating Proof-of-Possession

EO

Earth Observation

EP

Extension Package

ESA

European Space Agency

HTTP

Hypertext Transfer Protocol

IdP

Identity Provider

INSPIRE

INfrastructure for SPatial InfoRmation in Europe

ISO

International Organization for Standardization

JOSE

Javascript Object Signing and Encryption

JSON

JavaScript Object Notation

JWE

JSON Web Encryption

JWK

JSON Web Key

JWS

JSON Web Signature

JWS/CT

JSON Web Signature Clear Text

JWT

JSON Web Token

KEK

Key Encryption Key

KMS

Key Management System

OAI-PMH

Open Archive Initiative Protocol for Metadata Harvesting

OGC

Open Geospatial Consortium

REST

Representational State Transfer

STAC

SpatioTemporal Asset Catalog

STANAG

Standardization Agreement

SWG

Standard Working Group

TIE

Technology Integration Experiment

UML

Unified Modeling Language

URI

Uniform Resource Identifier

URL

Uniform Resource Locator

XML

eXtensible Markup Language

4.  OGC API-Records tailoring

4.1.  Introduction

This chapter includes the following.

  1. Whether OGC API – Records can support classical discovery workflows comparable with OGC CSW/ISO 19115 setups.

  2. A proposed tailoring based on the use cases and requirements gathered during the project.

4.1.1.  CSW ISO AP / ISO19115 Setups

OGC CSW has been used for ISO19115 metadata (and in particular its XML encoding ISO19139(-2)) extensively in the past. The CSW ISO Application Profile (AP) OGC 07-045r1 is widely implemented in Europe as the INSPIRE discovery service as one of the INSPIRE Network Services [3]. In addition, the INSPIRE community uses ISO19115 metadata and its XML encodings (e.g., ISO19139(-2)) for encoding dataset, dataset series, and services as explained in the Technical Guidance document [4]. The Joint Research Centre (JRC) of the European Commission (EC) are proposing a GeoDCAT-AP encoding as a Resource Description Framework (RDF) vocabulary with information content covering the union of metadata elements of the core profile of ISO 19115:2003 and those defined in the framework of the INSPIRE Directive of the European Union. This allows for a JSON-LD encoding for metadata records currently described within the INSPIRE community.

4.1.2.  CSW ebRIM AP / ISO19115 Setups

In addition to CSW ISO AP, other communities use the CSW ebRIM Application Profile (AP) OGC 07-114r4 for discovery of resources described using the same ISO19115-based metadata. A dedicated ebRIM Extension Package for CSW ebRIM was developed by the OGC members and released in 2014 (OGC 13-084r2). This standard is known as I15 Extension Package (EP) or Cataloguing of ISO19115 Metadata (CIM) EP. The extension package was originally used by the Earth Observation (EO) community to support EO collection, service and sensor discovery as described in OGC 11-035r1. A typical EO discovery workflow consists of two steps: An initial search for EO collections (similar to INSPIRE dataset series) followed by a search for EO granules (i.e., products, similar to INSPIRE datasets) belonging to the collection. The search parameters available for the granule search typically differ according to the collection, such as filtering according to cloud cover percentage only applies to collections from optical sensors. While discovery services based on the ebRIM CSW service bindings have been replaced by OpenSearch service bindings in the EO community (See CEOS-BP and OGC 13-026r9), many agencies still describe their EO collections using ISO19139(-2) metadata records. The /gmd:MD_Metadata/gmd:parentIdentifier property (ISO19139:2007), /eop:metaDataProperty/eop:EarthObservationMetaData/eop:parentIdentifier (OGC 10-157r4) property, $.properties.parentIdentifier (OGC 17-003r2) property and eo:parentIdentifier queryable (OGC 13-026r9) all reflect the hierarchical relation between the metadata record of an EO granule and the metadata record of the corresponding EO collection.

The gmd:parentIdentifier relation is also mandatory in the INSPIRE context if a higher level dataset is available in the hierarchy [5][6].

4.2.  Main use cases and requirements

Table 1 — User stories — discovery workflow

User StoryAs a …​I want to …​so that I can …​
1Metadata Consumerobtain metadata about the catalog service endpoint, including its service bindings.interact with the catalog.
2Metadata Consumeraccess the catalog service and perform requests for catalog records.discover metadata records available in the catalog.
2.1Metadata Consumeraccess the catalog service and perform search requests for catalog records matching my search criteria.discover metadata records available in the catalog.
2.2Metadata Consumeraccess the catalog service and retrieve one specific complete catalog record in a specific format.retrieve all detailed metadata information for a single record in my preferred format (XML, ISO, RDF, …).
3Metadata Publisherupload metadata records in the catalogmake them discoverable for metadata consumers.
3.1Metadata Publisherupdate or remove metadata records available in the catalogperform metadata changes.
3.2Metadata Publisherobtain metadata records available in the catalog.perform metadata changes.

Clause 4.1 of [3] lists the identified use cases that an INSPIRE Discovery Service has to fulfill to support the typical INSPIRE workflow. Such a service is known as the INSPIRE Profile of CSW ISO AP. The corresponding use case diagram is depicted below.

Figure 1 — Discovery Service Use Cases [3]

The following subsections assess whether OGC API-Records can satisfy each of these use cases and derive requirements for the additional tailoring of OGC API-Records.

4.2.1.  Use Case 1 (UC1): Get Discovery Service Metadata

A CSW catalog allows clients to retrieve service metadata from a server via the GetCapabilities operation which may contain a MetadataURL element (Req. 7 and Table 3 of [3]).

Similarly, an OGC API-Records implementation should provide the same information in the following way, to support the same workflow:

Table 2 — Discovery service metadata comparison

Extended CSW MetadataOGC API-Records Metadata
Service identification,
Service provider,
Operations metadata
Landing Page link rel=”describedby” and type=”application/vnd.iso.19139+xml” and /conformance endpoint. The hreflang attribute can be used in the link object to provide the discovery service metadata in multiple languages (Req. 6 of [3]).
Filter capabilitiesLandingPage link rel=”queryables”, type=”application/schema+json” and /queryables endpoint as per OGC 19-079r1. Similarly, CQL capabilities are to be advertised.

Recommendation 1

Statement

The discovery interface should provide discovery service metadata equivalent to the above Extended CSW Capabilities information.

4.2.2.  Use Case 2 (UC2): Discover Metadata

To implement the INSPIRE workflow, the CSW ISO AP supports the GetRecords operation as per clause 4.3.2 of [3] with following two additional parameters.

  • The language parameter: The OGC API-Records API server can provide a similar capability by supporting the usual HTTP content negotiation mechanisms and process the Accept-Language header of a request (as per clause 7.10 of OGC 17-069r3).

  • The query parameter: Supported by the filter statement of CSW ISO AP. To support similar Filter_Capabilities as can be advertised in a CSW Capabilities document, the OGC API-Records server will need to implement a subset of the draft OGC Common Query Language (CQL2) OGC 21-065 and support CQL2 filter expressions at the /collections/{collection-id}/items endpoint.

    NOTE  INSPIRE requires the Discovery Service to advertise the default language in the CSW GetCapabilities response. Proposing a similar mechanism to advertise the default language is further work. Possible approaches include:

    • advertise default language in the OGC API-Records Landing Page response;

    • advertise default language in the OGC API-Records API Definition response; and

    • use of hreflang in the link object referring to the search endpoint (/collections/{id}/items) in a Collection response.

Recommendation 2

Statement

The discovery interface should support the equivalent of the (INSPIRE) search parameters defined in clause 4.4 of [3].

When past OGC discovery interfaces were defined, INSPIRE requirements were taken into account by proposing the search parameters required by the INSPIRE discovery service. The OGC OpenSearch standard OGC 13-026r9 was tailored in this way to cover INSPIRE requirements and a dedicated INSPIRE conformance class was added. The CSW CIM EP specification was also tailored for INSPIRE requirements.

To ensure a common response format, a GetRecords request is recommended to support “application/xml” and ISO19139 as outputSchema (outputSchema=http://www.isotc211.org/2005/gmd).

Recommendation 3

Statement

The discovery interface should support access to the (original) XML-based metadata (i.e., ISO19139, ISO19139-2, ISO19115-3, etc.) through content negotiation or indirectly via an $.properties.links[] object with rel=”via” in a regular API-Records GeoJSON search response.

Recommendation 4

Statement

The discovery interface should use the media types listed in OGC13-026r9 for identifying ISO19139, ISO19139-2, or ISO19115-3 representations, i.e., “application/vnd.iso.19139+xml”, “application/vnd.iso.19139-2+xml”, and “application/vnd.iso.19115-3+xml” for content negotiation or as type attribute of the rel=”via” links.



{
"rel": "via",
"href": "https://fedeo.ceos.org/collections/series/items/PROBA.CHRIS.1A?httpAccept=application/vnd.iso.19139%2Bxml",
"type": "application/vnd.iso.19139+xml",
"title": "ISO 19139 metadata"
}

Figure 2 — Access to Original ISO Metadata File With "Via" Link From the GeoJSON Representation.

An INSPIRE discovery service has to advertise all its queryables. To achieve this capability, the OGC API-Records catalog needs to advertise its queryables via the appropriate endpoints /queryables and/or /collections/{collection-id}/queryables.

Recommendation 5

Statement

The discovery interface should support discovery of “datasets,” “dataset series,” and “services”.

Recommendation 6

Statement

The discovery interface should support GeoDCAT-AP or DCAT-AP encoding as primary metadata representation.

Recommendation 7

Statement

The discovery interface should support retrieval of records using their GeoDCAT-AP or DCAT-AP encoding in at least the following RDF serialisations: application/rdf+xml and application/ld+json. Support for text/turtle is optional.

4.2.3.  Use Case 3 (UC3): Publish Metadata

The Publish Metadata operation supports editing (insert, update, and delete) of metadata elements of resources in the catalog (push or pull metadata mechanisms). To support the INSPIRE workflow, the CSW ISO AP has to support the Transaction (push) or Harvest (pull) operation as per clause 4.3.3 of [3].

To support similar capabilities, the OGC API-Records server will need to implement the draft “OGC API — Features — Part 4: Create, Replace, Update, and Delete” OGC 20-002 standard.

NOTE  The above OGC 20-002 standard may also support editing collections available at a /collections endpoint when the resources endpoint is interpreted as {landingPageUri}/collections. This case is similar to the {landingPageUri}/processes case (Example 2).

Recommendation 8

Statement

The catalog interface should support insertion, deletion, and update of “datasets,” “dataset series,” and “services” metadata records.

Recommendation 9

Statement

The catalog interface should support insertion and updates of records using their original ISO19139 or ISO19115-3 encoding.

Recommendation 10

Statement

The catalog interface should support insertion and updates of records using their GeoDCAT-AP or DCAT-AP encoding.

Recommendation 11

Statement

The catalog interface should support insertion and updates of records using their GeoDCAT-AP or DCAT-AP encoding in at least the following RDF serialisations: application/rdf+xml and application/ld+json. Support for text/turtle is optional.

4.3.  Proposed Interface Design

In clause 6.5, the draft OGC API-Records standard defines three building blocks that each can be tailored for a specific community. The following subsections propose a tailoring of each of these building blocks to support the requirements that were identified in the previous section.

Requirement 1

Label/req/iso/record-types-1
Statement

The catalog shall support discovery resources of type series (if applicable) via one of the following mechanisms.

A

(Option 1) Via the /collections and /collections/{resource-id} endpoints.

B

(Option 2) Via the /collections/{collection-id}/items and /collections/{collection-id}/items/{resource-id} endpoints.

Requirement 2

Label/req/iso/record-types-2
Statement

The catalog shall support discovery resources of type dataset or service (if applicable) via the /collections/{collection-id}/items and /collections/{collection-id}/items/{resource-id} endpoints.

As explained above, there are two alternative ways to map series on the data model. The tailoring of the draft OGC API-Records Standard and interpretation of the requirements below depend on the selected mapping. The term series search endpoint is used to indicate the search endpoint for series search selected according to the above requirement. The terms dataset and services search endpoint apply to the search endpoints for dataset and service records (if applicable).

4.3.1.  Record Collection (Catalog) Tailoring

Section 8 of OGC 20-004 defines the schema for the collection resource as an extension of the collection schema defined in OGC API-Features and OGC API-Common — Part 2: Geospatial Data.

Recommendation 12

Statement

If additional GeoJSON properties are required in the catalog collection schema to represent ISO19139(-2) or ISO19115-3 dataset series metadata properties, they should be borrowed from the GeoDCAT-AP or DCAT-AP encoding when possible. Applicable to Option-1 only.

Recommendation 13

Statement

The catalog should support the ISO19139(-2) or ISO19115-3 metadata representations for the collection schema (via content negotiation or a query parameter, e.g., f=). This represents an additional requirements class in addition to “clause 10.3 Requirements Class GeoJSON” and “clause 10.2 Requirements Class HTML” for the catalog collection schema in OGC 20-024. Applicable to Option-1 only.

4.3.2.  Record Schema Tailoring

Section 16.1 of OGC 20-004 defines the GeoJSON (application/geo+json) encoding of the catalog record schema.

Recommendation 14

Statement

If additional GeoJSON properties are required in the catalog record schema to represent ISO19139(-2) or ISO19115-3 metadata properties, they should be borrowed from the GeoDCAT-AP or DCAT-AP encoding when possible.

NOTE  The EO Collection GeoJSON(-LD) Encoding (OGC 17-084r1) Best Practice proposes a reusable GeoJSON encoding with corresponding mapping to ISO19139(-2) and NASA UMM-C properties in its Annex C, consistent with GeoDCAT-AP via a JSON-LD context definition.

Recommendation 15

Statement

The catalog should support the ISO19139(-2) or ISO19115(-3) metadata representations for the record schema (via content negotiation or a query parameter, e.g., f=). This represents an additional requirements class in addition to “clause 16.1 Requirements Class GeoJSON” and “clause 16.3 Requirements Class HTML” for the catalog record schema.

4.3.3.  Records API Tailoring

Requirement 3

Label/req/iso/type-queryable
Statement

The OGC API-Records search endpoint shall support the queryable type, equivalent to the CSW queryable Type (MD_Metadata.hierarchyLevel) to filter (ISO19139) metadata records based on the hierarchyLevel (i.e., series, dataset, service) (See OGC 07-045r2).

Examples:

To support the search workflows using search criteria defined in Table 4 of [3], the following requirements apply.

Requirement 4

Label/req/iso/mandatory-series-queryables
Statement

The OGC API-Records series search endpoint shall support the following additional search parameters with expected data type, meaning and mapping on (ISO19139) metadata as defined in OpenSearch Extension for Earth Observation (OGC 13-026r9).

A

useLimitation.

B

accessConstraint

C

otherConstraint

D

classification

E

organisationName

F

organisationRole

G

topicCategory

H

lineage

I

keyword

J

denominator

K

distanceValue

L

distanceUOM

M

Accept-Language (header) — i.e., metadata language.

N

title

O

abstract

P

specificationTitle

Q

specificationDate

R

specificationdateType

S

degree

Requirement 5

Label/req/iso/mandatory-item-queryables
Statement

The OGC API-Records /collections/{collectionId}/items endpoint (a.k.a. dataset and service search endpoint) shall support the additional search parameters listed in the previous requirement /req/iso/mandatory-series-queryables.

Requirement 6

Label/req/iso/advertise-series-queryables
Statement

The OGC API-Records interface shall advertise the available queryables for the series search endpoint (if applicable) at the endpoint corresponding the option selected for “series” discovery (See above)

A

Via the /queryables endpoints (If Option 1 was selected).

B

Via the /collections/{collection-id}/queryables (if Option 2 was selected).

Requirement 7

Label/req/iso/advertise-item-queryables
Statement

The OGC API-Records interface shall advertise the available queryables for the dataset and service search endpoints (if applicable) at the /collections/{collection-id}/queryables endpoint.

The example below provides an example of a /queryables response advertising search parameters required for a typical INSPIRE discovery workflow.



{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"title": "Available search parameters",
"type": "object",
"properties": {
"limit": {
"title": "limit",
"type": "integer"
},
"bbox": {
"title": "bbox",
"type": "array",
"minItems": 4,
"maxItems": 6,
"items": {
"type": "number"
}
},
"datetime": {
"title": "datetime",
"type": "string"
},
"externalId": {
"title": "externalId",
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"title": "type",
"type": "array",
"items": {
"type": "string"
}
},
"q": {
"title": "q",
"type": "array",
"items": {
"type": "string"
}
},
"useLimitation": {
"title": "useLimitation",
"type": "string"
},
"accessConstraint": {
"title": "accessConstraint",
"type": "string",
"enum": [
"copyright",
"patent",
"trademark",
"license",
"intellectualPropertyRights",
"restricted",
"otherRestrictions"
]
},
"otherConstraint": {
"title": "otherConstraint",
"type": "string"
},
"classification": {
"title": "classification",
"type": "string",
"enum": [
"unclassified",
"restricted",
"confidential",
"secret",
"topSecret"
]
},
"organisationName": {
"title": "organisationName",
"type": "string",
"enum": [
"CEDA",
"CMEMS",
"DE/DLR",
"ESA/ESRIN",
"FR/CNES",
"JP/JAXA/EOC",
"VITO"
]
},
"organisationRole": {
"title": "organisationRole",
"type": "string",
"enum": [
"resourceProvider",
"custodian",
"owner",
"user",
"distributor",
"originator",
"pointOfContact",
"principalInvestigator",
"processor",
"publisher",
"author"
]
},
"topicCategory": {
"title": "topicCategory",
"type": "string"
},
"lineage": {
"title": "lineage",
"type": "string"
},
"keyword": {
"title": "keyword",
"type": "string"
},
"denominator": {
"title": "denominator",
"type": "string"
},
"distanceValue": {
"title": "distanceValue",
"type": "number"
},
"distanceUOM": {
"title": "distanceUOM",
"type": "string"
},
"language": {
"title": "type",
"type": "string"
},
"title": {
"title": "type",
"type": "string"
},
"abstract": {
"title": "abstract",
"type": "string"
},
"specificationTitle": {
"title": "specificationTitle",
"type": "string"
},
"specificationDate": {
"title": "specificationDate",
"type": "string",
"format": "date-time"
},
"specificationdateType": {
"title": "specificationdateType",
"type": "string",
"enum": [
"creation",
"revision",
"publication"
]
},
"degree": {
"title": "degree",
"type": "string",
"enum": [
"True",
"False",
"Null"
]
}
},
"$id": "https://tb18.cat.org/collections/series/queryables"
}

Figure 3 — Advertising INSPIRE Search Parameters Via the /queryables Response

Requirement 8

Label/req/iso/update-series
Statement

The OGC API-Records shall implement (series) metadata record insertion, update, and deletion at the /collections (Option 1) or /collections/{collection-id}/items endpoint (Option2) using the paths and HTTP methods as per OGC20-002.

Requirement 9

Label/req/iso/update-items
Statement

The OGC API-Records shall implement (dataset and service) metadata record insertion, update, and deletion at the /items endpoint using the paths and HTTP methods as per OGC20-002.

See Annex A Example 3.3 for a detailed Jupyter Notebook example using the POST operation and application/xml media type to insert a metadata record and the DELETE operation to remove the record.

The resource definition diagram below summarizes the available resources, the applicable HTTP methods, available representations, and the paths for each of the resources. Some parts of the diagram only apply when Option 1 was used for modeling (ISO) series, i.e., when /collections/{collection-id} represents a series.

Figure 4 — Resource Definition Diagram for Tailored OGC API-Records

5.  Asynchronous Communication for OGC API-Records

5.1.  Introduction

One of the goals for Testbed-18 was to contribute to asynchronous communication discussions by implementing an asynchronous catalog. The OGC Testbed-18 Call for Participation (CFP) describes asynchronous communication as scenarios where clients want to subscribe to updates for previously provided queries. Those subscribers should be informed of new or updated catalog entries (e.g., inserted by a publisher).

The designed solution described below is based on the Subscription resource which represents the mission of delivering update notification based on the requested records query and the provided delivery method.

Although the approach above does not specifically tackle the concern of queries that cannot be processed within regular HTTP time out (e.g., when the server needs encrypting), such a scenario is simply a special case of a subscription with a single update notification (when the response is available).

5.2.  Main Use Cases and Requirements

Table 3 — User Stories — Asynchronous Catalog

User StoryAs a …​I want to …​so that I can …​
21Metadata Consumersubscribe to a search request.receive additional search results in the future matching my original search criteria.
22Metadata Consumerunsubscribe to a search request subscription.stop receiving additional search results in the future.
23Metadata Consumerdefine the frequency with which I want to receive additional search results (e.g., daily).receive search result updates grouped by period.
24Metadata Consumerprovide an HTTP endpoint or email address to receive notification of additional search resultschoose the notification mechanism.
25Metadata Consumerindicate at subscription time that the server shall apply Data Centric Security (signature, encryption) to the future search responses.choose the security level for future additional search results.

The subscription interface should allow a client to subscribe to the results (and updates) of a catalog query. The subscription implies that the catalog must notify (asynchronously) the subscribers of subsequent modifications matching the query until the user unsubscribes.

In particular, the following reports and interfaces covering asynchronous interactions were reviewed and considered for the design of a solution.

  • The asynchronous support capability provided in the draft OGC API – Processes Standard involves the polling of status (supported by the Core requirements class) and the callback-driven approach (supported by the Callback requirement class) which relies on OpenAPI native capabilities (https://swagger.io/docs/specification/callbacks/).

  • The behavior models described in the OGC Publish-Subscribe White Paper (OGC 20-081) include the Delayed Response, the Standing Request, the Synchronization and the Publish-Subscribe.

  • The Simple Async mechanism proposed as an OGC API – Common extension (https://github.com/opengeospatial/ogcapi-common/tree/master/proposals/simple-async).

  • The Geosynchronization mechanism specified in the OGC OWS 7 Engineering Report — Geosynchronization service (OGC 10-069r2) describing the Subscriptions, Topics, and Publishers resources and related operations.

  • The Publish/Subscribe Interface Standard (OGC 13-131r1) that supports the core components and concepts of the Publish/Subscribe message exchange pattern with OGC Web Services.

  • The OGC Testbed-13 Asynchronous Services ER (OGC 17-028) that essentially describes the Publish-Subscribe and the status polling of the legacy OGC Web Processing Service interface.

As a starting point, the OGC API — Processes Callback approach was adapted to the API Records context as follows.

  • The behavior model is extended to support a subscriber requesting continuous update notifications about new catalog records.

  • The subscriber must provide a notification expiration time to avoid flooding a subscriber with too many callback notifications.

  • The Dismiss operation must support the cancellation of the subscription.

  • The content of the notification may either include the (updated) records or a link to these records.

While the callback could be specified in HTTP GET Catalog request, the Testbed participants reached a consensus to design a blank solution and handle the subscription creation from a dedicated HTTP POST on the resource endpoint.

5.3.  Proposed Interface Design

The following subsections propose a OGC Subscription requirement class for the OGC API-Records draft standard. The proposed interface relies on subscription resources. A subscription is a job that delivers notifications when a client subscribes to resources updates (i.e., new records or modified records).

The following flow applies to a subscription and the resulting notifications.

  • The Catalog Client (on the behalf of a signed user) submits a subscription request to the Catalog server and provides the URL to the subscribed resources and the delivery options (delivery method, expiration, schedule).

  • The Catalog server registers the subscription and returns HTTP code 201 along with the link to the created subscription.

  • Each time the server schedules a check on the subscribed records, a notification is prepared and sent to the configured receiver.

Figure 5 — Asynchronous Pattern for API Records

The interface provides operations to create, read, update, and delete subscriptions. The resource definition diagram below summarizes the applicable HTTP methods and the paths for each of the resources.

Figure 6 — Subscriptions Resources API Definition

5.3.1.  Subscription Resource Schema

A subscription is represented as the following set of properties.

  • Resources-uri: Identifier of the resources to which the user subscribes (typically a URL to catalog records).

  • Delivery: Method and target for notification deliveries formatted as protocol:address[,additional parameters] (e.g., mailto:you@ogc.org).

  • Expires: Seconds the subscription is valid (or ISO 8601 date to be discussed)/

  • Schedule: Defines the notification schedule using a cron-like format (e.g., “0 0 * * 0”).

  • Status: Indicates the state of a created subscription (e.g., started, completed, cancelled).

  • Deliveries: List the URL links to the resources that have already been delivered (in a notification).

Additional DCS properties (public-key, wrapped-dek) are detailed further.

The OpenAPI 3.0 schema subscription.yaml is represented on the class diagram below.

Figure 7 — Subscription Schema

5.3.2.  Create a Subscription

A client can create a subscription by identifying the resources for which update notifications should be sent and indicating the delivery options.

Requirement 10

Label/req/subscriptions/create
Statement

The server shall support the HTTP POST operation at the path /subscriptions. The request shall be based on the SubscriptionRequest class of the subscription.yaml schema.

Requirement 11

Label/req/subscriptions/create-success
Statement

A successful execution of the operation shall be reported as a response with a HTTP status code 201. The header of the response shall return the HTTP Location header that contains a link to the newly created subscription.

The example below illustrates a typical subscription request.



{
"resources-uri": "http://server.com/records/items?param=value",
"delivery": "http://server.com/callbackURI",
"expiry": "2025-12-10T",
"schedule": "0 0 * * 0"
}

Figure 8 — Subscription Request Example

See also Annex A Example 5.1.

Alternatively, a subscription could be requested directly when retrieving a list of catalog records. This could be achieved by extending the HTTP GET request with the relevant parameters (such as the OGC API Processes callbacks). However, the Testbed participants agreed to focus on the specific subscription endpoint in the context of the OGC API Records.

5.3.3.  Receive subscription notifications

If the subscriber provides a delivery method, then the results are communicated to the delivery endpoint in accordance with the delivery options (expiry, schedule, etc.). Also, the subscriber can specify preferences about the notification content (updated records or a link to those records) using the HTTP Prefer header as detailed below.

Requirement 12

Label/req/subscription/notification
Statement

The server shall deliver notifications when subscribed resources (identified in resources-uri) are updated (new resources or modified resources). If the request is accompanied with the HTTP Prefer header then the server SHOULD honor that preference.

A

The notification must contain a link to the resources if the subscription request is provided with the Prefer header with value ‘return=minimal’ or if the header is not present.

B

The notification must contain the list of resources if the request is accompanied with the HTTP Prefer header asserting a return=representation preference.

Requirement 13

Label/req/subscriptions/notification-delivery
Statement

The server shall send update notifications only if a delivery method is provided in the subscription. If provided, the server shall deliver notifications using the method and protocol provided in the delivery property (e.g., mailto:you@ogc.org)

Requirement 14

Label/req/subscriptions/notification-expires
Statement

If the expires property is provided, the server shall stop deliver notification starting at the indicated expiration date.

Requirement 15

Label/req/subscriptions/notification-schedule
Statement

If the schedule property is provided, the server shall deliver notification following the provided UNIX cron schedule.

5.3.4.  Retrieve a Subscription

A subscription can be retrieved to monitor the subscription status (e.g., started, completed, cancelled) and get links to the updated resources clusters that were reported by the server.

When no delivery method is specified, the subscription plays the same role as the job status document defined in OGC API Processes: The subscription can be polled for discovering updated resources.

Requirement 16

Label/req/subscriptions/subscription-get
Statement

The server shall support the HTTP GET operation at the path /subscriptions/{sub_id} to retrieve an existing subscription.

Requirement 17

Label/req/subscriptions/subscription-get-response
Statement

A successful execution of the operation shall be reported as a response with a HTTP status code 200. The content of that response shall be based upon the Subscription class of the OpenAPI 3.0 schema subscription.yaml. The deliveries array provide links to delivery units (i.e., a set of updated resources that have been prepared by the server).

Recommendation 16

Statement

The catalog should prepare the delivery units following the frequency specified in the schedule property. If an update is not detected, then no delivery unit should be prepared, and no link should be added to the deliveries array.

The example below illustrates the response of the HTTP GET request.

Figure 9 — Get Subscription Response Example

5.3.5.  Update and Delete Subscription

A subscription might be deleted using HTTP Delete or can be updated using HTTP Patch for editing any of the subscription property (e.g., delivery, schedule, public-key).

Note that the possibility to update the status of the subscription (e.g., paused) has been raised but not implemented in the scope of the project.

See also Annex A Example 5.6.

Requirement 18

Label/req/subscriptions/subscription-patch
Statement

The server shall support the HTTP PATCH operation at the path /subscriptions/{sub_id}. The request shall be based on the SubscriptionRequest class of the subscription.yaml schema, and the delivery process should be updated accordingly. The response of a successful PATCH request is 204: Done.

Requirement 19

Label/req/subscriptions/subscription-delete
Statement

The server shall support the HTTP DELETE operation at the path /subscriptions/{sub_id}. The corresponding subscription should be removed and can no longer be retrieved. The response of a successful DELETE request is 204: Done

5.3.6.  Subscription States

A tailoring of the OGC Subscription requirement was implemented for requesting an explicit subscription status update. The approach extends the existing status (started, completed, cancelled) with additional values, and proposes providing the PATCH operation to update the status of a subscription.

The subscription states as shown on diagram below include the following.

  • created: The subscription has been submitted by the client.

  • approved: The subscription endpoint has been approved (with the security code).

  • ready: The target resources (uri) are provided.

  • started: The subscription is manually started.

  • stopped: The subscription is manually stopped.

  • deleted: The subscription is deleted.

See also Annex A Example 5.4 and Example 5.5.

Figure 10 — Subscription State Diagram

The diagram reflects only explicit operations, but automated status changes might be relevant (e.g., automatically starting the subscription). Moreover, alternative flows and states can be considered such as completed for an expired subscription.

6.  Application of Data Centric Security

6.1.  Introduction

Applying Data Centric Security can be applied to the following interactions.

  • Synchronous Search Responses

  • Asynchronous Responses

  • Metadata Insertions/Updates in the Catalog

6.2.  Main Use Cases and Requirements

The table below summarizes the main use cases.

Table 4 — User Stories — Data Centric Security

User StoryAs a …​I want to …​So that I can …​
11Metadata Publisherupload plain text metadata records in the catalog.make them discoverable for metadata consumers.
12Metadata Publisherupload signed metadata records in the catalog.ensure integrity.
13Metadata Publisherupload encrypted metadata records in the catalog.ensure confidentiality and make it available to only selected metadata consumers.
14Metadata Publisherupload metadata records in the catalog combined with corresponding access rules.ensure appropriate access rights.
15Metadata Consumerchoose whether to receive metadata records in search responses as plain records, signed or encrypted assuming I have the appropriate access rights.select the appropriate security level.
16Metadata Consumerverify the signature of a metadata record part of a search response.check integrity and authenticity.
17Metadata Consumerdecrypt an encrypted metadata record which is part of a search response.process, display, etc. the metadata record content.

6.2.1.  Synchronous Responses With DCS

The API endpoints /collections/{id}/items (for item search), /collections/{id}/items/{id} (for collection search) etc.) that are subject to encrypted payloads or responses can vary. Clients can discover this through the media types supported for a specific resource (i.e. application/dcs+geo or application/jose).

In the context of an OGC API – Records implementation, the application of DCS has many similarities to the second scenario described in “Testbed-17: Data Centric Security ER” (21-020r1), which depicts the exchange of DCS-protected content from an OGC API — Features implementation. The same ER describes which metadata fields in a response allow a client to successfully decrypt the information.

6.2.1.1.  Application/DCS+GEO

According to clause 4.1 of 21-020r1, for OGC API – Features, the DCS data format can be applied as an extension to XML and JSON. Although the ISO19115 tailoring of OGC API – Records may decide to also use XML formats (see above), the focus was on a JSON approach. The response formats proposed for OGC API – Features correspond to the encrypted features in a JSON container (clause 5.2.2 of 21-020r1), based on the schema illustrated below.

figure

Figure 11 — API Features JOSE Based Containers JSON Schema (dcs+geo)

The potentially sensitive information in the data_description element can be requested with three levels of security (plain, integrity, or confidentiality) depending on the requested media type profile for application/dcs+geo. The catalog server detects that a client wants an encrypted response when it receives a request (via content negotiation) for the application/dcs+geo media type.

When provided in a JSON Web Encryption (JWE) token, the data_description element (see schema above) is encrypted with the public key of the user (i.e., client) providing the public Key Encryption Key (KEK) id previously registered at the Key Management Service (KMS).

The data is always encrypted in a JWE token using a Data Encryption Key (DEK). The kid and kurl of the DEK are included the JWE header. The kurl is a custom header parameter providing the URL to the KMS to retrieve the DEK. The definition of the DCS container in JSON is provided in clause 8 of OGC 20-021r2. The responses from an OGC API Records request (assuming the GeoJSON conformance class) encrypted in a DCS container contain “metadata” (optional housekeeping information) and “data”, with “data” representing the encrypted original OGC API Records response.

The following Data Centric Security (DCS) flow applies for synchronous search (and subscription) requests.

  • [1] The Catalog Client D114 (on the behalf of a signed in user) submits a request to the Catalog server (e.g. search request) and provides the DCS media type (f parameter), the access token, the key challenge (PIN), and the key challenge method.

  • [2] The Catalog validates the access_token, applies access control based on the bearer token, and retrieves the username and client_id associated with the user token.

  • [3] The Catalog server creates a Data Encryption Key (DEK) and then encrypts the response items using the relevant key (multiple keys might be required in case various confidentiality levels are associated to the response items).

  • [4] The Catalog registers the DEK along the client id (aud parameter), the access token, and the key_challenge to Key Management Service D115 (KMS).

  • [5] The Catalog response (DCS container) is returned to the Client.

  • [6] The client extracts the DEK kid and kurl to request the DEK. Optionally, the client might provide the kek_id of a previously registered user public key (Key Encryption Key) to request the encryption of the key.

  • [7] The Key Management Service (KMS) returns the DEK key optionally encrypted with the user private key (KEK).

  • [8] The Catalog Client decrypts the DCS container and displays the records to the user.

Figure 12 — Synchronous Responses with DCS

See Annex A Example 2.1 (/items) and Example 3.1 (/items/{item-id}) for detailed Jupyter Notebook examples using the application/dcs+geo media type.

6.2.1.2.  Application/JOSE

Instead of the above approach where the catalog server chooses the encryption key and communicates the key to the client via a reference (kid) to the KMS, a client may choose to use its own public encryption key and pass that key to the catalog server. The KMS is not used in this scenario. When the response (JOSE format) is received, the client can decrypt the response with its own private (encryption) key.

See Annex A Example 3.2 for a detailed Jupyter Notebook example using the application/jose media type defined in [RFC 7515].

The current assumption is that the /collections/{collection-id}/items and /collections/{collection-id}/items/{record-id} responses are in-scope for the above encryption. The same approach can be applied to /collections and /collections/{collection-id} if appropriate, with encrypted JSON instead of GeoJSON representations. Clients can discover which resources (URL) accept requests for the application/dcs+geo or application/jose media types as this should be advertised by the server in the OpenAPI definition of the interface or even in an OpenSearch OSDD document. This allows for a flexible use of such encrypted response capabilities by a (Catalog).

6.2.2.  Asynchronous Communication with DCS

When the notification includes links to the subscribed resources, the nominal Data Centric Security process can be applied when the resources are retrieved by the subscriber depending on the catalog implementation.

In the case where the notification includes the records, participants explored the following models for encrypting the data.

  • Using the KMS for retrieving the DEK generated by the catalog. However, Testbed participants were concerned about persisting user information on the catalog side and/or key permissions for the receiver endpoint which are not necessarily the same as the subscriber client.

  • Providing a client public key to encrypt DEK generated by the catalog.

  • Providing a DEK to the catalog generated by the client using the catalog private key.

Further recommendations are proposed to enforce DCS on the resource data when they are requested in the notification content.

Requirement 20

Label/req/subscription/dcs
Statement

If the subscriber requests resources in the notifications (HTTP Prefer header asserting a return=representation preference), then data centric security shall be applied (i.e., resources are encrypted) if the resource-uri specifies the dcs+geo format (f parameter).

A

The catalog shall encrypt the data using the DEK provided by the client and return the DEK identifier (if wrapped_dek property is provided).

B

The catalog shall generate a DEK to encrypt the data and return the DEK encrypted using the client public key (if public-key property is provided).

6.2.3.  Record Insertions With DCS

According to clause 2.3.1 of the CFP, publishers shall be able to send new or updated content to the catalog server with encrypted content that fulfills DCS principles. This implies that the catalog server acts as a (DCS) client receiving DCS encrypted content and must implement the steps a client typically applies as described in OGC 21-020r1.

6.3.  Proposed Interface Design

6.3.1.  Synchronous Responses With DCS (Encryption)

The diagram below is the proposed resource definition diagram for an OGC API-Records implementation with support for DCS (encryption).

Figure 13 — Resource Definition Diagram for OGC API-Records With DCS (Synchronous Responses)

Figure 14 — Resource Diagram /Collections/{collectionId}/Items

6.3.2.  Asynchronous Responses With DCS

As mentioned earlier, when notifications are requested for including the records (with the return-representation preference), the content must be encrypted for applying Data Centric Security.

The following flow extends the OGC API-Records asynchronous flow with DCS.

  • The Catalog Client (on the behalf of a signed user) submits a subscription request to the Catalog server (with the return-representation preference). The request includes either the public-key or wrapped-dek property (detailed further).

  • The Catalog server registers the subscription and returns HTTP code 201 along the link to the created subscription.

  • Each time the server prepares a notification, the records are encrypted depending on the selected security approach.

Figure 15 — DCS Async Sequence Diagram

6.3.2.1.  Subscriber Submits a DEK

The subscriber might submit a DEK generated locally then used by the catalog to return the resources encrypted in the notifications. The notification content is encoded in a JWE token with a header mentioning the kid (client DEK identifier) for decrypting the notification payload. The major drawback of this method is the reuse of the same encryption key for all notifications, potentially for years.

In the request, the subscriber provides the wrapped-dek property which holds the JWE token that includes the encrypted JWK encoding of the client DEK. The client DEK is encrypted with the catalog public key advertised on /.well-known/jwks.json with the attribute use set to enc.

The following subscription flow applies to a notification encryption based on a DEK generated by the client.

  • The catalog client (on the behalf of a signed user) retrieves the catalog server public key.

  • The catalog client generates the DEK and encrypts the DEK using the catalog public key.

  • The catalog client submits a subscription request to the catalog server and provides the encrypted DEK in the wrapped_dek property.

  • The catalog server decrypts the DEK with the private key.

  • For each notification, the catalog server encrypts the data records with the DEK.

  • The receiver service of the catalog client decrypts the data with the DEK.

Figure 16 — Notifications With DCS (Client Sends the DEK) Sequence Diagram

6.3.2.2.  Subscriber Submits Public Keys

The subscriber might submit a public key used to return the DEK that will be created by the catalog. The subscriber provides the public_key property which consists of a JWK public key.

In the notifications, the resources are encoded in a JWE token which includes the DEK encoded with the public key.

The following subscription flow applies to a notification encrypted based on a DEK generated by the catalog server.

  • The catalog client submits a subscription request to the Catalog server and provides a public key in the public_key property.

  • For each notification, the catalog server generates a DEK and sends the encrypted notification along with the JWE token holding the DEK encrypted with the client public key.

  • The receiver service of the catalog client decrypts the DEK with the private key, then decrypts the notification content with the DEK.

Figure 17 — Notifications with DCS (Catalog Generates the DEK) Sequence Diagram

As the solution also has be implemented using an HTTP GET operation, the recommendation below applies for the alternative operation.

Recommendation 17

Statement

When provided in an HTTP GET request, the public key used to return the DEK should be encoded using the deepObject style as per OpenAPI 3.0 – simple non-nested objects are serialized as paramName[prop1]=value1&paramName[prop2]=value2&…​

6.3.2.3.  Callback Endpoint Security Concerns

The notification endpoints (email address or HTTP(S) URL) must be validated by the service for the following reasons:

  • to prevent unsolicited content for existing endpoints; and

  • to avoid spamming servers for invalid endpoints.

Recommendation 18

Statement

The server SHOULD only deliver notifications to an email delivery endpoint if a link containing a secret code and delivered to the target email address has ben clicked by the receiver (to confirm the subscription).

Recommendation 19

Statement

The server SHOULD only deliver notifications to an HTTP(s) delivery endpoint if a TBD.

6.3.3.  Record Insertions With DCS

Publishers need to send new or updated content to the catalog server so that the interested parties can be notified as elaborated in the asynchronous communication related sections of this ER.

DCS principles might be applied to encrypt the content submitted on the catalog. This implies that the catalog server acts as a DCS client receiving DCS encrypted content, and is required to implement the steps a client typically applied as described in the Testbed-17: Data Centric Security ER (OGC 21-020r1).

For applying DCS to the OGC API-Records insert operation, Testbed participants proposed relying on the private key of the catalog. The public asynchronous encryption key can be advertised in /.well-known/jwks.json.

Recommendation 20

Statement

The records inserted in a catalog should be encoded using the catalog public key provided in the /.well-known/jwks.json endpoint (with key entry provided with attribute use set with value ‘enc’).

The cty (content type) attribute of the Javascript Object Signing and Encryption (JOSE) header (i.e., first part of the JWE) should be set to the media type of the metadata record to be inserted in the catalog. For example, the value “geo+json” corresponds to “application/geo+json”, while “vnd.iso.19139+xml” corresponds to “application/vnd.iso.19139+xml”. This allows the receiving catalog to know what it should obtain after decryption.

The sequence required for applying DCS to a catalog record is illustrated on the diagram below and includes the following steps.

  • The catalog client (publisher) retrieves the JSON Web Key Set (JWKS) containing the public key required for encrypting published content. The relevant key is the key item holding the ‘enc’ value (for encoding) in the use attribute.

  • The catalog client encrypts the content with the catalog public key and submits the request to the catalog server.

  • Typically, in an isolated secured runtime environment behind the catalog server, the submitted encrypted records are decrypted with the private key.

  • Once the decryption is achieved, the record is added to the catalog database and the catalog client receives the confirmation response.