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.

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.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

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.

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).

{
	"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.

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.

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.

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.

4.3.3.  Records API Tailoring

Examples:

• https://ogc.demo.secure-dimensions.de/pycsw/collections/metadata:main/items?type=series

• https://ogc.demo.secure-dimensions.de/pycsw/collections/metadata:main/items?type=dataset

• https://ogc.demo.secure-dimensions.de/pycsw/collections/metadata:main/items?type=service

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

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

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.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.

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.

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.

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.

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.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 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.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.

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.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.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.

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.