WIP: Identities

.gitignore

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

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]

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.

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
+<!--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 ##
+
+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

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

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|