From b5fbe1040de1e61978bfc6bc70bf5b14e0181099 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Wed, 17 Aug 2016 17:21:37 -0400 Subject: [PATCH 1/2] Change Group section to agentGroup, move agentClass to proposals/ --- CHANGELOG.md | 6 +++++ README.md | 50 ++++++++++++++++++++++---------------- proposals/agent-class.md | 52 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 21 deletions(-) create mode 100644 proposals/agent-class.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cd61ed..fdd12ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +##### v.0.4.0 + +- Change Group ACL definition spec to one based on `vcard:hasMember` instead of + `acl:agentClass`. Move previous `agentClass` based section to `proposals/` for + archival purposes. + ##### v.0.3.1 - Add a discussion of infinite loops in Group ACL resolution diff --git a/README.md b/README.md index 8a9748e..279f5ce 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Next](https://www.w3.org/community/ldpnext/)) type systems, such as the [Solid](https://github.com/solid/solid) project (see also the parent [spec](https://github.com/solid/solid-spec)). -**Current Spec version:** `v.0.3.1` (see [CHANGELOG.md](CHANGELOG.md)) +**Current Spec version:** `v.0.4.0` (see [CHANGELOG.md](CHANGELOG.md)) ## Table of Contents @@ -224,10 +224,10 @@ as denoted by her WebID URI, `https://alice.databox.me/profile/card#me`. ### Groups of Agents -To give access to a group of agents, use the `acl:agentClass` predicate. -The object of an `agentClass` statement is a hash fragment identifier that -resolves to an RDF class statement in a **Group Listing** document. -If a WebID is listed in that document, *and* it's of the specified class, it is +To give access to a group of agents, use the `acl:agentGroup` predicate. +The object of an `agentGroup` statement is a link to a **Group Listing** +document. The WebIDs of group members are listed in it, using the +`vcard:hasMember` predicate. If a WebID is listed in that document, it is given access. Example ACL resource, `shared-file1.acl`, containing a group permission: @@ -249,8 +249,8 @@ Example ACL resource, `shared-file1.acl`, containing a group permission: a acl:Authorization; acl:accessTo ; acl:mode acl:Read, acl:Write; - acl:agentClass ; - acl:agentClass . + acl:agentGroup ; + acl:agentGroup . ``` Corresponding `work-groups` Group Listing document: @@ -258,23 +258,31 @@ Corresponding `work-groups` Group Listing document: ```ttl # Contents of https://alice.example.com/work-groups @prefix acl: . -@prefix rdfs: . +@prefix vcard: . <> a acl:GroupListing. -<#Employee> a rdfs:Class. -<#Accounting> a rdfs:Class. -<#Management> a rdfs:Class. +<#Accounting> +a vcard:Group; + vcard:hasUID ; + dc:created "2013-09-11T07:18:19+0000"^^xsd:dateTime; + dc:modified "2015-08-08T14:45:15+0000"^^xsd:dateTime; - a <#Employee>, <#Accounting>. - a <#Employee>, <#Accounting>. + # Accounting group members: + vcard:hasMember ; + vcard:hasMember . - a <#Employee>, <#Management>. +<#Management> +a vcard:Group; + vcard:hasUID ; + + # Management group members: + vcard:hasMember . ``` #### Group Listings - Implementation Notes -When implementing support for `acl:agentClass` and Group Listings, keep in mind +When implementing support for `acl:agentGroup` and Group Listings, keep in mind the following issues: 1. Group Listings are regular documents (potentially with their own `.acl`s). @@ -285,7 +293,7 @@ the following issues: ##### Group Listings - Authentication of External Requests -Group Listings via `acl:agentClass` links introduce the possibility of an ACL +Group Listings via `acl:agentGroup` links introduce the possibility of an ACL checking engine having to make requests to other servers. Given that access to those external group listings can be protected, the question immediately arises: By what mechanism should the ACL checking engine authenticate its request to @@ -327,7 +335,7 @@ examples. ##### Infinite Request Loops in Group Listings Since Group Listings (which are linked to from ACL resources using -the `acl:agentClass` predicate) are regular documents, they can have their very +the `acl:agentGroup` predicate) are regular documents, they can have their very own `.acl` resources that restrict which users (or groups) are allowed to access or change them. This fact, that `.acl`s point to Group Listings, which can have `.acl`s of their own, which can potentially also point to Group Listings, and so @@ -340,15 +348,15 @@ https://a.com https://b.com ------------- GET --------------- group-listA <------ group-listB.acl | ^ contains: - | | agentClass + | | agentGroup v GET | group-listA.acl ------> group-listB contains: - agentClass + agentGroup ``` The access to `group-listA` is controlled by `group-listA.acl`. So far so good. -But if `group-listA.acl` contains any `acl:agentClass` references to *another* +But if `group-listA.acl` contains any `acl:agentGroup` references to *another* group listing (say, points to `group-listB`), one runs into potential danger. In order to retrieve that other group listing, the ACL-checking engine on `https://b.com` will need to check the rules in `group-listB.acl`. And if @@ -361,7 +369,7 @@ To guard against these loops, implementers have several options: **A) Do not allow cross-domain Group Listing resolutions**. The simplest to implement (but also the most limited) option is to disallow cross-domain Group Listings resolution requests. That is, the ACL-checking code -could detect `agentClass` links pointing to external servers during ACL +could detect `agentGroup` links pointing to external servers during ACL resolution time, and treat those uniformly (as errors, or as automatic "access denied"). diff --git a/proposals/agent-class.md b/proposals/agent-class.md new file mode 100644 index 0000000..4bf0867 --- /dev/null +++ b/proposals/agent-class.md @@ -0,0 +1,52 @@ +### Groups of Agents and `agentClass` + +**Note:** Current spec uses `acl:agentGroup` and `vcard:hasMember` to implement +group membership. This section is saved here for reference / archival purposes. + +To give access to a group of agents, use the `acl:agentClass` predicate. +The object of an `agentClass` statement is a hash fragment identifier that +resolves to an RDF class statement in a **Group Listing** document. +If a WebID is listed in that document, *and* it's of the specified class, it is +given access. + +Example ACL resource, `shared-file1.acl`, containing a group permission: + +```ttl +# Contents of https://alice.databox.me/docs/shared-file1.acl +@prefix acl: . + +# Individual authorization - Alice has Read/Write/Control access +<#authorization1> + a acl:Authorization; + acl:accessTo ; + acl:mode acl:Read, acl:Write, acl:Control; + acl:agent . + +# Group authorization, giving Read/Write access to two groups, which are +# specified in the 'work-groups' document. +<#authorization2> + a acl:Authorization; + acl:accessTo ; + acl:mode acl:Read, acl:Write; + acl:agentClass ; + acl:agentClass . +``` + +Corresponding `work-groups` Group Listing document: + +```ttl +# Contents of https://alice.example.com/work-groups +@prefix acl: . +@prefix rdfs: . + +<> a acl:GroupListing. + +<#Employee> a rdfs:Class. +<#Accounting> a rdfs:Class. +<#Management> a rdfs:Class. + + a <#Employee>, <#Accounting>. + a <#Employee>, <#Accounting>. + + a <#Employee>, <#Management>. +``` From d6505cf89727fd095d5023072fcd9502f6a8c829 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Thu, 18 Aug 2016 14:38:59 -0400 Subject: [PATCH 2/2] Clarify relationship betwen Group Listings and their containing documents --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 279f5ce..1a43d9e 100644 --- a/README.md +++ b/README.md @@ -335,11 +335,12 @@ examples. ##### Infinite Request Loops in Group Listings Since Group Listings (which are linked to from ACL resources using -the `acl:agentGroup` predicate) are regular documents, they can have their very -own `.acl` resources that restrict which users (or groups) are allowed to access -or change them. This fact, that `.acl`s point to Group Listings, which can have -`.acl`s of their own, which can potentially also point to Group Listings, and so -on, introduces the potential for infinite loops during ACL resolution. +the `acl:agentGroup` predicate) reside in regular documents, those documents +will have their very own `.acl` resources that restrict which users (or groups) +are allowed to access or change them. This fact, that `.acl`s point to Group +Listings, which can have `.acl`s of their own, which can potentially also point +to Group Listings, and so on, introduces the potential for infinite loops +during ACL resolution. Take the following situation with two different servers: