Structure of delegation evidence

This part of the iSHARE Trust Framework is considered normative and is therefore compliant with RFC 2119.

This page describes (and prescribes) how, in data spaces/iSHARE network, delegation is communicated between different parties.

In data spaces/iSHARE network, delegation evidence expresses the delegation of rights from a delegator (the party that delegates rights; the policyIssuer) to the delegate (the party that receives the delegated rights; i.e. the accessSubject). Rights are expressed in rules in terms of allowed actions to be performed on resources, under the license(s) as defined in policySets.

Delegation evidence is modelled as a JSON object inspired by the XACML 3.0 specifications and structured as follows:

The JSON object consists of a root delegationEvidence element (modeled after an XACML PolicySet element) containing one or more policySet objects in the policySets array. The root element is only meant as a container element and extends the XACML specifications to cater for some iSHARE required metadata such as timestamps. Each of the second level policySet elements only acts as a container for actual policy elements with an indication of the rights in this policySet can be further delegated (with maxDelegationDepth) and what license(s) do apply. No other delegation logic is conveyed a second level policySet. Each policy element is used to express the actual rights being delegated. \

The root delegationEvidence element contains the following parameters.

Parameter	Contained in	Type	Required	Description
delegationEvidence		{ }	Yes	The root of any delegation evidence
notBefore	delegationEvidence	int	Yes	Unix timestamp in UTC indicating the start of validity period of this delegation evidence. SHOULD equal the time of issuing of the evidence unless historic evidence is requested.
notOnOrAfter	delegationEvidence	int	Yes	Unix timestamp in UTC indicating the end of validity period of this delegation evidence. It is up to the issuer off the evidence to set this time. Note that a reasonable amount of time SHOULD be allowed for processing of longer delegation paths. Also note that evidence cannot be revoked, so setting very long validity periods SHOULD be avoided.
policyIssuer	delegationEvidence	string	Yes	iSHARE identifier of the delegator (the delegating entity)
target	delegationEvidence	{ }	Yes	MUST for the root level contain an accessSubject. No other elements are allowed. It makes the entire delegation evidence applicable only to this accessSubject.
accessSubject	target	string	Yes	iSHARE identifier of the delegate (the entity that receives the delegated rights)
policySets	delegationEvidence	[ ]	Yes (1..n)	Container for one or more objects containing policy elements with an indication for further delegation. Note that policySet elements within one delegationEvidence MUST not restrict each other, but rather offer a mechanism to express additional rights. They MUST be evaluated in a "permit-override" manner, allowing a "Permit" if only one of the policySet elements evaluates to "Permit".

The second level objects in policySets each contain the following parameters. Other parameters are not allowed. Note that XACML spec is heavily restricted, a.o. for the reason to prevent redundancy (and resulting possible conflicts) with the root policySet element.

Parameter	Contained in	Type	Required	Description
maxDelegationDepth	policySets	int	No	Optional element that, if present, indicates that further delegation of the rights, conveyed in the policy elements that are part of this PolicySet, is allowed. The value indicates the delegation steps that are allowed after this step in order to evaluate the entire delegation path to "Permit"
target	policySet	{ }	Yes
environment	target	{ }	Yes
licenses	environment	[ ]	Yes	Array which describes which iSHARE licenses apply to this policySet.
policies	policySets	[ ]	Yes (1..n)	Used to express the actual rights being delegated. Note that policies within one policySets object MUST not restrict each other, but rather offer a mechanism to express additional rights. They MUST be evaluated in a "permit-override" manner, allowing a "Permit" if only one of the policy elements evaluates to "Permit".

A Policy element contains the following parameters.

Parameter	Contained in	Type	Required	Description
target	policies	string	Yes	Describes the target, in terms of resource and action, this policy applies to. It is also the scope that is permitted through the default Rule. Additional Rule elements can be described to exclude Resources and Actions from the default policy rights
resource	target	{ }	Yes
type	resource	string	Yes	String which describes the type of resource to which the rules apply.
identifiers	resource	[ ]	Yes	Array of strings containing one or more resource identifiers. Depending on the Type an identifier SHOULD be a urn.
attributes	resource	[ ]	No	Optional array of attributes of the resources the delegated rights apply to. If omitted defaults to all attributes. Depending on the Type an attribute SHOULD be a urn.
actions	target	[ ]	Yes
environment	target	{ }	No
serviceProviders	environment	[ ]	Yes	Array which lists the iSHARE client ID's of serviceProviders which are allowed to provide services to the accessSubject as described within this policy.
rules	policies	[ ]	Yes (1..n)	The first rule element is the default rule that applies to the target at policies level. Note that additional rule elements within one policies object are intended to restrict each the default rule. All rule elements in a Policy MUST be evaluated in a "deny-override" manner, allowing a "Permit" only if all of the rule elements evaluate to "Permit".

The default Rule element contains the following parameters.

Parameter	Contained in	Type	Required	Description
effect	rules	string	Yes	MUST contain 'Permit'

Additional Rule elements contains the following parameters.

Parameter	Contained in	Type	Required	Description
effect	rules	string	Yes	MUST contain 'Deny'
target	rules	{ }	Yes	Describe the target, in terms of resource and action, this additional rule applies to. Additional rule elements are limitations of the default rule and resource scope.
resource	target	{ }	Yes
type	resource	string	No*	Optional string which describes the type of resource to which the rule applies. Defaults to none if not specified.
identifiers	resource	[ ]	No*	Optional array of strings containing one or more resource identifiers. Depending on the type an identifier SHOULD be a urn.
attributes	resource	[ ]	No*	Optional array of attributes of the resources the delegated rights apply to. If omitted defaults to all attributes. Depending on the type an attribute SHOULD be a urn.
actions	target	[ ]	No	Optional array of actions, the additional rule applies to the actions listed. If no actions are listed then the default is to all iSHARE actions defined within the policy.

* Note: Although not individually required, at least one of the parameters within the resource object needs to be specified to which the additional rules apply.

Example delegation JSON:

//Organisation A delegates rights to organisation B. A allows B READ and CREATE access to all ETA and WEIGHT of A's containers of which the data is located at service provider C and can only be accessed with service provider C. However, A does not allow B to CREATE to ETA information and completely denies access to data regarding container ID.00000000000001. Furthermore, all rights of B are allowed under iSHARE licenses 1 and 3, and B has the right to delegate it's right two more times.

{
    "delegationEvidence": {
        "notBefore": 1509633681,
        "notOnOrAfter": 1509633741,
        "policyIssuer": "EU.EORI.NL123456789",
        "target": {
            "accessSubject": "EU.EORI.NL012345678"
        },
        "policySets": [
            {
                "maxDelegationDepth": 2,
                "target": {
                    "environment": {
                        "licenses": ["ISHARE.0001", "ISHARE.0003"]
                    }
                },
                "policies": [
                    {
                        "target": {
                            "resource": {
                                "type": "GS1.CONTAINER",
                                "identifiers": ["*"],
                                "attributes": ["GS1.CONTAINER.ATTRIBUTE.ETA", "GS1.CONTAINER.ATTRIBUTE.WEIGHT"]
                            },
                            "actions": ["ISHARE.READ", "ISHARE.CREATE"],
                            "environment": {
                                "serviceProviders": ["EU.EORI.NL123412345"]
                            }
                        },
                        "rules": [
                            {
                                "effect": "Permit"
                            },
                            {
                                "effect": "Deny",
                                "target": {
                                    "resource": {
                                        "attributes": ["GS1.CONTAINER.ATTRIBUTE.ETA"]
                                    },
                                    "actions": ["ISHARE.CREATE"]
                                }
                            },
                            {
                                "effect": "Deny",
                                "target": {
                                    "resource": {
                                        "identifiers": ["GS1.CONTAINER.ID.00000000001"]
                                    }
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

example code - for copying purposes

{"delegationEvidence":{"notBefore":1509633681,"notOnOrAfter":1509633741,"policyIssuer":"EU.EORI.NL123456789","target":{"accessSubject":"EU.EORI.NL012345678"},"policySets":[{"maxDelegationDepth":2,"target":{"environment":{"licenses":["ISHARE.0001","ISHARE.0003"]}},"policies":[{"target":{"resource":{"type":"GS1.CONTAINER","identifiers":["*"],"attributes":["GS1.CONTAINER.ATTRIBUTE.ETA","GS1.CONTAINER.ATTRIBUTE.WEIGHT"]},"actions":["ISHARE.READ","ISHARE.CREATE"],"environment":{"serviceProviders":["EU.EORI.NL123412345"]}},"rules":[{"effect":"Permit"},{"effect":"Deny","target":{"resource":{"attributes":["GS1.CONTAINER.ATTRIBUTE.ETA"]},"actions":["ISHARE.CREATE"]}},{"effect":"Deny","target":{"resource":{"identifiers":["GS1.CONTAINER.ID.00000000001"]}}}]}]}]}}

Please note that although in XACML the attributes PolicySetId, Version and PolicyCombiningAlgId are mandatory in XACML they are not ported to the iSHARE JSON structure. iSHARE Trust Framework follows the "deny-override" Policy Combining Algorithm. This implies that if at least one policy is evaluated as “deny”, the integrated output must also be “deny”.