diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9f11b75 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 7534321..8ff355b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## 2022-09 ### Changed -- fixed missing mandatory elements in mutlipart message - +- fixed missing mandatory elements in multipart message +- Fixed wrong references to IDS-G-pre and RAM in CONTRIBUTING.md ## [Q2/2022] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28a5003..4b586ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to IDS-G-pre +# Contributing to IDS-G -IDS-G is the official repository of [IDSA](https://www.internationaldataspaces.org) to publish the [IDS-RAM]() and the subsequent specifications. +IDS-G is the official repository of [IDSA](https://www.internationaldataspaces.org) to publish the [IDS-RAM](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0) and the subsequent specifications. All content published here is approved by the IDSA Technical Steering Committee and the IDSA Working Groups. Detailed information on the contribution process can be found in the [IDS-G Handbook](Handbook/README.md). Nevertheless, you are very welcome to contribute to this project when you find a bug, want to suggest an improvement, or have an idea for a useful @@ -30,7 +30,7 @@ should at least include the following information: ## Labels -The [labels](https://github.com/International-Data-Spaces-Association/ids-g/labels) are listed at the +The [labels](https://github.com/International-Data-Spaces-Association/IDS-G/labels) are listed at the [issues](https://github.com/International-Data-Spaces-Association/IDS-G/issues). There are two types of labels: one describes the content of the issue and should be used by the developer that creates the issue. The other one, starting with `status`, will be added from the @@ -75,5 +75,5 @@ An example of a very good commit might look like this: `feat![login]: add awesom ## Versioning -IDS-G-pre uses the [SemVer](https://semver.org/) for versioning. The release versions +IDS-G uses the [SemVer](https://semver.org/) for versioning. The release versions are tagged with their respective version. diff --git a/Communication/CommunicationGuide.md b/Communication/CommunicationGuide.md new file mode 100644 index 0000000..b227c88 --- /dev/null +++ b/Communication/CommunicationGuide.md @@ -0,0 +1,171 @@ +# IDS Communication Guide # + +## Introduction ## + +Interoperability is a major goal of the IDS. Therefore, the interoperability between IDS Connectors and other components is of high importance. The IDS Communication Guide shall provide the required data structure and the interaction sequences to be realized for interoperability and to be used for interoperability testing. + +The Communication Guide is organized into a modular and composable structure. + +## Terms and Definitions ## + +### Control Plane vs. Data Plane and in-band vs. out of band ### + +Joint understanding of the terms `in-band` and `out-of-band`, as well as the `control plane` and `data plane`: + +**Commonalities:** Both term pairs… + +- represent the split of a previously joint, combined flow of information into two separate parts +- have a background in technology +- have some overlap, but put different emphasis + +#### in-band/out-of-band #### + +- **origins:** selection of radio frequencies (“bands”) for primary/secondary communication +- the split is motivated mainly by isolation & break-out reasons +- `in-band`: the same `frequency`, `connection` or `means of communication` is used for all transfers +- `out-of-band`: for a selected subset of communication, a different, dedicated band is selected +- **example:** main process is using HTTP, user identity verification subprocess uses SMTP (email) + +#### control plane/data plane #### + +- **origins:** in a networking device… +- the `control plane` is optimized for customizability and security. it controls the data plane. +- the `data plane` is optimized for speed, throughput and bandwidth. it handles the data payloads. +- the split is motivated mainly by “separation of concerns” +- `control plane`: controls what happens on the data plane +- `data plane`: agnostic of control logic, only used for payload transfers + +## Foundation ## + +The foundation package contains elements that commonly used. This includes standards that are used as foundation for the Communication Guide. + +### Foundational standards ### + +[The Foundational Standards list.](./FoundationalStandards/README.md) + +### Information Model ### + +The common information model that is used in every other package. This shall include a base model containing the entities of a data space and their relation. + +![Entities and relationships in data spaces](./images/Communicatoin-Guide_Dataspace_entities.png) + +(find the source file of the image above [here](./images/CommunicatoinGuide_Dataspace_entities.drawio)) + +The realization bases on DCAT for the Data Products and ODRL for Contract Policies. + +[The IDS-Information Model is here.](./Infomodel/README.md) + +### Identities ### + +messages and data types: +protocols: state machines for message flows and interaction patterns: +API binding: + +### Trust Frameworks ### + +messages and data types: +protocols: state machines for message flows and interaction patterns: +API binding: + +### Policies (authorization and Policy Description) ### + +messages and data types: +protocols: state machines for message flows and interaction patterns: +API binding: + +## Data Sharing (Conector) ## + +### Contract Negotiation ### + +part of the control plane + +messages and data types: +protocols: state machines for message flows and interaction patterns: +API binding: + +### Data Transfer ### + +part of the data plane. How data is exchanged with focus on communication and not on how the data plane is built. + +messages and data types: +protocols: state machines for message flows and interaction patterns: +API binding: + +## Catalog (Publish and query meta-data) ## + +The catalog in the IDS is a collection of Self-Descriptions, either of IDS Connectors or IDS Resources published by such IDS Connectors. The Self-Descriptions are the first-class-citizen in the catalogs, therefore all messages have the Self-Descriptions as their target, instead of the catalogs containing them. + +### Messages and Datatypes + +The messages, expected content, and the error behaviour are described in the [Functions and Correlated Messages](../Components/MetaDataBroker/FunctionsAndCorrelatedMessages/) section of the Metadata Broker. + +### Interaction Sequences + +Creating and manipulating catalog entries follows different state transitions depending wether Connector or Resource self-descriptions are concerned. + +#### Register and Update a Connector Self-Description + +An IDS Connector self-description is either unknown to a catalog (`initial state`), registered (`ConnectorRegistered`), temporarily inactive (`ConnectorInactive`), or deleted from the catalog (`end state`) as shown in Fig. C1. An inactive self-description is intended for Connectors, which are currently not reachable but intend to become active again in the dataspace. A Connector which self-description has been deleted before (aka. has reached the `end state`) must never come back with the same URI identifier. This is to prevent *false-flag operations* where evil players claim the identity of removed Connectors. + +![catalog-connector-interaction](./images/catalog-connector-interaction.png) + +___Figure C1: State transitions of Connector self-descriptions in a catalog.___ + + +#### Retrieve a Connector Self-Description + +Fig. C2 shows the diagram how to request a Connector self-description entry from a catalog. The DescriptionRequestMessage contains a reference to the target Connector self-discription identifier, defining which catalog entry shall be returned. There is no intermediate state so the operation is either successful or fails, for instance, due to a non-existing entry or an incorrectly formatted message. + +![catalog-request-connector-interaction](./images/catalog-request-connector-interaction.png) + +___Figure C2: Requesting a Connector self-description has no further states apart of the standard success or error cases.___ + + +#### Register and Update a Resource Self-Description + +An IDS Resource is either unknown to a catalog (`initial state`), registered (`ResourceRegistered`), temporarily inactive (`ResourceInactive`), or deleted from the catalog (`end state`) as shown in Fig. C3. It may be automatically created if a Connector self-description is added or extended (ConnectorUpdateMessage) and its self-description also contains Resource entries. A Resource self-description becomes inactive - and active again - if its parent Connector catalog entry becomes inactive or active. Similarily, a Resource self-description gets deleted automatically if the containing Connector gets deleted through a ConnectorUnavailableMessage. + +![catalog-resource-interaction](./images/catalog-resource-interaction.png) + +___Figure C3: State transitions of Connector self-descriptions in a catalog.___ + +#### Rerieve a Resource Self-Description + +Fig. C4 shows the diagram how to request a Resource entry from a catalog, similar to the operation for a Connector self-description. The DescriptionRequestMessage contains a reference to the target Resource self-discription identifier, defining which catalog entry shall be returned. There is no intermediate state so the operation is either successful or fails, for instance, due to a non-existing entry or an incorrectly formatted message. + +![catalog-request-resource-interaction](./images/catalog-request-resource-interaction.png) + +___Figure C4: Requesting a Resource self-description has no further states apart of the standard success or error cases.___ + + +#### Query a Catalog + +Fig. C5 shows the diagram how to send a formulated query a catalog. Different to the retrieval of Connector or Resource self-description entries, the return format is not predefined but depends on the query. The QueryMessage contains formulated query string in a standardized query language, for instance, SPARQL or the upcoming GQL. There is no intermediate state so the operation is either successful or fails, for instance, if the query language is not supported by the catalog hoster or the query itself contains syntax errors. + +![catalog-query-interaction](./images/catalog-query-interaction.png) + +___Figure C5: Sending a catalog query has no further states apart of the standard success or error cases.___ + + + +### API Bindings + +The API Operations of catalogs in the different protocol bindings are explained in the respective protocol sections: +* [IDS REST](./protocols/ids-rest/README.md#complex-operations-and-workflows) +* [IDS Multipart](./protocols/multipart/README.md#41-metadata-broker-communication) +* [idscp2](./protocols/idscp2/ApplicationLayer/README.md) + + +## Registration ## + +messages and data types: +protocols: state machines for message flows and interaction patterns: +API binding: + +## Audit logging ## + +currently out of scope + +## Vocabularies ## + +currently out of scope diff --git a/Communication/FoundationalStandards/README.md b/Communication/FoundationalStandards/README.md new file mode 100644 index 0000000..944b3ad --- /dev/null +++ b/Communication/FoundationalStandards/README.md @@ -0,0 +1,63 @@ +# Foundational Standards # + +These Foundational Standards are used in the IDS Communication Guide: + +## Attribute Based Access Control (ABAC) ## + +Related to Access Control that is not part of the [IDS-RAM](https://github.com/International-Data-Spaces-Association/IDS-G/blob/master/Glossary/README.md#ids-ram-international-data-spaces-reference-architecture-model). +[NIST, Guide to Attribute Based Access Control (ABAC) Definition and Considerations](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-162.pdf) + +## Linked Data Platform (LDP) ## + +W3C Recommendation how to read and write RDF data in RESTful manners, e.g. IDS Self-Descriptions, at a remote server. + +[W3C, "Linked Data Platform"](https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp.html) + +[W3C, "Linked Data Platform 1.0 Primer"](https://www.w3.org/TR/ldp-primer/) + +## Open Digital Rights Language (ODRL) ## + +[W3C, ODRL](https://www.w3.org/TR/odrl-model/) as basis + for IDS usage control. + +## Resource Description Framework (RDF) ## + +[Wikipedia, „Resource Description Framework“](https://en.wikipedia.org/wiki/Resource_Description_Framework). + +## Time Ontology in OWL ## + +[W3C, "Time Ontology"](https://www.w3.org/TR/owl-time/) + +## The Organization Ontology ## + +[W3C, "The Organization Ontology"](https://www.w3.org/TR/vocab-org/) + +## WebAccessControl (WAC) ## + +LDP-inspired access control language for decentralized systems. + +[W3C, "Web Acces Control"](https://www.w3.org/wiki/WebAccessControl) + +## eXtensible Access Control Markup Language (XACML) ## + +OASIS standard defining an XML-based policy language and reference architecture for access control systems. + +[Wikipedia, "XACML"](https://en.wikipedia.org/wiki/XACML) + +## Verifiable Credentials/Verifiable Presentations (VC/VP) ## + +W3C Recommendation to sign RDF statements, in particular JSON-LD. + +[W3C, "Verifiable Credentials"](https://www.w3.org/TR/vc-data-model/) + +## Transport Layer Security (TLS)## + +RFC 8446 (TLS v1.3) specifies how to encrypt data transfer in the internet. + +[RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) + +## Multipart ## + +Message format to transfer content with several parts. Used, e.g., for the exchange of IDS messages applying the Multipart-over-HTTPS scheme. + +[Wikipedia, Multipart MIME](https://en.wikipedia.org/wiki/MIME#Multipart_messages) \ No newline at end of file diff --git a/Communication/Identities/README.md b/Communication/Identities/README.md new file mode 100644 index 0000000..0f930d1 --- /dev/null +++ b/Communication/Identities/README.md @@ -0,0 +1,40 @@ +# Identities + +Connector identities according to this specification are comprised of a base identity, typically represented by an X.509 certificate, and some sort of token, typically an OAuth 2.0 JSON Web Token (JWT), see [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html), with a short lifetime. +This token contains statements about properties of the connector ("claims"), like its membership in one or more data spaces, and its Trust Level as well as its Assurance Level. +In order to establish trust via these tokens, two requirements have to be met: + +- Security-relevant claims within the token, or the entire token as a whole, MUST be signed by one or more trusted entities. +- There MUST exist a sound mechanism that enables connectors to proof ownership over the tokens or claims issued for a particular connector to peer connectors it is directly communicating with, as described below. +Specifically, any connector MUST also implement the corresponding validation mechanism in order to be capable of identifying and rejecting tokens that have not been issued for the connector(s) it assumes to be communicating with. + +## Mandatory Claims + +Each implementation of identity tokens MUST at least implement the following claims: + +- `securityProfile`: Reflects the `SecurityProfile` of the owning connector according to IDS certification criteria. +Valid values are `idsc:BASE_SECURITY_PROFILE`, `idsc:TRUST_SECURITY_PROFILE` and `idsc:TRUST_PLUS_SECURITY_PROFILE` as given by the members of https://international-data-spaces-association.github.io/InformationModel/docs/index.html#SecurityProfile. +Any other value denotes the absence of a security profile. +- `extendedGuarantee`: Reflects extended security features or properties that go beyond the requirements of the connector's `SecurityProfile`. +The claim MUST NOT contain any property that reflects a security level lower than the requirements of the stated `SecurityProfile`. +The claim MAY contain one or more values represented by members of `SecurityGuarantee` subclasses. +For a comprehensive list, see https://international-data-spaces-association.github.io/InformationModel/docs/index.html#SecurityGuarantee. + +## X.509/OAuth2-Token-based Identities +Identities of this kind are established via X.509 certificates and corresponding private keys. +The tokens used to provide identity information to other peers are regular OAuth 2.0 JWTs (see [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html)). +In the IDS context, the OAuth 2.0 server (see [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html)) issuing such tokens is called a "Dynamic Attribute Provisioning Server", or DAPS for short. + +### Format and Signature +The format of Dynamic Attribute Tokens (DATs) and the interaction between DAPS and connector are described in the [DAPS Specification](../../Components/IdentityProvider/DAPS/README.md). +As DATs are JWTs with a (RSA) signature, the issuing DAPS acts as a central, trusted entity, which also manages the contained claims about the connector. + +### Token Ownership Verification +The ownership over DAPS tokens is proven to peer connectors via ownership of a private key used for transport encryption, typically an RSA key belonging to a X.509 certificate. + +For typical TLS encryption scenarios, the respective approach via the `transportCertsSha256` claim is documented in the [DAPS Token Response Specification](../../Components/IdentityProvider/DAPS/README.md#token-response). +This claim is specified to contain an array of SHA256 fingerprints as hex-encoded strings, or a single such hash as a string. +As per that specification, DAPS implementations SHOULD allow the `transportCertsSha256` claim to be overridden with a dynamic value when requesting the DAT. +For non-TLS encrypted communication channels, hashes of corresponding public keys or their very values (e.g. for short representations of EC keys) MAY be used instead. + +For verification, a connector MUST check that the fingerprint of its peer's certificate is contained in - or equal to - the value of the `transportCertsSha256` claim. diff --git a/Infomodel/Message/DescriptionRequestMessage_POST.md b/Communication/Infomodel/Message/DescriptionRequestMessage_POST.md similarity index 100% rename from Infomodel/Message/DescriptionRequestMessage_POST.md rename to Communication/Infomodel/Message/DescriptionRequestMessage_POST.md diff --git a/Infomodel/Message/README.md b/Communication/Infomodel/Message/README.md similarity index 100% rename from Infomodel/Message/README.md rename to Communication/Infomodel/Message/README.md diff --git a/Infomodel/Message/requests/README.md b/Communication/Infomodel/Message/requests/README.md similarity index 100% rename from Infomodel/Message/requests/README.md rename to Communication/Infomodel/Message/requests/README.md diff --git a/Infomodel/README.md b/Communication/Infomodel/README.md similarity index 100% rename from Infomodel/README.md rename to Communication/Infomodel/README.md diff --git a/Communication/Message-Structure/README.md b/Communication/Message-Structure/README.md index 67f57dd..66dcc1c 100644 --- a/Communication/Message-Structure/README.md +++ b/Communication/Message-Structure/README.md @@ -43,8 +43,8 @@ A Connector has following properties, which are used for it's self-description. |host† |Network host of the Connector capable of serving / consuming Digital Contents and services| |defaultHost |Default host that should be used for basic infrastructure interactions, e.g., providing the self description| |authInfo |Information of the authentication service used by the Connector (e.g., to access a Connector’s data)| -|securityProfile |Set of security guarantees claimed by a Connector. Value contains one of the default security profile codes, such as idsc:BASE_CONNECTOR_SECURITY_PROFILE. All profiles can be found here: https://github.com/International-Data-Spaces-Association/InformationModel/blob/develop/codes/SecurityGuarantee.ttl Valid attributes are: idsc:BASE_SECURITY_PROFILE idsc:TRUST_SECURITY_PROFILE idsc:TRUST_PLUS_SECURITY_PROFILE| -|extendedGuarantee |Reference to additional security guarantees that, if used in combination with a security profile instance, overrides the respective guarantee of the given predefined instance. Value is a pre-defined code for the claimed guarante, e.g., ids:USAGE_CONTROL_POLICY_ENFORCEMENT| +|securityProfile |Set of security guarantees claimed by a Connector. Value contains one of the default security profile codes, such as idsc:BASE_CONNECTOR_SECURITY_PROFILE. All profiles can be found here: https://international-data-spaces-association.github.io/InformationModel/docs/index.html#SecurityProfile Valid attributes are: idsc:BASE_SECURITY_PROFILE idsc:TRUST_SECURITY_PROFILE idsc:TRUST_PLUS_SECURITY_PROFILE| +|extendedGuarantee |Reference to additional security guarantees that, if used in combination with a security profile instance, overrides the respective guarantee of the given predefined instance. Value is a pre-defined code for the claimed guarante, e.g., ids:USAGE_CONTROL_POLICY_ENFORCEMENT, see subclass members of https://international-data-spaces-association.github.io/InformationModel/docs/index.html#SecurityGuarantee for a full list| |transportCertSha256† |SHA256 fingerprints of currently valid transport certificates| |componentCertification |Certification issued for the given Connector. Value is an instance of class ids:ComponentCertification| |publicKey |Public Key that has been created for the Connector| diff --git a/Communication/images/Communicatoin-Guide_Dataspace_entities.png b/Communication/images/Communicatoin-Guide_Dataspace_entities.png new file mode 100644 index 0000000..c339533 Binary files /dev/null and b/Communication/images/Communicatoin-Guide_Dataspace_entities.png differ diff --git a/Communication/images/CommunicatoinGuide_Dataspace_entities.drawio b/Communication/images/CommunicatoinGuide_Dataspace_entities.drawio new file mode 100644 index 0000000..9809619 --- /dev/null +++ b/Communication/images/CommunicatoinGuide_Dataspace_entities.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/Communication/images/catalog-connector-interaction.png b/Communication/images/catalog-connector-interaction.png new file mode 100644 index 0000000..bcb31d8 Binary files /dev/null and b/Communication/images/catalog-connector-interaction.png differ diff --git a/Communication/images/catalog-query-interaction.png b/Communication/images/catalog-query-interaction.png new file mode 100644 index 0000000..1d3667f Binary files /dev/null and b/Communication/images/catalog-query-interaction.png differ diff --git a/Communication/images/catalog-request-connector-interaction.png b/Communication/images/catalog-request-connector-interaction.png new file mode 100644 index 0000000..43a3f8c Binary files /dev/null and b/Communication/images/catalog-request-connector-interaction.png differ diff --git a/Communication/images/catalog-request-resource-interaction.png b/Communication/images/catalog-request-resource-interaction.png new file mode 100644 index 0000000..d01edb0 Binary files /dev/null and b/Communication/images/catalog-request-resource-interaction.png differ diff --git a/Communication/images/catalog-resource-interaction.png b/Communication/images/catalog-resource-interaction.png new file mode 100644 index 0000000..11d52b4 Binary files /dev/null and b/Communication/images/catalog-resource-interaction.png differ diff --git a/Communication/images/connector-broker-interactions.drawio b/Communication/images/connector-broker-interactions.drawio new file mode 100644 index 0000000..28008a6 --- /dev/null +++ b/Communication/images/connector-broker-interactions.drawio @@ -0,0 +1 @@ +7V1bc6M2FP4tffBM98EZ7rYfN8lutzPdabvbdttHxci2GoxcISfx/vpKRsIgAb5xMTZ5CUgCxLnpO0eH44H9sHz7iYDV4jP2YTCwDP9tYD8OLMt0PY/94y0b0WI4RtwyJ8gXbbuGr+g7lANF6xr5MMoMpBgHFK2yjVMchnBKM22AEPyaHTbDQfapKzCHWsPXKQj01m/Ip4u4dewau/ZPEM0X8smmIXqewPR5TvA6FM8LcQjjniWQtxFDowXw8Wuqyf4wsB8IxjQ+Wr49wIDTVVIsvu5jQW8yZQJDesgFP00N9O35ZW69OstRtAJ/uf+GQye+ywsI1oIUDzGJMfkDLleYAIKCzZ8heAEoAE8B/BzN78T70I0kH/QZNcUpJnSB5zgEwYdd6/2WRJDPxGBnuzG/YLxijSZr/BdSuhGiAdYUs6YFXQail70k2fwtrt+e/MNP7ixXnj++pXsfN/LsDdG/5U3Ycfoydrq7ip/Ii+I35K9VSGzRFOE1mYpRIzB2pvBpavpw5rnO0BKSDMgc0hIm2Ik0MA2DeAnZ/Nl1BAaAopfsFICQ9HkybsdydiC4foQETIolIMv2drl+52b4vofpzfJv3BD/CuaXYt1XCig7fD+wvIDN+P6JsKM5P0qY+gXOUUQhYWxRGcos1IofwjeaYZ6ZZcrrAlH4dQW2ZHtlKwLvxgR9xyEFctALJBQxA/s+QPOQtS2R729lopAT/Ar4lmrSKSp6LdeNLxHLzURY2Ned6Tal1V2kzPbYqJ4HtleiPyufsaMSi5kif47G5GpWkcXcZzAPUpVcPRjp+lIgsopmnqE74tLfMGKzTSTEMzICYtoK5+NXERcpzE9mcbpN1RWzDpk4z56OjjKochVNrZz/pLoaXkVzh+hClKDR+A5nypTpZa2OOTpMqN4TAjapYSs+ICp+DoOdmec4CqxThttO2XB2ED9fuVhOBs9mEaxFB9xW5FuKaQbsjcrBXqIUZtZQjg6zlMfKdzEEPEnIz5Rqx1Kk2lWkOp7SEVJdtSCdvsD+Ap6Yo5oRECDgyJRxCJIynEJghL5z6CuYLV6Q3dy9H7iPCfs12JJ4qeLiQeIBpgWjWGcKYY9xZ9pOhlnSNp4qA5VagU/+r3/8PrMfvZdfv70sgfctwpMYGmeYJ6Epe+cwwzLvvzV3he+nOMBki2ENMn/6kdGOPdqQ/95tCc88/JAOZ2DJnNN46CcYvEDOyVR/tDUTvNc0V2/pjvihvCfEZMlBa9L3wjxewP4zeQB0TXhUonTcFKyKhrwK7Mk7HSO2GEbADBgkQ/b6UxTO9SsxWS1AKG5pxW1MwOhQiC5vTqRX9iFmNkPxJEO+6raHEnazGbu/fFIYg3AOlrdhk9RjXjHxsxNL7sXe5ekZsdvxe0aU4Gc4FHA7M24XDxkqfNyCds7C9MG71Ex9OMWEiTEOh3SBps8hjMT0UIgokvRRx6Z4WTouNZ3MuFmAAVWJ46NoFYCNHB4gHtUxfkA8IkIBp/T9TmA1F0uKONOYWMrj/l7ye8m/TslPBYp62e9l/6ZkP0afBULfooevODN7w+Sh/55vpHBsHIAoQtO48SMKNOfqLh0CkD1VhgAOdZFqicae5LR7k6wbZbl7vHbbKBufddur8qRsDYwfFS8e6qPu1/TnEEy3dK0wmlzoWWlyU+gseXZ7MeKy4GjGE1LNQxCgVcTNwIxp3UNsuliHbWz/+PK5tcGyJ7FcZ1NLDQKYnkYtO4dYali1MmLluY2FxEoJUyJzoS9EO0PKDPmqoJttKGosHfS2CGfrG7o99Oqh13VCry8wBg3pMODlAbGjExb2I7EqUdXBSQoFWQrCEg6NO8eTN6sXa5nKauWY5Vhrz/j2tkgkuTqBCRwJqBpY2nJDyTqAkvqv49KLSlg6LnXlKEds1I4nluOK5bKsfD+DmQzmBo2aMBmOk8VpzqTcZLjj0vEtmgzdh8vTghyUpwI0RyAIfVGtIz+IP12oiulUhL3dLI/sJl28XHHXzfkGRpeEPSqAHhFTeioHicUmPzBUR25ILtkPDQztRzD2yHROMUdN7qjq2+EhvjIZq1c2Tlup1HjS0Gxi3bKM7FPd0Z51yysd38i6VcaHMqRLFnj5tI6qWRzMkYJePX1x8HLWBq+utaGPy/RxmVuJy2iJECnHrEuhmiOWMomELmrDLCe0U2ycK88sVJL0pQu1L11WXwO18I2bvVFBhmJVS5e7f+m6iL0Ibe13m9vEySWcaXdUmRvApab8ynGfbprWmcp5Hgt12PIIoylBK76UfIH/rWFEP7P1Cczhj4nZH/755ed3uby/5IzcEhkucwxMc5JRu5NC4E1CcSl6nYg6e2MdtzdrxI6K0bdo/j3j0ijXzhcg3TD/OZ/K5Q9s6tvS/KfrwaZi8y/j0Ndk/feGhbpn/buUhzTKido0a8O6koikWv/2KTfprX8RbaxDwb/VKviXZjIl/L+vIdkIg38lJn5ydSbe6hLAHzstGypJnM6Z+PYpp2/q9MWDKl4p3ANXCvvcOhrnSUJJGalbKyJ0Jh+bqgVVOs08Pl50etHh5YdqSERqsxxRPhuvtCZRNRkh1oGqaBU4/50pTZT/Vrr/39cmasi4F0lUX6eoxcwka9yKsHegUFEJ0GzPfF5UvaL8Fy+rqNndgkUlylOIjLpYscjWo159pl6fqXcjmXp92ZZe8m9C8vuSRb3s36rsX2r6dZdLFp3nLJ0d9j3Jg7+0okWlNKwxJl1HCaMa4sxtljQqDaV2YqO5yZpGJTregY3mNosa5X87l/cJRqz57AGA44wFIJGwsFK713TG60ipyt4OrLN6WNc2rHPGAs05EwnrjKuCdVO+AYoY68r9mYLFcgV8X6f7kiEXFCqNvYb0GtKchvQGvBfPCxbPCg048vl8k3o+9sdDnXQaOyi5mTE7HFkFplZcEEfuNad9EDMHG6q7dNVhw5J8hguvCzY4JsfhmFiH1fGqYObEFZvy524Wq2W8rMNSIfRIiRL5cC37bpL6G2dvW7AHfcg25rExHFt5RdfeVyFmUja+nhiOm+f6dsuB6+Pyra//Vx+XVyv5HefA9WLfYbG/ef+qF7Tevja459+NLdA9ToG6x3RZTkK+uzauykkwPPn9Wb2bpCPF5d0LsCfm4QBbT97Ozr6+NEe3L0jYG/5bMfx9mmMv+bcp+Z2DPHuzvs4CPbX/XkKdoIdhNk+Ci5oxj5IY5o7MQzBM/ajF0evxVPzzBx3JBRspxSDa//EDp52CP139ji7PJhz1qwXnVuc11Z28qr6j0zdP1C8/ncmdYxrJnzL3mj+AljuRt/B5nlNe3KiLn+e5es5pXtGZLm39XlQZmvO2dp1KfnxX3+RU8Ihqqw7exnXL73NyJXF2SjDHEbvhbOlffMY+Nxgf/gc=dZHBDoMgDIafhrvCou7s3Lzs5GFnIp2QoDXIotvTT4PMEbcT5ev/U9oSlrfTxfBeXlGAJjQSE2EnQmkcxdl8LOTpSJIeHGiMEqtoA5V6gXeu9KEEDIHQImqr+hDW2HVQ24BxY3AMZXfUYdWeN7ADVc31nt6UsNLRjKYbL0E10leOk6PLtNyL104GyQWOX4gVhOUG0bqonXLQy/D8XJzv/Cf7+ZiBzv4wzMH29nwJNsSKNw== \ No newline at end of file diff --git a/Components/IdentityProvider/DAPS/README.md b/Components/IdentityProvider/DAPS/README.md index 43efc6c..f2f1ded 100644 --- a/Components/IdentityProvider/DAPS/README.md +++ b/Components/IdentityProvider/DAPS/README.md @@ -116,8 +116,8 @@ Contains the public keys of the used transport certificates, hashed using SHA256 The identifying X509 certificate should not be used for the communication encryption. Therefore, the receiving party needs to connect the identity of a connector by relating its hostname (from the communication encryption layer) and the used private/public key pair, with its IDS identity claim of the DAT. -The public transportation key must be one of the `transportCertsSha256` values. -Otherwise, the receiving connector must expect that the requesting connector is using a false identity claim. +The public transportation key MUST be one of the `transportCertsSha256` values. +Otherwise, the receiving connector MUST expect that the requesting connector is using a false identity claim. In general, this claim holds an Array of Strings, but it may optionally hold a single String instead if the Array would have exactly one element. * **extendedGuarantee** @@ -189,7 +189,7 @@ DAPS implementations are advised to explicitly white-list any requestable claims and to check requested values as appropriate. To allow clients to specify their own transport certificates, -DAPS implementations should support specifying values for the **transportCertsSha256** claim. +DAPS implementations SHOULD support specifying values for the **transportCertsSha256** claim. ### Example diff --git a/Specifications/README.md b/Specifications/README.md new file mode 100644 index 0000000..3938f1b --- /dev/null +++ b/Specifications/README.md @@ -0,0 +1,13 @@ +# Getting Started + +The [Information Model document](./model/information.model.md) defines the core concepts, entities, and relationships that underpin a `Dataspace`. + +The [Catalog Protocol document](./catalog/catalog.protocol.md) defines a how a `Catalog` is requested from a catalog service by a consumer using an abstract message exchange format. + +The [Catalog Binding document](./catalog/catalog.binding.https.md) defines a RESTful API over HTTPS for the `Catalog Protocol`. + +The [Bibliography](./notes/bibliography.md) contains links to relevant standards referenced by the above documents. + +Note that PlantUML diagrams will be replaced by Draw-IO alternatives. + + diff --git a/Specifications/catalog/catalog.binding.https.md b/Specifications/catalog/catalog.binding.https.md new file mode 100644 index 0000000..164daf0 --- /dev/null +++ b/Specifications/catalog/catalog.binding.https.md @@ -0,0 +1,134 @@ +# Catalog HTTPS Binding + +## 1 Introduction + +This specification defines a RESTful API over HTTPS for the [Catalog Protocol]. + +The OpenAPI definitions for this specification can be accessed [here](TBD). + +## 2 Path Bindings + +### 2.1 Prerequisites + +1. The `` notation indicates the base URL for a catalog service endpoint. For example, if the base catalog URL is `api.example.com`, the URL `https:///catalog/request` + will map to `https//api.example.com/catalog/request`. + +2. All request and response messages must use the `application/json` media type. + +### 2.2 CatalogErrorMessage + +In the event of a request error, the catalog service must return an appropriate HTTP code and a [CatalogErrorMessage](./catalog.protocol.md#) in the response body. + +| Field | Type | Description | +|---------|---------------|-------------------------------------------------------------| +| code | string | An optional implementation-specific error code. | +| reasons | Array[object] | An optional array of implementation-specific error objects. | + +### 2.3 The `catalog/request` endpoint + +#### 2.3.1 POST + +The [CatalogRequestMessage](catalog.protocol.md#1-catalogrequestmessage) corresponds to `POST https:///catalog/request`: + +``` +POST https://provider.com/catalog/request + +Authorization: ... + +{ + "@context": { + "ids": "https://idsa.org/" + }, + "@type": "ids:CatalogRequest" + "ids:filter": {} +} +``` + +The `Authorization` header is optional if the catalog service does not require authorization. If present, the contents of the `Authorization` header are detailed in the +[Authorization section](#authorization). + +The `filter` property is optional. If present, the `filter` property can contain an implementation-specific filter expression or query to be executed as part of the catalog +request. + +#### 2.3.2 OK (200) Response + +If the request is successful, the catalog service must return a response body containing a [CatalogMessage](./message/catalog.message.json) which is a profiled DCAT Catalog type +described by the [Catalog Protocol Specification](catalog.protocol.md). + +## 3 Technical Considerations + +### 3.1 Authorization + +A catalog service may require authorization. If the catalog service requires authorization, requests must include an HTTP `Authorization` header with a token. The contents of +the token are undefined by may be an OAUTH2, Web DID, or other access token type. + +### 3.2 Versioning + +- Versioning will be done via URLs. TBD. + +### 3.3 Pagination + +A catalog service may paginate the results of a `CatalogRequestMessage`. Pagination data is specified using [Web Linking](https://datatracker.ietf.org/doc/html/rfc5988) +and the HTTP `Link` header. The `Link` header will contain URLs for navigating to previous and subsequent results. The following request sequence demonstrates pagination: + +``` +Link: ; rel="next" +{ + "@context": { + "dcat": "http://www.w3.org/ns/dcat/" + }, + "@type": "dcat:Catalog" + ... +} + +``` + +Second page response: + +``` +Link: ; rel="previous" +Link: ; rel="next" + +{ + "@type": "dcat:Catalog" + ... +} +``` + +Last page response: + +``` +Link: ; rel="previous" + +{ + "@type": "dcat:Catalog" + ... +} +``` + +### 3.4 Compression + +Catalog services MAY compress responses to a catalog request by setting the `Content-Encoding` header to `gzip` as described in +the [HTTP 1.1 Specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-gzip-coding). + +## 4 Notes + +### 4.1 Asynchronous Interactions + +We may want to specify optional support for asynchronous callbacks for the catalog response. This would require addling a `callbackAddress` property and an `@id` to the request: + +``` +POST https://provider.com/catalog/request + +Authorization: ... + +{ + "@context:{}, + "@type": "ids:CatalogRequest" + "@id: "..." + "ids:callbackAddress": "https://example.com/endpoint" +} +``` + +The `CatalogResponseMessage` would be POSTed back to the endpoint. the response message could be posted mutiple times for paginated results and would need to include the +original `@id` value as a `correlationId` and a property indicating if the contents are complete (or additional responses will be sent). diff --git a/Specifications/catalog/catalog.protocol.md b/Specifications/catalog/catalog.protocol.md new file mode 100644 index 0000000..6417dba --- /dev/null +++ b/Specifications/catalog/catalog.protocol.md @@ -0,0 +1,131 @@ +# Catalog Protocol + +## 1 Introduction: Terms + +This document outlines the catalog protocol. The following terms are used: + +- A _**message type**_ defines the structure of a _message_. +- A _**message**_ is an instantiation of a _message type_. +- A _**catalog**_ is a [DCAT catalog](https://www.w3.org/TR/vocab-dcat-3/) offered by a _provider_ +- a _**catalog service**_ is a provider participant agent that advertises offered assets +- A _**consumer**_ is a participant agent that requests access to an offered asset. + +The catalog protocol defines a how a `Catalog` is requested from a catalog service by a consumer using an abstract message exchange format. The concrete message exchange wire +format is defined in binding specifications. + +## 2 Message Types + +All messages must be serialized in JSON-LD compact form as specified in the [JSON-LD 1.1 Processing Algorithms and API](https://www.w3.org/TR/json-ld11-api/#compaction-algorithms). +Future IDS specifications may define additional optional serialization formats. + +### 2.1 CatalogRequestMessage + +**Sent by**: Consumer + +**Example**: + +``` +{ + "@context: { + "ids": "https://idsa.org/" + }, + "@type": "ids:CatalogRequest" + "ids:filter": {} +} +``` + +**Response**: [CatalogMessage](./message/catalog.message.json) containing the [DCAT catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog). + +**Schema**: (xx)[] + +#### Description + +The `CatalogRequestMessage` is message sent by a consumer to a catalog service. The catalog service must respond with a `CatalogMessage,` which is a +valid [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog). + +The `CatalogRequestMessage` may have a `filter` property which contains an implementation-specific query or filter expression type supported by the catalog service. + +The catalog service may require an authorization token. Details for including that token can be found in the relevant catalog binding specification. Similarly, pagination may +be defined in the relevant catalog binding specification. + +## 3 DCAT Vocabulary Mapping + +This section describes how the IDS Information Model maps to DCAT resources. + +### 3.1 Asset Entry + +An `Asset Entry` is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) with the following attributes: + +#### 3.1.1 dcat:haPolicy + +An asset entry Dataset may have 0..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset. Offers must NOT contain any +target attributes. The target of an offer is the asset associated with the containing asset entry. If an entry is has no associated policies (hasPolicy does not contain any offer +entries), the asset is does not have any usage control policy. + +### 3.2 Distributions + +An asset may contain 0..N [DCAT Distributions](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution). Each distribution must have at least one `DataService` which specifies where +the distribution is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `AssetTransfer`. + +### 3.3 DataService + +A DataService may specify an IDS service endpoint such as a `Connector`. + +#### 3.3.1 ids:dataServiceType + +If the DataService refers to an IDS service endpoint, it must include the property `ids:dataServiceType`: + +| Category | Description | +|------------|----------------------------------------------------------------------------| +| Definition | Specifies the IDS service type | +| Domain | [dcat:DataService](https://www.w3.org/TR/vocab-dcat-2/#Class:Data_Service) | +| Type | xsd:string | +| Note | The value of this field is left intentionally open for future extension. | + +The following table lists well-know IDS endpoint types: + +| Value | Description | +|---------------|----------------------| +| ids:connector | A Connector endpoint | +| | | + + +#### 3.3.2 dcat:servesDataset + +Note that the property `dcat:servesDataset` should be omitted from the `DataService` since `DataSets` are included as top-level entries. Clients are not required to process the +contents of `dcat:servesDataset`. + +## 4 Technical Considerations + +### 4.1 Queries and Filter Expressions + +A _**catalog service**_ may support catalog queries or filter expressions as an implementation-specific feature. However, it is expected that query capabilities will be implemented +by the consumer against the results of a `CatalogRequestMessage,` as the latter is an RDF vocabulary. Client-side querying can be scaled by periodically crawling provider catalog +services, caching the results, and executing queries against the locally-stored catalogs. + +### 4.2 Replication Protocol + +The catalog protocol is designed to be used by federated services without the need for a replication protocol. Each consumer is responsible for issuing requests +to 1..N catalog services, and managing the results. It follows that a specific replication protocol is not needed, or more precisely, each consumer replicates data from catalog +services by issuing `CatalogRequestMessages`. + +The discovery protocol adopted by a particular dataspace defines how a consumer discovers catalog services. + +### 4.3 Security + +It is expected (although not required) that catalog services implement access control. A catalog as well as individual catalog _datasets_ may be restricted to trusted parties. +The catalog service may require consumers to include a security token along with a `CatalogRequestMessage.` The specifics of how this is done can be found in the relevant +catalog binding specification. In addition, this specification does not define the contents of the security token. It is expected different security mechanisms may be used such +as [OAuth2 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-06) or [did:web](https://w3c-ccg.github.io/did-method-web/). + +### 4.4 Catalog Brokers + +A dataspace may include _**catalog brokers**_. A catalog broker is a consumer that has trusted access to 1..N upstream catalog services and advertises their respective catalogs as +a single catalog service. The broker is expected to honor upstream access control requirements. + +## 5 DCAT and ODRL Profiles + +The catalog is a DCAT catalog with the following restrictions: + +1. Each ODRL `Offer` must be unique to a dataset since the target of the offer is derived from its enclosing context. +2. Each ODRL `Offer` must NOT include an explicit `target` attribute. diff --git a/Specifications/catalog/message/catalog.error.message.json b/Specifications/catalog/message/catalog.error.message.json new file mode 100644 index 0000000..0147e7f --- /dev/null +++ b/Specifications/catalog/message/catalog.error.message.json @@ -0,0 +1,11 @@ +{ + "@context": { + "ids": "https://idsa.org/" + }, + "@type": "ids:CatalogErrorMessage", + "code": "123:A", + "reasons": [ + {}, + {} + ] +} diff --git a/Specifications/catalog/message/catalog.message.json b/Specifications/catalog/message/catalog.message.json new file mode 100644 index 0000000..8f2b7b8 --- /dev/null +++ b/Specifications/catalog/message/catalog.message.json @@ -0,0 +1,71 @@ +{ + "@context": { + "dcat": "http://www.w3.org/ns/dcat/", + "dct": "http://purl.org/dc/terms/", + "odrl": "https://www.w3.org/TR/odrl-model/", + "ids": "https://idsa.org/" + }, + "@id": "urn:uuid:3afeadd8-ed2d-569e-d634-8394a8836d57", + "@type": "dcat:Catalog", + "dct:title": "Data Provider A Catalog", + "dct:description": "A catalog of data items", + "dct:publisher": "Data Provider A", + "dcat:keyword": [ + "traffic", "government" + ], + "dcat:DataService": [ + { + "@id": "urn:uuid:4aa2dcc8-4d2d-569e-d634-8394a8834d77", + "@type": "dcat:DataService", + "dct:terms": "ids:connector", + "dct:endpointUrl": "https://provder-a.com/connector" + } + ], + "dcat:dataset": [ + { + "@id": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88", + "@type": "dcat:Dataset", + "dct:title": "Traffic Data", + "dct:description": "Traffic data sample extract", + "dcat:keyword": [ + "traffic" + ], + "dcat:hasPolicy": [ + { + "@context": { + "@vocab": "https://www.w3.org/TR/odrl-model/" + }, + "uid": "urn:uuid:2828282:3dd1add8-4d2d-569e-d634-8394a8836a88", + "permissions": [ + { + "action": "use", + "constraints": [ + { + "leftExpression": { + "@value": "spatial" + }, + "rightExpression": { + "@value": "EU" + }, + "operator": "EQ" + } + ], + "duties": [] + } + ], + "prohibitions": [], + "obligations": [] + } + ], + "dcat:distribution": [ + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "ids:s3+push" + }, + "dcat:accessService": "urn:uuid:4aa2dcc8-4d2d-569e-d634-8394a8834d77" + } + ] + } + ] +} diff --git a/Specifications/catalog/message/catalog.request.message.json b/Specifications/catalog/message/catalog.request.message.json new file mode 100644 index 0000000..b3ed3d8 --- /dev/null +++ b/Specifications/catalog/message/catalog.request.message.json @@ -0,0 +1,7 @@ +{ + "@context": { + "ids": "https://idsa.org/" + }, + "@type": "ids:CatalogRequestMessage", + "ids:filter": {} +} diff --git a/Specifications/diagrams/diagram.styles.puml b/Specifications/diagrams/diagram.styles.puml new file mode 100644 index 0000000..911f758 --- /dev/null +++ b/Specifications/diagrams/diagram.styles.puml @@ -0,0 +1,83 @@ + + +!$blue = "#066DFA" +!$gray = "#98A3AB" +!$lightGray = "#F4F5F9" +!$darkGray = "#747C94" +!$green = "#24DCC1" +!$blueFill = "#E4EBFA" +!$greenFill = "#CFFBDE" +!$borderRed = "#F40000" +!$lightRed = "#FDCCCC" + +skinparam sequence { +ArrowColor Black +LifeLineBorderColor 000000 +LifeLineBackgroundColor #A9DCDF +} + +skinparam roundCorner 10 + +skinparam ArrowColor $darkGray +skinparam ArrowHeadColor $darkGray +skinparam LifeLineBackgroundColor $darkGray + + +skinparam CloudBackgroundColor $lightGray +skinparam CloudBorderColor $gray +skinparam CloudFontColor Black + +skinparam ArtifactBackgroundColor $lightGray +skinparam ArtifactBorderColor $gray + +skinparam ComponentBackgroundColor $blueFill +skinparam ComponentBorderColor $blue +skinparam ComponentFontColor Black + +skinparam DatabaseBackgroundColor $greenFill +skinparam DatabaseBorderColor $green +skinparam DatabaseFontColor Black + +skinparam ParticipantBorderColor $blue +skinparam ParticipantBackgroundColor $blueFill +skinparam SequenceGroupBorderColor #DADADA +skinparam SequenceGroupHeaderFontColor #898A89 +skinparam BoxPadding 20 +skinparam ParticipantPadding 10 + +skinparam AgentBackgroundColor White +skinparam AgentBackgroundColor $blueFill +skinparam AgentBorderColor #066DFA +skinparam noteBorderColor FEF3BF +skinparam SequenceBoxBorderColor F2F2F2 +skinparam shadowing false +skinparam AgentBorderThickness 1 + +skinparam NoteBackgroundColor FEFFDD + +skinparam FrameBackgroundColor $lightGray +skinparam FrameBorderColor $lightGray +skinparam FrameFontColor $darkGray + +skinparam ActivityBackgroundColor $blueFill + +skinparam StateBackgroundColor $blueFill +skinparam StateBorderColor $blue +skinparam StateStartColor $blue +skinparam StateEndColor $blue +skinparam StateFontSize 12 + +skinparam ActivityBackgroundColor $blueFill +skinparam ActivityBorderColor $blue +skinparam ActivityEndColor $blue +skinparam ActivityStartColor $blue +skinparam ActivityDiamondBackgroundColor $lightGray +skinparam ActivityDiamondBorderColor $blue + +skinparam PartitionBackgroundColor $lightGray +skinparam PartitionBorderColor $darkGray +skinparam PartitionFontColor $darkGray + +skinparam ClassAttributeFontColor Black +skinparam ClassBorderColor $blue +skinparam ClassBackgroundColor $blueFill diff --git a/Specifications/model/im.dataspace.relationships.png b/Specifications/model/im.dataspace.relationships.png new file mode 100644 index 0000000..607785e Binary files /dev/null and b/Specifications/model/im.dataspace.relationships.png differ diff --git a/Specifications/model/im.dataspace.relationships.puml b/Specifications/model/im.dataspace.relationships.puml new file mode 100644 index 0000000..1b88cce --- /dev/null +++ b/Specifications/model/im.dataspace.relationships.puml @@ -0,0 +1,33 @@ +@startuml +!pragma layout smetana + +!include ../diagrams/diagram.styles.puml + + +agent Participant +agent ParticipantAgent +agent CI as "Credential\nIssuer" +agent IDP as "Identity\nProvider" +agent Dataspace +agent DataspaceAuthority as "Dataspace\nAuthority" +agent Registry as "Dataspace\nRegistry" + +DataspaceAuthority -down-> Dataspace : manages + +Dataspace -down-> Registry: uses + +Participant -up-> Dataspace : member of +Participant -down-> ParticipantAgent : controls + +ParticipantAgent --> Registry : registers/uses + +IDP --> ParticipantAgent : issues +ParticipantAgent --> IDP : verifies + +CI --> ParticipantAgent : issues +ParticipantAgent --> CI : verifies + + + + +@enduml diff --git a/Specifications/model/im.participant.entities.drawio b/Specifications/model/im.participant.entities.drawio new file mode 100644 index 0000000..430f867 --- /dev/null +++ b/Specifications/model/im.participant.entities.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/Specifications/model/im.participant.entities.png b/Specifications/model/im.participant.entities.png new file mode 100644 index 0000000..ac1601a Binary files /dev/null and b/Specifications/model/im.participant.entities.png differ diff --git a/Specifications/model/information.model.md b/Specifications/model/information.model.md new file mode 100644 index 0000000..e91c514 --- /dev/null +++ b/Specifications/model/information.model.md @@ -0,0 +1,151 @@ +# Dataspace Information Model + +The information model defines the core concepts, entities, and relationships that underpin a `Dataspace`. + +## 1 Terminology + +### Dataspace + +A `Dataspace` is a set of technical services that facilitate interoperable asset sharing between entities. + +### DataspaceAuthority + +A `DataspaceAuthority` is an entity that manages a `Dataspace`. + +### Participant + +A `Participant` is a `Dataspace` member that provides and/or consumes assets. + +### ParticipantAgent + +A `ParticipantAgent` is a technology system that performs operations on behalf of a `Participant`. + +### IdentityProvider + +An `IdentityProvider` is a trusted technology system that creates, maintains, and manages identity information for a `Participant` and `ParticipantAgents`. + +### CredentialIssuer + +A `CredentialIssuer` is a trusted technology system that issues verifiable credentials for a `Participant` and `ParticipantAgents`. + +### ClearingHouse (TBD) + +A `ClearingHouse` is a trusted technology system that records and verifies domain events. + +### DataspaceRegistrationService + +A `DataspaceRegistrationService` is a technology system that maintains the state of `Participants` in a `Dataspace`. + +### Asset + +Data or a technical service that can be shared by a `Participant`. + +### Policy + +A set of rules, duties, and obligations that define the terms of use for an `Asset`. + +### Offer + +A concrete `Policy` associated with a specific `Asset`. + +### Agreement + +A concrete `Policy` associated with a specific `Asset` that has been signed by both the provider and consumer `Participants`. + +### Catalog + +A collection of entries representing `Assets` and their `Offers` that is advertised by a provider `Participant`. + +### CatalogService + +A `PariticipantAgent` that makes a `Catalog` accessible to `Participants`. + +### Connector (DataService) + +A `PariticipantAgent` that produces `Agreements` and manages `Asset` sharing. + +### Contract Negotiation + +A set of interactions between a provider `Connector` and consumer `Connector` that establish an `Agreement`. + +### Asset Transfer + +A set of interactions between a provider `Connector` and consumer `Connector` that give access to an `Asset` under the terms of an `Agreement`. + +## 2 Dataspace Information Model + +The following sections outline the Dataspace Information Model, which form the foundation of this specification. + +### 2.1 Dataspace Entity Relationships + +The relationships between the primary dataspace entities are defined as follows: + +![](./im.dataspace.relationships.png) + +Note that all relationships are multiplicities unless specified. + +- A `Dataspace Authority` manges one or more `Dataspaces`. This will include participant registration and may entail mandating business and/or requirements. For example, a + Dataspace Authority may require participants to obtain some form of business certification. A Dataspace authority may also impose technical requirements such as support for the + technical enforcements of specific usage policies. +- A `Participant` is a member of one or more `Dataspaces`. A participant registers `Participant Agents` that perform tasks on its behalf. +- A `Participant Agent` performs tasks such as publishing a catalog or engaging in an asset transfer. In order to accomplish these tasks, a participant agent may + use a _**verifiable presentation**_ generated from a _**credential**_ obtained from a third-party issuer. A participant agent may also use an _**ID token**_ issued by a + third-party identity provider. Note that a participant agent is a logical construct and does not necessarily correspond to a single runtime process. +- An `Identity Provider` is a trust anchor that generates `ID tokens` used to verify the identity of a `Participant Agent`. Multiple identity providers may operate in + a dataspace. The identity standard used by a provider is not defined but could be _OAuth2_ or _Decentralized Identifiers using did:web_. An identity provider may be a third-party + or a participant itself (for example, in the case of decentralized identifiers). +- A `Credential Issuer` issues _verifiable credentials_ used by participant agents to allow access to assets and verify usage control. + +The diagram below depicts the relationships between `ParticipantAgent` types: + +![](./im.participant.entities.png) + +- A `CatalogService` is a `Participant Agent` that makes a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) available to other participants. +- A `Catalog` contains one or more `Asset Entries`, which are [DCAT Datasets](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset). A `Catalog` also contains **_at least one_** + [DCAT DataService](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) that references a `Connector` where assets may be obtained. +- An `Asset Entry` has **one** `Offer`, which is an [ODRL Offer](https://www.w3.org/TR/odrl-model/#policy-offer) describing the _usage control policy_ associated with the asset. +- A `Connector` is a `Participant Agent` that performs `Contract Negotiation` and `Asset Transfer` operations with another connector. An outcome of a `ContractNegotiation` may + be the production of an `Agreement`, which is an [ODRL Agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) defining the _usage control policy_ agreed to for an asset. + +## 2.2 Classes + +Not all dataspace entities have a concrete _technical_ materialization; some entities may exist as purely logical constructs. For example, a `Dataspace Authority` +and `Participant Agent` have no representation in the protocol message flows that constitute dataspace interactions. This section outlines the classes that comprise the concrete +elements of the information model, i.e. those that are represented in protocol message flows. + +### 2.2.1 Catalog + +A `Catalog` is a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) with the following attributes: + +- 0..N `Asset Entries`. Since a catalog may be dynamically generated for a request based on the requesting participant's credentials it is possible for it to contain 0 matching + asset entries. (DCAT PROFILE) +- 1.N [DCAT DataService](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) that references a `Connector` where assets may be obtained. (DCAT PROFILE) + +### 2.2.1 Asset Entry + +An `Asset Entry` is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) with the following attributes: + +- 1..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset. **_Offers must NOT contain any target attributes. The + target of an offer is the asset associated with the containing asset entry._** (ODRL PROFILE) +- 1..N [DCAT Distributions](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution). Each distribution must have at least one `DataService` which specifies where the distribution + is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `AssetTransfer`. (DCAT PROFILE) + +### 2.2.1 Offer + +An `Offer` is an [ODRL Offer](https://www.w3.org/TR/odrl-model/#policy-offer) with the following attributes: + +- An ODRL `uid` that is a unique UUID. (ODRL PROFILE) +- The `Offer` must be unique to a dataset since the target of the offer is derived from its enclosing context. +- The `Offer` must NOT include an explicit `target` attribute. + +### 2.2.1 Agreement + +An `Agreement` is an [ODRL Agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) with the following attributes: + +- The `Agreement` class must include one `target` attribute that is the UUID of the asset the agreement is associated with. An agreement is therefore associated with **EXACTLY + ONE** asset. (ODRL PROFILE) + + + + + diff --git a/Specifications/notes/bibliography.md b/Specifications/notes/bibliography.md new file mode 100644 index 0000000..c483ea9 --- /dev/null +++ b/Specifications/notes/bibliography.md @@ -0,0 +1,23 @@ +# Bibliography + +## JSON-LD +- [JSON-LD](https://www.w3.org/TR/json-ld/) + +## DCAT +- [DCAT Working Group GitHub](https://github.com/w3c/dxwg) +- [DCAT Vocabulary WD](https://w3c.github.io/dxwg/dcat/) +- [Profile Guidance](https://w3c.github.io/dxwg/profiles/) +- [Profiles Vocabulary](https://w3c.github.io/dx-prof/prof/) +- [DCAT Vocabulary RDF](https://www.w3.org/ns/dcat2.ttl) + +## RFCs +- [Web Linking](https://datatracker.ietf.org/doc/html/rfc5988) +- [Linkset Media Types](https://www.rfc-editor.org/rfc/rfc9264.html) +- [JSON Web Signature (JWS)](https://www.rfc-editor.org/rfc/rfc7515) +- [JWK Thumbprint](https://www.rfc-editor.org/rfc/rfc7638#section-3) +- [JCS](https://www.rfc-editor.org/rfc/rfc8785) + +## IDS +- [IDS InfoModel](https://international-data-spaces-association.github.io/InformationModel/docs/index.html) +- [IDS GitHub InfoModel](https://github.com/International-Data-Spaces-Association/InformationModel) +