Skip to content

Commit

Permalink
Korrekturen
Browse files Browse the repository at this point in the history
  • Loading branch information
@BenediktSR
BenediktSR authored Nov 22, 2023
1 parent 10571bb commit ef30445
Showing 1 changed file with 75 additions and 43 deletions.
118 changes: 75 additions & 43 deletions docs/policies/policies.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
# General Information about Policies
# Policies in Catena-x

## General Information about Policies

>ℹ️ All explanations in this chapter "General Information about Policies" were taken from the following [source](https://w3c.github.io/poe/model/).
## Introduction
### Introduction

Several business scenarios require expressing what are the permitted and prohibited actions over resources. These permitted/prohibited actions are usually expressed under the form of policies, i.e., expressions that indicate those uses and re-uses of the content which are conformant with existing regulations or to the constraints assigned by the owner. Policies may also be enriched with additional information, i.e., who are the entities in charge of the definition of such Policy and those who are required to conform to it, what are the additional constrains to be associated with the Permissions, Prohibitions and Duties expressed by the Policy. The ability to express these concepts and relationships is important both for the producers of content, i.e., they may state in a clear way what are the permitted and the prohibited actions to prevent misuse, and for the consumers, i.e., they may know precisely what resources they are allowed to use and re-use to avoid breaking any rules, laws or the owner's constraints. This specification describes a common approach to expressing these policy concepts.

## Semantic Model
### Semantic Model

The ODRL Information Model defines the underlying semantic model for permission, prohibition, and obligation statements describing content usage. The information model covers the core concepts, entities and relationships that provide the foundational model for content usage statements. These machine-readable policies may be linked directly with the content they are associated to with the aim to allow consumers to easily retrieve this information.

### Most Important Terminology
#### Most Important Terminology

| Term | Description |
| -------- | -------- |
| Policy | A group of one or more Rules
Expand All @@ -19,11 +24,11 @@ The ODRL Information Model defines the underlying semantic model for permission,
| Prohibition | The inability to exercise an Action over an Asset
| Constraint | A boolean/logical expression that refines an Action and Asset collection or the conditions applicable to a Rule.

## Policies in Catena-X


# Policies in Catena-X
A Catena-X policy uses the ODRL Information Model as a semantic model. Theoretically, a policy can be constructed individually using this ODRL Information Model. Catena-X does not yet use all the possibilities that ODRL provides, so the next example will show how a Catena-X policy is basically structured.
## Policy Template Example with @context: `"http://www.w3.org/ns/odrl.jsonld"`

### Policy Template Example with @context: `"http://www.w3.org/ns/odrl.jsonld"`

{
"@context": {},
Expand Down Expand Up @@ -51,15 +56,16 @@ A Catena-X policy uses the ODRL Information Model as a semantic model. Theoretic

| Variable | Content |
| -------- | -------- |
| "@id" | A Policy MUST have one uid property value (of type IRI) to identify the Policy. |
| policy "@type" | A Set Policy is the default Policy subclass. The Set is aimed at scenarios where there is an open criteria for the semantics of the policy expressions and typically refined by other systems/profiles that process the information at a later time. No privileges are granted to any Party (if defined). More detailed information about the possible policy subclasses can be found [here](https://w3c.github.io/poe/model/#infoModel) |
| policy "@context" | The context here is always "http://www.w3.org/ns/odrl.jsonld". This allows the odrl: prefix to be omitted. |
| "@id" | A Policy MUST have one uid property value (of type IRI) to identify the Policy. |
| policy "@type" | A Set Policy is the default Policy subclass. The Set is aimed at scenarios where there is an open criteria for the semantics of the policy expressions and typically refined by other systems/profiles that process the information at a later time. No privileges are granted to any Party (if defined). More detailed information about the possible policy subclasses can be found [here](https://w3c.github.io/poe/model/#infoModel) |
| policy "@context" | The context here is always "<http://www.w3.org/ns/odrl.jsonld>". This allows the odrl: prefix to be omitted. |
| policy "permission" | A Policy MUST have at least one permission, prohibition, or obligation property values.
| policy permission "action" | "use" the target Asset (under a specific permission), currently only the action "use" is used by Catena-X |
| policy permission "constraint" | A boolean/logical expression that refines an Action and Party/Asset collection or the conditions applicable to a Rule. <br> <br> The leftOperand instances MUST clearly be defined to indicate the semantics of the Constraint. Catena-X will use the **left operand** of a *constraint* to associate a specific verifiable credential (VC). The left operand value will correspond to the form: [VC type].[subtype] <br> **Right Operand:** The rightOperand is the value of the Constraint that is to be compared to the leftOperand. <br> <br> All possible `Catena-X constraints` can be found here: [https://github.com/eclipse-tractusx/ssi-docu](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md)
## Policy Template Example with @context: ` "odrl": "http://www.w3.org/ns/odrl/2/"`
There is another possibility of representation: in the example above, `"@context": "http://www.w3.org/ns/odrl.jsonld"` was defined, so it is not necessary to always write `odlr:xy`. If this is not defined, the policy must look like this:
| policy permission "action" | "use" the target Asset (under a specific permission), currently only the action "use" is used by Catena-X |
| policy permission "constraint" | A boolean/logical expression that refines an Action and Party/Asset collection or the conditions applicable to a Rule. The leftOperand instances MUST clearly be defined to indicate the semantics of the Constraint. Catena-X will use the **left operand** of a *constraint* to associate a specific verifiable credential (VC). The left operand value will correspond to the form: [VC type].[subtype]. **Right Operand:** The rightOperand is the value of the Constraint that is to be compared to the leftOperand. All possible `Catena-X constraints` can be found here: [https://github.com/eclipse-tractusx/ssi-docu](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md)

### Policy Template Example with @context: `"odrl": "http://www.w3.org/ns/odrl/2/"`

There is another possibility of representation: in the example above, `"@context": "http://www.w3.org/ns/odrl.jsonld"` was defined, so it is not necessary to always write `odlr:xy`. If this is not defined, the policy must look like this:

{
"@context": {
Expand Down Expand Up @@ -89,14 +95,23 @@ There is another possibility of representation: in the example above, `"@context
]
}
}
## Policies & Verifiable Credenitals (VC)
### General Information

### Policies & Verifiable Credenitals (VC)

#### General Information

Catena-X uses policies to determine access to and use of data. The policies refer to verifiable credentials (VC) that are stored in the Managed Identity Wallet (MIW). Catena-X uses the principle of self-sovereign identity (SSI) here.

>ℹ️ Detailed Information <br> More information about SSI, VC and MIW can be found here: <br> - [https://github.com/eclipse-tractusx/ssi-docu](https://github.com/eclipse-tractusx/ssi-docu) <br> - [https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-2](https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-2) (for release 23.09) <br> - [https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-3](https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-3) (for release 23.12)
>ℹ️ Detailed Information about SSI, VC and MIW can be found here:
- [https://github.com/eclipse-tractusx/ssi-docu](https://github.com/eclipse-tractusx/ssi-docu)
- [https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-2](https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-2) (for release 23.09)
- [https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-3](https://github.com/eclipse-tractusx/ssi-docu/tree/main/docs/architecture/cx-3-3) (for release 23.12)

The key architectural principle underlying this specification is that policy definitions must be decoupled from their corresponding VC schema. Namely, the specific **constraints** and shape of the VC schema must not be reflected in the policy definition. This allows VC schemas to be altered without impacting policy definitions.
### Membership Constraint Example

#### Membership Constraint Example

The main difference between the various Catena-X policies is their `constraints`. For this reason, only the constraint examples are shown below instead of always showing the entire policy.

To understand what the connection between policy and VC looks like, let's take a look at the following example ([Source](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#1-membership-constraint)):
Expand Down Expand Up @@ -145,18 +160,24 @@ An associated VC could look like this ([Source](https://github.com/eclipse-tract
| credentialSubject "memberOf" | The organization or group the holder is a member of (in this case, "Catena-X") |
| credentialSubject "status" | The status of the credential, indicating it is currently "Active"
| credenitalSubject "startTime" | The date and time when the membership started (in UTC format)
## Specific Catena-X Constraints

>ℹ️ Detailed Information <br> All possible `Catena-X constraints` can be found here: [https://github.com/eclipse-tractusx/ssi-docu](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md)
### Specific Catena-X Constraints

>ℹ️ Detailed Information about all possible `Catena-X constraints` can be found here:
- [https://github.com/eclipse-tractusx/ssi-docu](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md)

### Access & Usage Policies

In Catena-X, a distinction is made between `Access` and `Usage` Policies.
>ℹ️ Note: `The terms:"usage policy" and "contract policy" are used synonymously!`
## Access & Usage Policies
In Catena-X, a distinction is made between `Access` and `Usage` Policies.
>ℹ️ Note <br> `The terms "usage policy" and "contract policy" are used synonymously!`
- **access policy:** determines whether a particular consumer is offered an asset or not. For example, we may want to restrict certain assets such that only consumers within a particular geography can see them. Consumers outside that geography wouldn't even have them in their catalog.
- **usage policy or contract policy:** determines the conditions for initiating a contract negotiation for a particular asset. Note that does not automatically guarantee the successful creation of a contract, it merely expresses the eligibility to start the negotiation.

`Access and Usage Policies are not distinguished by a special semantic but by the time of the check.`
<br> To explain this in more detail, it is necessary to understand how data exchange via EDC works in Catena-X. If you want to provide data, you must create a contract definition. This looks like this, for example:

To explain this in more detail, it is necessary to understand how data exchange via EDC works in Catena-X. If you want to provide data, you must create a contract definition. This looks like this, for example:

curl -X POST "${BOB_DATAMGMT_URL}/data/contractdefinitions" \
--header 'X-Api-Key: password' \
Expand All @@ -177,11 +198,17 @@ In Catena-X, a distinction is made between `Access` and `Usage` Policies.

As you can see, the contract definition determines which access or usage policy is referred to. This is done via the respective id's.

>ℹ️ More detailed information about the data transfer in Catena-X can be found [here](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/samples/Transfer%20Data.md).
>ℹ️ More detailed information about the data transfer in Catena-X can be found [here](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/samples/Transfer%20Data.md).
### EDC Policy Playground
>
>ℹ️ Policies can be created individually with the following tool:
- Online Version: [Link](https://eclipse-tractusx.github.io/tutorial-resources/policy-playground/)
- Local Version: [Link](https://github.com/eclipse-tractusx/tutorial-resources/tree/main/edc-policy-playground)
>
### Exemplary scenarios

## EDC Policy Playground
>ℹ️ Policies can be created individually with the following tool: <br> - Online Version: [Link](https://eclipse-tractusx.github.io/tutorial-resources/policy-playground/) <br> - Local Version: [Link](https://github.com/eclipse-tractusx/tutorial-resources/tree/main/edc-policy-playground)
## Exemplary scenarios
For the following Scenarios, we assume there is a **Partner 1 (provider)** who wants to provide Data for **Partner 2 (consumer)**.

- Partner 1 (provider) has the Business-Partner-Number BPN12345.
Expand Down Expand Up @@ -213,9 +240,12 @@ So for this example, if Partner 2 does a catalogue request to Partner 1, the fol
"contractTemplates": "https://public.catena-x.org/contracts/"
}
}
### Scenario 1

#### Scenario 1

Partner 1 wants to create an Access Policy, that Partner 2 can only receive the Contract offer if its BPN matches AND if it has the Traceability Credential (Traceability Contract Signed). If one of those is missing, Partner 2 won't receive a Contract Offer.
#### Partner 1 - Access Policy Example

##### Partner 1 - Access Policy Example

{
"@context": {
Expand Down Expand Up @@ -256,13 +286,15 @@ Partner 1 wants to create an Access Policy, that Partner 2 can only receive the

Be aware, the credential within the Summary Credential is called "TraceabilityCredential", but as the EDC does a mapping, the EDC Access Policy Entry needs to be named "FrameworkAgreement.traceability"!

#### Desired Outcome
##### Desired Outcome

Partner 2 receives the Contract Offer because the BPNs are matching and he owns the Traceability Credential.
### Scenario 2

#### Scenario 2

Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contract Offer if its BPN matches. But a Contract Agreement should only be created if Partner 2 also signed the Traceability Framework Agreement. So in this case, Partner 2 should receive the Contract Offer in the first place, regardless if it signed the Traceability Framework Agreement. The signing of the Agreement should be checked at the time of contract negotiation.

#### Partner 1 - Access Policy Example
##### Partner 1 - Access Policy Example (Scenario 2)

{
"@context": {
Expand Down Expand Up @@ -293,7 +325,7 @@ Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contr
}
}

#### Partner 1 - Usage/Contract Policy Example
##### Partner 1 - Usage/Contract Policy Example (Scenario 2)

{
"@context": {
Expand Down Expand Up @@ -324,15 +356,15 @@ Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contr
}
}

#### Desired Outcome
##### Desired Outcome (Scenario 2)

Partner 2 receives the Contract Offer and is able to negotiate the contract because he owns the Traceability Credential.

### Scenario 3
#### Scenario 3

Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching AND Partner 2 is identified as a Dismantler (owns the "DismantlerCredential").

#### Partner 1 - Access Policy Example
##### Partner 1 - Access Policy Example (Scenario 3)

{
"@context": {
Expand Down Expand Up @@ -371,15 +403,15 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra
}
}

#### Desired Outcome
##### Desired Outcome (Scenario 3)

Partner 2 does not receive the Contract Offer as he does not own the Dismantler Credential and is therefore not able to negotiate the contract or request the data.

### Scenario 4
#### Scenario 4

Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching. Further, Partner 1 only wants to create an Agreement if Partner 2 is identified as a Dismantler (owns the "DismantlerCredential"). Otherwise the Negotiation has to fail.

#### Partner 1 - Access Policy Example
##### Partner 1 - Access Policy Example (Scenario 4)

{
"@context": {
Expand Down Expand Up @@ -410,7 +442,7 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra
}
}

#### Partner 1 - Usage/Contract Policy Example
##### Partner 1 - Usage/Contract Policy Example (Scenario 4)

{
"@context": {
Expand Down Expand Up @@ -441,8 +473,8 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra
}
}

#### Desired Outcome
##### Desired Outcome (Scenario 4)

Partner 2 receives the Contract Offer in the first place.

The contract negotiation, started by Partner 2 fails because he has not been identified as Dismantler and therefore does not own the Dismantler Credential.
The contract negotiation, started by Partner 2 fails because he has not been identified as Dismantler and therefore does not own the Dismantler Credential.

0 comments on commit ef30445

Please sign in to comment.