Skip to content

Commit c7ff6fe

Browse files
kjetilkkjetilk
authored
Merge pull request #26 from TallTed/patch-1
minor typo fixes and format improvements
2 parents dcdacc4 + 61891f7 commit c7ff6fe

File tree

1 file changed

+78
-62
lines changed

1 file changed

+78
-62
lines changed

‎README.md‎

Lines changed: 78 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -200,14 +200,15 @@ and Control) to one of her web resources, located at
200200

201201
```ttl
202202
# Contents of https://alice.databox.me/docs/file1.acl
203-
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
203+
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
204204
205205
<#authorization1>
206-
a acl:Authorization;
207-
acl:agent <https://alice.databox.me/profile/card#me>; # Alice's WebID
208-
acl:accessTo <https://alice.databox.me/docs/file1>;
209-
acl:mode
210-
acl:Read, acl:Write, acl:Control.
206+
a acl:Authorization;
207+
acl:agent <https://alice.databox.me/profile/card#me>; # Alice's WebID
208+
acl:accessTo <https://alice.databox.me/docs/file1>;
209+
acl:mode acl:Read,
210+
acl:Write,
211+
acl:Control.
211212
```
212213

213214
## Describing Agents
@@ -236,58 +237,61 @@ Example ACL resource, `shared-file1.acl`, containing a group permission:
236237

237238
```ttl
238239
# Contents of https://alice.databox.me/docs/shared-file1.acl
239-
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
240+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
240241
241242
# Individual authorization - Alice has Read/Write/Control access
242243
<#authorization1>
243-
a acl:Authorization;
244-
acl:accessTo <https://alice.example.com/docs/shared-file1>;
245-
acl:mode acl:Read, acl:Write, acl:Control;
246-
acl:agent <https://alice.example.com/profile/card#me>.
244+
a acl:Authorization;
245+
acl:accessTo <https://alice.example.com/docs/shared-file1>;
246+
acl:mode acl:Read,
247+
acl:Write,
248+
acl:Control;
249+
acl:agent <https://alice.example.com/profile/card#me>.
247250
248251
# Group authorization, giving Read/Write access to two groups, which are
249252
# specified in the 'work-groups' document.
250253
<#authorization2>
251-
a acl:Authorization;
252-
acl:accessTo <https://alice.example.com/docs/shared-file1>;
253-
acl:mode acl:Read, acl:Write;
254-
acl:agentGroup <https://alice.example.com/work-groups#Accounting>;
255-
acl:agentGroup <https://alice.example.com/work-groups#Management>.
254+
a acl:Authorization;
255+
acl:accessTo <https://alice.example.com/docs/shared-file1>;
256+
acl:mode acl:Read,
257+
acl:Write;
258+
acl:agentGroup <https://alice.example.com/work-groups#Accounting>;
259+
acl:agentGroup <https://alice.example.com/work-groups#Management>.
256260
```
257261

258262
Corresponding `work-groups` Group Listing document:
259263

260264
```ttl
261265
# Contents of https://alice.example.com/work-groups
262-
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
263-
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
266+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
267+
@prefix vcard: <http://www.w3.org/2006/vcard/ns#>.
264268
265-
<> a acl:GroupListing.
269+
<> a acl:GroupListing.
266270
267271
<#Accounting>
268-
a vcard:Group;
269-
vcard:hasUID <urn:uuid:8831CBAD-1111-2222-8563-F0F4787E5398:ABGroup>;
270-
dc:created "2013-09-11T07:18:19+0000"^^xsd:dateTime;
271-
dc:modified "2015-08-08T14:45:15+0000"^^xsd:dateTime;
272+
a vcard:Group;
273+
vcard:hasUID <urn:uuid:8831CBAD-1111-2222-8563-F0F4787E5398:ABGroup>;
274+
dc:created "2013-09-11T07:18:19+0000"^^xsd:dateTime;
275+
dc:modified "2015-08-08T14:45:15+0000"^^xsd:dateTime;
272276
273-
# Accounting group members:
274-
vcard:hasMember <https://bob.example.com/profile/card#me>;
275-
vcard:hasMember <https://candice.example.com/profile/card#me>.
277+
# Accounting group members:
278+
vcard:hasMember <https://bob.example.com/profile/card#me>;
279+
vcard:hasMember <https://candice.example.com/profile/card#me>.
276280
277281
<#Management>
278-
a vcard:Group;
279-
vcard:hasUID <urn:uuid:8831CBAD-3333-4444-8563-F0F4787E5398:ABGroup>;
282+
a vcard:Group;
283+
vcard:hasUID <urn:uuid:8831CBAD-3333-4444-8563-F0F4787E5398:ABGroup>;
280284
281-
# Management group members:
282-
vcard:hasMember <https://deb.example.com/profile/card#me>.
285+
# Management group members:
286+
vcard:hasMember <https://deb.example.com/profile/card#me>.
283287
```
284288

285289
#### Group Listings - Implementation Notes
286290

287291
When implementing support for `acl:agentGroup` and Group Listings, keep in mind
288292
the following issues:
289293

290-
1. Group Listings are regular documents (potentially with their own `.acl`s).
294+
1. Group Listings are regular documents (potentially each with its own `.acl`).
291295
2. What authentication mechanism should the ACL checking engine use, when making
292296
requests for Group Listing documents on other servers?
293297
3. Infinite request loops during ACL resolution become possible, if an `.acl`
@@ -306,14 +310,14 @@ To specify that you're giving a particular mode of access to *everyone*
306310
of *all* agents (the general public). For example:
307311

308312
```ttl
309-
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
310-
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
313+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
314+
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
311315
312316
<#authorization2>
313-
a acl:Authorization;
314-
acl:agentClass foaf:Agent; # everyone
315-
acl:mode acl:Read; # has Read-only access
316-
acl:accessTo <https://alice.databox.me/profile/card>. # to the public profile
317+
a acl:Authorization;
318+
acl:agentClass foaf:Agent; # everyone
319+
acl:mode acl:Read; # has Read-only access
320+
acl:accessTo <https://alice.databox.me/profile/card>. # to the public profile
317321
```
318322

319323
Note that this is a special case of `acl:agentClass` usage, since it doesn't
@@ -333,14 +337,14 @@ you can use
333337
of *all* authenticated agents. For example:
334338

335339
```ttl
336-
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
337-
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
340+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
341+
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
338342
339343
<#authorization2>
340-
a acl:Authorization;
341-
acl:agentClass acl:AuthenticatedAgent; # everyone
342-
acl:mode acl:Read; # has Read-only access
343-
acl:accessTo <https://alice.databox.me/profile/card>. # to the public profile
344+
a acl:Authorization;
345+
acl:agentClass acl:AuthenticatedAgent; # everyone
346+
acl:mode acl:Read; # has Read-only access
347+
acl:accessTo <https://alice.databox.me/profile/card>. # to the public profile
344348
```
345349

346350
Note that this is a special case of `acl:agentClass` usage, since it doesn't
@@ -400,8 +404,13 @@ In solid a maxim is, you have complete control of he data. Therefore it is up to
400404
- A writer could give in their profile a statement that they will allow readers to use a given app.
401405

402406
```
403-
<#me> acl:trustedApp [acl:origin <https://calendar.example.com>; acl:mode acl:Read , acl:Append].
404-
<#me> acl:trustedApp [acl:origin <https://contacts.example.com>; acl:mode acl:Read , acl:Write, acl:Control] .
407+
<#me> acl:trustedApp [ acl:origin <https://calendar.example.com>;
408+
acl:mode acl:Read,
409+
acl:Append].
410+
<#me> acl:trustedApp [ acl:origin <https://contacts.example.com>;
411+
acl:mode acl:Read,
412+
acl:Write,
413+
acl:Control].
405414
```
406415

407416
We define the owners of the resource as people given explicit Control access to it.
@@ -411,14 +420,15 @@ For each owner x, the server looks up the (extended?) profile, and looks in it f
411420
triple of the form
412421

413422
```
414-
?x acl:trustedApp ?y .
423+
?x acl:trustedApp ?y.
415424
```
416425
The set of trust objects is the accumulated set of ?y found in this way.
417426

418427
For the app ?z to have access, for every mode of access ?m required
419428
there must be some trust object ?y such that
420429
```
421-
?y acl:origin ?z ; acl:mode ?m .
430+
?y acl:origin ?z;
431+
acl:mode ?m.
422432
```
423433
Note access to different modes may be given in the same or different trust objects.
424434

@@ -490,21 +500,22 @@ An example ACL for a container would look something like:
490500

491501
```ttl
492502
# Contents of https://alice.databox.me/docs/.acl
493-
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
503+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
494504
495505
<#authorization1>
496-
a acl:Authorization;
506+
a acl:Authorization;
497507
498508
# These statements specify access rules for the /docs/ container itself:
499-
acl:agent <https://alice.databox.me/profile/card#me>;
500-
acl:accessTo <https://alice.databox.me/docs/>;
501-
acl:mode
502-
acl:Read, acl:Write, acl:Control;
503-
504-
# defaultForNew says: this authorization (the statements above) will also
505-
# be inherited by any resource within that container that doesn't have its
506-
# own ACL.
507-
acl:defaultForNew <https://alice.databox.me/docs/>.
509+
acl:agent <https://alice.databox.me/profile/card#me>;
510+
acl:accessTo <https://alice.databox.me/docs/>;
511+
acl:mode acl:Read,
512+
acl:Write,
513+
acl:Control;
514+
515+
# defaultForNew says: this authorization (the statements above)
516+
# will also be inherited by any resource within that container
517+
# that doesn't have its own ACL.
518+
acl:defaultForNew <https://alice.databox.me/docs/>.
508519
```
509520

510521
**Note:** The `acl:defaultForNew` predicate will soon be renamed to
@@ -546,9 +557,9 @@ need to be public-readable. THIS IS THE ONLY METHOD CURRENTLY IN USE
546557
**WebID-TLS Delegation**. If your implementation uses the WebID-TLS
547558
authentication method, it also needs to implement the ability to delegate its
548559
requests on behalf of the original user.
549-
(No, the original requester may not be akllowed access -- you don't have to ableForto
560+
(No, the original requester may not be allowed access -- you don't have to able to
550561
access a group to be in it)
551-
a discussion of such a capability,
562+
For a discussion of such a capability,
552563
see the [Extending the WebID Protocol with Access
553564
Delegation](http://bblfish.net/tmp/2012/08/05/WebID_Delegation.pdf) paper.
554565
One thing to keep in mind is - if there are several hops (an ACL request chain
@@ -640,8 +651,13 @@ guard against. In either case, the consequences are not disastrous.
640651
- A reader can ask to use a given app, by publishing the fact that she trusts a given app.
641652

642653
```
643-
<#me> acl:trustsForUse [acl:origin <https://calendar.example.com> acl:mode acl:Read , acl:Append].
644-
<#me> acl:trustsForUse [acl:origin <https://contacts.example.com> acl:mode acl:Read , acl:Write, acl:Control] .
654+
<#me> acl:trustsForUse [ acl:origin <https://calendar.example.com>;
655+
acl:mode acl:Read,
656+
acl:Append].
657+
<#me> acl:trustsForUse [ acl:origin <https://contacts.example.com>;
658+
acl:mode acl:Read,
659+
acl:Write,
660+
acl:Control].
645661
```
646662

647663
A writer could have also more sophisticated requirements, such as that any app Alice

0 commit comments

Comments
 (0)