63 communication guide identities (#83)

* Issue 46: Bugfix adding necessary JSON-LD context elements (#49)

* Bugfix adding necessary JSON-LD context elements



Co-authored-by: Sebastian Steinbuss <23654606+ssteinbuss@users.noreply.github.com>

* First identity token draft

* Added mandatory claims section

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>
Co-authored-by: Michael Lux <michael.lux@aisec.fraunhofer.de>

CHANGELOG.md

@@ -6,10 +6,14 @@ 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
 - fixed missing mandatory elements in multipart message
 - Fixed wrong references to IDS-G-pre and RAM in CONTRIBUTING.md
 
+
 ## [Q2/2022]
 
 ### Added

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|

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