diff --git a/docs/policies/policies.md b/docs/policies/policies.md index 765d00804..eef578b6a 100644 --- a/docs/policies/policies.md +++ b/docs/policies/policies.md @@ -2,7 +2,7 @@ ## 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/). +ℹ️ All explanations in this chapter "General Information about Policies" were taken from the following [source](https://w3c.github.io/poe/model/). ### Introduction @@ -30,17 +30,21 @@ A Catena-X policy uses the ODRL Information Model as a semantic model. Theoretic ### Policy Template Example with @context: `"http://www.w3.org/ns/odrl.jsonld"` - { - "@context": {}, - "@type": "PolicyDefinitionRequest", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Set", - "@context": "http://www.w3.org/ns/odrl.jsonld", - "permission": [ +```json +{ + "@context": {}, + "@type": "PolicyDefinitionRequest", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Set", + "@context": "http://www.w3.org/ns/odrl.jsonld", + "permission": [ + { + "action": "use", + "constraint": [ { - "action": "use", - "constraint": [ + "@type": "LogicalConstraint", + "and": [ { "leftOperand": { "@value": "" @@ -52,7 +56,10 @@ A Catena-X policy uses the ODRL Information Model as a semantic model. Theoretic } ] } - } + ] + } +} +``` | Variable | Content | | -------- | -------- | @@ -67,34 +74,41 @@ A Catena-X policy uses the ODRL Information Model as a semantic model. Theoretic 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": { - "odrl": "http://www.w3.org/ns/odrl/2/" +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequest", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "odrl:Set", + "odrl:permission": [ + { + "odrl:action": { + "@id": "odrl:use" }, - "@type": "PolicyDefinitionRequest", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "odrl:Set", - "odrl:permission": [ - { - "odrl:action": { - "@id": "odrl:use" + "odrl:constraint": [ + { + "@type": "odrl:LogicalConstraint", + "odrl:and": [ + { + "odrl:leftOperand": { + "@value": "" }, - "odrl:constraint": [ - { - "odrl:leftOperand": { - "@value": "" - }, - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "" - } - ] - } + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "" + } ] - } - } + } + ] + } + ] + } +} +``` ### Policies & Verifiable Credenitals (VC) @@ -102,7 +116,7 @@ There is another possibility of representation: in the example above, `"@context 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 about SSI, VC and MIW can be found here: +ℹ️ 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) @@ -116,35 +130,39 @@ The main difference between the various Catena-X policies is their `constraints` 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)): - { - "constraint": { - "leftOperand": "Membership", - "operator": "eq", - "rightOperand": "active" - } +```json +{ + "constraint": { + "leftOperand": "Membership", + "operator": "eq", + "rightOperand": "active" } +} +``` An associated VC could look like this ([Source](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/3.%20Verifiable%20Credentials/Structure%20and%20Formats.md)): - { - "id": "UUID", - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://w3id.org/security/suites/jws-2020/v1", - "https://raw.githubusercontent.com/catenax-ng/product-core-schemas/main/businessPartnerData" - ], - "type": ["VerifiableCredential", "MembershipCredentialCX"], - "issuanceDate": "2021-06-16T18:56:59Z", - "expirationDate": "2022-06-16T18:56:59Z", - "issuer": "did", // operating environment - "credentialSubject": { - "type": "MembershipCredential", - "holderIdentifier": "bpn", - "memberOf": "Catena-X", - "status": "Active", - "startTime": "2021-06-16T18:56:59Z" - } +```json +{ + "id": "UUID", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/security/suites/jws-2020/v1", + "https://raw.githubusercontent.com/catenax-ng/product-core-schemas/main/businessPartnerData" + ], + "type": ["VerifiableCredential", "MembershipCredentialCX"], + "issuanceDate": "2021-06-16T18:56:59Z", + "expirationDate": "2022-06-16T18:56:59Z", + "issuer": "did", // operating environment + "credentialSubject": { + "type": "MembershipCredential", + "holderIdentifier": "bpn", + "memberOf": "Catena-X", + "status": "Active", + "startTime": "2021-06-16T18:56:59Z" } +} +``` | Variable | Content ([Source](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/3.%20Verifiable%20Credentials/Structure%20and%20Formats.md)) | | -------- | -------- | @@ -163,53 +181,56 @@ An associated VC could look like this ([Source](https://github.com/eclipse-tract ### Specific Catena-X Constraints ->ℹ️ Detailed Information about all possible `Catena-X constraints` can be found here: +ℹ️ 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!` +In Catena-X, a distinction is made between **Access** and **Usage** Policies. + +ℹ️ Note: **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.` +**The Access and Usage Policies are not distinguished by any special semantics, but rather by the time at which they are checked.** 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' \ - --header 'Content-Type: application/json' \ - --data '{ - "id": "1", - "criteria": [ - { - "operandLeft": "asset:prop:id", - "operator": "=", - "operandRight": "1" - } - ], - "accessPolicyId": "1", - "contractPolicyId": "1" - }' \ - -s -o /dev/null -w 'Response Code: %{http_code}\n' +```bash +curl -X POST "${BOB_DATAMGMT_URL}/data/contractdefinitions" \ + --header 'X-Api-Key: password' \ + --header 'Content-Type: application/json' \ + --data '{ + "id": "1", + "criteria": [ + { + "operandLeft": "asset:prop:id", + "operator": "=", + "operandRight": "1" + } + ], + "accessPolicyId": "1", + "contractPolicyId": "1" + }' \ + -s -o /dev/null -w 'Response Code: %{http_code}\n' +``` 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: + +ℹ️ 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 -For the following Scenarios, we assume there is a **Partner 1 (provider)** who wants to provide Data for **Partner 2 (consumer)**. +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. - Partner 2 (consumer) has the Business-Partner-Number BPN6789. @@ -218,28 +239,30 @@ Partner 2 (consumer) signed the **Traceability Framework Agreement** and followe So for this example, if Partner 2 does a catalogue request to Partner 1, the following summary credential is provided to Partner 1: - { - "@context": [ - "https://w3id.org/2023/catenax/credentials/summary/v1" +```json +{ + "@context": [ + "https://w3id.org/2023/catenax/credentials/summary/v1" + ], + "id": "", + "type": [ + "VerifiableCredential", + "SummaryCredential" + ], + "issuer": "", + "issuanceDate": "2023-06-02T12:00:00Z", + "expirationDate": "2022-06-16T18:56:59Z", + "credentialSubject": { + "id": "", + "holderIdentifier": "BPN6789", + "items": [ + "MembershipCredential", + "TraceabilityCredential" ], - "id": "", - "type": [ - "VerifiableCredential", - "SummaryCredential" - ], - "issuer": "", - "issuanceDate": "2023-06-02T12:00:00Z", - "expirationDate": "2022-06-16T18:56:59Z", - "credentialSubject": { - "id": "", - "holderIdentifier": "BPN6789", - "items": [ - "MembershipCredential", - "TraceabilityCredential" - ], - "contractTemplates": "https://public.catena-x.org/contracts/" - } + "contractTemplates": "https://public.catena-x.org/contracts/" } +} +``` #### Scenario 1 @@ -247,6 +270,7 @@ Partner 1 wants to create an Access Policy, that Partner 2 can only receive the ##### Partner 1 - Access Policy Example +```json { "@context": { "odrl": "http://www.w3.org/ns/odrl/2/" @@ -283,8 +307,9 @@ 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"! +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 @@ -296,37 +321,40 @@ Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contr ##### Partner 1 - Access Policy Example (Scenario 2) - { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{BPN6789}}" - } - ] - } +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ + { + "@type": "Constraint", + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "{{BPN6789}}" + } + ] } - ] - } + } + ] } +} +``` ##### Partner 1 - Usage/Contract Policy Example (Scenario 2) +```json { "@context": { "odrl": "http://www.w3.org/ns/odrl/2/" @@ -355,6 +383,7 @@ Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contr ] } } +``` ##### Desired Outcome (Scenario 2) @@ -366,42 +395,44 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra ##### Partner 1 - Access Policy Example (Scenario 3) - { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{BPN6789}}" +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ + { + "@type": "Constraint", + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" }, - { - "@type": "Constraint", - "odrl:leftOperand": "Dismantler", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] - } + "odrl:rightOperand": "{{BPN6789}}" + }, + { + "@type": "Constraint", + "odrl:leftOperand": "Dismantler", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + } + ] } - ] - } + } + ] } +} +``` ##### Desired Outcome (Scenario 3) @@ -413,65 +444,69 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra ##### Partner 1 - Access Policy Example (Scenario 4) - { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{BPN6789}}" - } - ] - } +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ + { + "@type": "Constraint", + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "{{BPN6789}}" + } + ] } - ] - } + } + ] } +} +``` ##### Partner 1 - Usage/Contract Policy Example (Scenario 4) - { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "Dismantler", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] - } +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ + { + "@type": "Constraint", + "odrl:leftOperand": "Dismantler", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + } + ] } - ] - } + } + ] } +} +``` ##### Desired Outcome (Scenario 4)