Selective Data Sharing

The owner of an IOTICSpace is in control of all its twins, and therefore of all the data stored and streaming through them. Owners can decide to make their twins visible (or not) and to share data with all, none, or a select number of parties and, by extension, join one or more data ecosystems or consortia.

This page will cover:

• An introduction to Selective Data Sharing
• Visibility (the F in FAIR)
  • How to set a Digital Twin's visibility (PUBLIC, PRIVATE)
• Accessibility (the A in FAIR)
  • Selective data sharing for the entire IOTICSpace
  • Selective data sharing for a specific Digital Twin
  • Designing for granular access control
  • How to set a Digital Twin's access permissions (ALLOW ALL, ALLOW SOME, ALLOW NONE)

An introduction to Selective Data Sharing

IOTICS distinguishes between two settings:

1. Visibility (the F in FAIR)

 * whether a Digital Twin's **metadata **is visible (or not) to another IOTICSpace
 * this is set by updating the Host Twin's or Digital Twin's *Visibility* property

2. Accessibility (the A in FAIR)

 * whether a Digital twin's **data **can be accessed (or not) by a Digital Twin from another IOTICSpace
 * it can be enabled for the entire IOTICSpace and selectively on a twin-by-twin basis
 * this is set by updating the Host Twin's or Digital Twin's *AllowList* property

Visibility (the F in FAIR)

The Visibility property determines whether a Digital Twin can be found by searching for its metadata. Two settings exist: PRIVATE and PUBLIC.

🚧

Default settings: Host Twin = PUBLIC, Digital Twin = PRIVATE

How to set a Digital Twin's visibility (PUBLIC, PRIVATE)

curl --request PATCH \
     --url https://example.iotics.space/qapi/twins/did%3Aiotics%3Adidexample1234abcd \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Iotics-ClientAppId: ExampleAppID' \
     --data '
{
     "newVisibility": {
          "visibility": "PUBLIC"
     },
}
'

import requests

url = "https://example.iotics.space/qapi/twins/did%3Aiotics%3Adidexample1234abcd"

payload = {
    "newVisibility": {"visibility": "PUBLIC"}
}
headers = {
    "Accept": "application/json",
    "Iotics-ClientAppId": "ExampleAppID",
    "Content-Type": "application/json"
}

response = requests.request("PATCH", url, json=payload, headers=headers)

print(response.text)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"newVisibility\":{\"visibility\":\"PUBLIC\"}");
Request request = new Request.Builder()
  .url("https://example.iotics.space/qapi/twins/did%3Aiotics%3Adidexample1234abcd")
  .patch(body)
  .addHeader("Accept", "application/json")
  .addHeader("Iotics-ClientAppId", "ExampleAppID")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

Accessibility (the A in FAIR)

Access permissions can be enabled:

• for the entire IOTICSpace, setting the Host Twin's AllowList
• on a twin-by-twin basis, setting a Digital Twin's individual AllowList

The Host Twin controls access to the entire IOTICSpace and therefore restricts or enables access to all the Digital Twins within the IOTICSpace to all, none or a select group of other IOTICSpaces. Granular access control can be achieved by setting an individual Digital Twin's access permissions.

Selective data sharing for the entire IOTICSpace

This is enabled or restricted by updating the Host Twin's AllowList property.

Available access levels of the AllowList are:

• ALLOW ALL - allows access from any other IOTICSpace
• ALLOW SOME - allows access from specific IOTICSpaces only
• ALLOW NONE - denies access to any other IOTICSpace

🚧

The Host Twin's default setting is ALLOW ALL

Selective data sharing for a specific Digital Twin

This is enabled or restricted by updating the Digital Twin's AllowList property.

Available access levels of the AllowList are:

• ALLOW ALL - allows access to the twin from any other IOTICSpace (provided the Host Twin allows this IOTICSpace)
• ALLOW SOME - allows access from specific IOTICSpaces only (provided the Host Twin allows this specific IOTICSpace)
• ALLOW NONE - denies access to any other IOTICSpace (irrespective of the Host Twin's AllowList setting)

🚧

A Digital Twin's default setting is ALLOW NONE

Designing for granular access control

Combining access permissions for the entire IOTICSpace with individual twins results in granular access control.

When configuring your access permissions, consider the following best practices:

1. What is the least restrictive data access you need? Consider that:
   • Restricting the Host Twin to ALLOW NONE may be tempting initially, however will leave you with an IOTICSpace unable to interact with anyone (therefore unable to join any data ecosystem). We recommend the Host Twin is set to ALLOW SOME or ALLOW ALL for future extensibility.
   • Updating the AllowList of individual Digital Twins can be done by any user, the Host Twin can only be updated by admins.
2. Do you need to share all or only parts of a Digital Twin's data? If you only need to share some of your Digital Twin's metadata and data with a third party, consider that:
   • in IOTICS the entire Digital Twin will be shared. If you still want to share only some of it, you can clone your existing twin, remove any details you don't want to share, and share that new twin instead.
   • this will also allow you to keep on top of your access permissions later, once you may need to manage more than two third parties with different data access needs (search by Host Twin DID will be handy).
3. Is there any potential conflict between your Host Twin and Digital Twin settings? Consider to:
   • regularly review your access needs. If the access permissions contradict themselves, the most restrictive and secure permissions are applied. This means that both the Host Twin and the Digital Twin need to allow access if this is desired. If the Host Twin restricts access, but the Digital Twin itself doesn't, access isn't given. Similarly, if the Host Twins allows access but the Digital Twin doesn't, access isn't given either.
   • if you need help designing your access permissions please do get in touch with us.

The following table details all possible combinations

🚧

Any conflicts between settings will resolve in the more secure and restrictive way

For example, if the Host Twin is set to ALLOW NONE and the Twin is set to ALLOW ALL, no other IOTICSpace can access any twin.

How to set a Digital Twin's access permissions (ALLOW ALL, ALLOW SOME, ALLOW NONE)

Updating the Host Twin or an individual Digital Twin follows the same principle, meaning that the AllowList has to be updated to either ALLOW ALL, NONE or ALLOW SOME.

When updating access permissions you need to remove existing allow to avoid a clash of permissions. This is done by deleting the hostAllowList property.

🚧

Check you have permissions to update the Host Twin and/or Digital Twin

Follow this step-by-step guide if you need help updating the Host Twin.

AGENT_TOKEN='example_Agent_TokenABCdefghijklmnopqrstuvwxyz1234567890'
A_TWIN_DID='did%3Aiotics%3Adidexample1234abcd'
curl -X PATCH "http://localhost:8081/qapi/twins/$A_TWIN_DID" \
 -H "accept: application/json" \
 -H "Iotics-ClientAppId: app1" \
 -H "Authorization: Bearer $AGENT_TOKEN" \
 -H "Content-Type: application/json"\
  -d "{\"properties\":{\"added\":[{\"key\":\"http://data.iotics.com/public#hostAllowList\",\"uriValue\":{\"value\":\"http://data.iotics.com/public#allHosts\"}}],\"deletedByKey\":[\"http://data.iotics.com/public#hostAllowList\"]}}"

allow_all_property = ModelProperty(key='http://data.iotics.com/public#hostAllowList',
                                    uri_value=Uri(value='http://data.iotics.com/public#allHosts'))
api.update_twin(twin_id=,did:iotics:didexample1234abcd,
                add_props=[
                    allow_all_property
                ],
                del_props_by_key=[
                    'http://data.iotics.com/public#hostAllowList'
                ])

AGENT_TOKEN='example_Agent_TokenABCdefghijklmnopqrstuvwxyz1234567890'
A_TWIN_DID='did%3Aiotics%3Adidexample1234abcd'
OTHER_HOST_TWIN_DID='did:iotics:otherdidexample1234abcd'
curl -X PATCH "http://localhost:8081/qapi/twins/$A_TWIN_DID" \
 -H "accept: application/json" \
 -H "Iotics-ClientAppId: app1" \
 -H "Authorization: Bearer $AGENT_TOKEN" \
 -H "Content-Type: application/json"\
  -d "{\"properties\":{\"added\":[{\"key\":\"http://data.iotics.com/public#hostAllowList\",\"uriValue\":{\"value\":\"$OTHER_HOST_TWIN_DID\"}}],\"deletedByKey\":[\"http://data.iotics.com/public#hostAllowList\"]}}"

allow_other_host_property = ModelProperty(key='http://data.iotics.com/public#hostAllowList',
                                    uri_value=Uri(value=did:iotics:otherdidexample1234abcd))
api.update_twin(twin_id=did:iotics:didexample1234abcd,
                add_props=[
                    allow_other_host_property
                ],
                del_props_by_key=[
                    'http://data.iotics.com/public#hostAllowList'
                ])

AGENT_TOKEN='example_Agent_TokenABCdefghijklmnopqrstuvwxyz1234567890'
A_TWIN_DID='did%3Aiotics%3Adidexample1234abcd'
curl -X PATCH "http://localhost:8081/qapi/twins/$A_TWIN_DID" \
 -H "accept: application/json" \
 -H "Iotics-ClientAppId: app1" \
 -H "Authorization: Bearer $AGENT_TOKEN" \
 -H "Content-Type: application/json"\
  -d "{\"properties\":{\"added\":[{\"key\":\"http://data.iotics.com/public#hostAllowList\",\"uriValue\":{\"value\":\"http://data.iotics.com/public#noHost\"}}],\"deletedByKey\":[\"http://data.iotics.com/public#hostAllowList\"]}}"

allow_none_property = ModelProperty(key='http://data.iotics.com/public#hostAllowList',
                                    uri_value=Uri(value='http://data.iotics.com/public#noHost'))
api.update_twin(twin_id=did:iotics:didexample1234abcd,
                add_props=[
                    allow_none_property
                ],
                del_props_by_key=[
                    'http://data.iotics.com/public#hostAllowList'
                ])