55 update strcuture communication package

.gitignore

@@ -0,0 +1 @@
+.idea/

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
 ## 2022-09 
 
 ### Changed

Communication/CommunicationGuide.md

@@ -0,0 +1,212 @@
+# IDS Communication Guide #
+
+## Introduction ##
+
+This section is non normative.
+
+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.
+
+### Aims of the Communication Guide ###
+
+tbd
+
+### Conformance ###
+
+tbd
+
+### Structure of the document ###
+
+The remainder of the document is structures as follows:
+
+- Terms and Definitions
+- The foundation package contains the reusable structures and definitions:
+  - the basic strucutre of elements and their relationship (information model)
+  - standards that are used in the document
+  - a definition of digital identities and their interactions
+  - a definition of policies
+  - Trust Frameworks as a foundation to establish trust in a data space
+- Data Sharing
+  - Contract negotiation sequence
+  - Data Transfer
+- Catalog
+- Registration to a data space
+- Audit Logging and observability (currently out of scope)
+- Use of vocabularies (currently out of scope)
+
+![structure of IDS Communication Specification](./images/Structure_Commuication.png)
+
+The [Bibliography](./notes/bibliography.md) contains links to relevant standards referenced by the above documents.
+
+## Terms and Definitions ##
+
+Most important terms and definition are in the [Glossary](../Glossary/README.md)
+
+### 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
+
+#### General remarks on transactions and synchronized states ###
+
+**We should explain briefly on the requirements of state management and how we deal witt it in the remainder of the document.**
+
+- Good practice is correlation ID and go to TERMINATED state in case of error
+
+## 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 [Information Model document](./model/information.model.md) defines the core concepts, entities, and relationships that underpin a `Dataspace`.
+
+[The IDS-Information Model is the declarative model --> the Binding of the model above to rdf](./Infomodel/README.md)
+
+The general message structure is described [here](./Message-Structure/README.md).
+
+And the message types are listed [here](./Message-Types/README.md).
+
+And messages are part of the [IDS Infomodel](./Infomodel/Message/README.md).
+
+### Identities ###
+
+[This section](./Identities/README.md)
+
+While the API binding is [here](../Components/IdentityProvider/README.md).
+
+### Trust Frameworks ###
+
+[This section](./TrustFrameworks/README.md)
+
+### Policies (authorization and Policy Description) ###
+
+Policies in this context are the IDS Usage Contracts that are defined [here](../UsageControl/Contract/README.md)
+
+## Data Sharing (Connector) ##
+
+Data Sharing and the interaction between connectors focus on Contract Negotiation and Data Transfer
+
+### Contract Negotiation ###
+
+[This section](./ContractNegotiation/README.md)
+
+### Data Transfer ###
+
+part of the data plane. How data is exchanged with focus on communication and not on how the data plane is built.
+
+Bindings for the data exchange are described in the [protocols section](./protocols/README.md).
+
+- [IDS-REST](./protocols/ids-rest/README.md)
+- [Multipart](./protocols/multipart/README.md)
+- [IDSCP V2](./protocols/idscp2/README.md)
+
+## Catalog (Publish and query meta-data) ##
+
+**This section mixes old and new please review**
+
+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.
+
+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`.
+
+### 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
+<!--state machines for message flows and interaction patterns:-->
+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 ##
+
+[This section](./Registration/README.md)
+
+## Audit logging ##
+
+currently out of scope
+
+## Vocabularies ##
+
+currently out of scope

Communication/ContractNegotiation/README.md

@@ -0,0 +1 @@
+to be added 

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)

Communication/Identities/README.md

@@ -0,0 +1,40 @@
+# Identities
+
+Connector identities according to this specification are typically represented by some sort of token.
+This token contains statements about properties of the connector ("claims"), like its membership in one or more data spaces.
+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 a connector to proof ownership over the tokens or claims issued for this particular connector.
+Specifically, any connector implementing a corresponding validation mechanism MUST be capable of identifying and rejecting tokens that have not been issued for the respective peer connector(s).
+
+## 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 OAuth2 JSON Web Tokens (JWTs).
+In the IDS context, the OAuth2 server 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.

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|