-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathfosp.html
1714 lines (1446 loc) · 91.3 KB
/
fosp.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><title>The Federated Object Sharing Protocol</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="The Federated Object Sharing Protocol">
<meta name="keywords" content="FOSP">
<meta name="generator" content="xml2rfc v1.36 (http://xml.resource.org/)">
<style type='text/css'><!--
body {
font-family: verdana, charcoal, helvetica, arial, sans-serif;
font-size: small; color: #000; background-color: #FFF;
margin: 2em;
}
h1, h2, h3, h4, h5, h6 {
font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
font-weight: bold; font-style: normal;
}
h1 { color: #900; background-color: transparent; text-align: right; }
h3 { color: #333; background-color: transparent; }
td.RFCbug {
font-size: x-small; text-decoration: none;
width: 30px; height: 30px; padding-top: 2px;
text-align: justify; vertical-align: middle;
background-color: #000;
}
td.RFCbug span.RFC {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: bold; color: #666;
}
td.RFCbug span.hotText {
font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: normal; text-align: center; color: #FFF;
}
table.TOCbug { width: 30px; height: 15px; }
td.TOCbug {
text-align: center; width: 30px; height: 15px;
color: #FFF; background-color: #900;
}
td.TOCbug a {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
font-weight: bold; font-size: x-small; text-decoration: none;
color: #FFF; background-color: transparent;
}
td.header {
font-family: arial, helvetica, sans-serif; font-size: x-small;
vertical-align: top; width: 33%;
color: #FFF; background-color: #666;
}
td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
td.author-text { font-size: x-small; }
/* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
a.info {
/* This is the key. */
position: relative;
z-index: 24;
text-decoration: none;
}
a.info:hover {
z-index: 25;
color: #FFF; background-color: #900;
}
a.info span { display: none; }
a.info:hover span.info {
/* The span will display just on :hover state. */
display: block;
position: absolute;
font-size: smaller;
top: 2em; left: -5em; width: 15em;
padding: 2px; border: 1px solid #333;
color: #900; background-color: #EEE;
text-align: left;
}
a { font-weight: bold; }
a:link { color: #900; background-color: transparent; }
a:visited { color: #633; background-color: transparent; }
a:active { color: #633; background-color: transparent; }
p { margin-left: 2em; margin-right: 2em; }
p.copyright { font-size: x-small; }
p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
ol.text { margin-left: 2em; margin-right: 2em; }
ul.text { margin-left: 2em; margin-right: 2em; }
li { margin-left: 3em; }
/* RFC-2629 <spanx>s and <artwork>s. */
em { font-style: italic; }
strong { font-weight: bold; }
dfn { font-weight: bold; font-style: normal; }
cite { font-weight: normal; font-style: normal; }
tt { color: #036; }
tt, pre, pre dfn, pre em, pre cite, pre span {
font-family: "Courier New", Courier, monospace; font-size: small;
}
pre {
text-align: left; padding: 4px;
color: #000; background-color: #CCC;
}
pre dfn { color: #900; }
pre em { color: #66F; background-color: #FFC; font-weight: normal; }
pre .key { color: #33C; font-weight: bold; }
pre .id { color: #900; }
pre .str { color: #000; background-color: #CFF; }
pre .val { color: #066; }
pre .rep { color: #909; }
pre .oth { color: #000; background-color: #FCF; }
pre .err { background-color: #FCC; }
/* RFC-2629 <texttable>s. */
table.all, table.full, table.headers, table.none {
font-size: small; text-align: center; border-width: 2px;
vertical-align: top; border-collapse: collapse;
}
table.all, table.full { border-style: solid; border-color: black; }
table.headers, table.none { border-style: none; }
th {
font-weight: bold; border-color: black;
border-width: 2px 2px 3px 2px;
}
table.all th, table.full th { border-style: solid; }
table.headers th { border-style: none none solid none; }
table.none th { border-style: none; }
table.all td {
border-style: solid; border-color: #333;
border-width: 1px 2px;
}
table.full td, table.headers td, table.none td { border-style: none; }
hr { height: 1px; }
hr.insert {
width: 80%; border-style: none; border-width: 0;
color: #CCC; background-color: #CCC;
}
--></style>
</head>
<body>
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
<tr><td class="header">Network Working Group</td><td class="header">F. Maurer</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">September 2015</td></tr>
<tr><td class="header">Expires: March 4, 2016</td><td class="header"> </td></tr>
</table></td></tr></table>
<h1><br />The Federated Object Sharing Protocol<br />fosp-00</h1>
<h3>Abstract</h3>
<p>Federated Object Sharing Protocol (FOSP) is an application-level protocol that allows sharing arbitrary data,
setting access rights on the shared data and receiving notifications on changes.
It can be used in a federated network, e.g. between multiple independent providers.
It was designed to be the most simple solution that combines all these features.
</p>
<h3>Status of this Memo</h3>
<p>
This document is an Internet-Draft and is
NOT offered in accordance with Section 10 of RFC 2026,
and the author does not provide the IETF with any rights other
than to publish as an Internet-Draft.</p>
<p>
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current
Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p>
<p>
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any time.
It is inappropriate to use Internet-Drafts as reference material or to cite
them other than as “work in progress.”</p>
<p>
This Internet-Draft will expire on March 4, 2016.</p>
<a name="toc"></a><br /><hr />
<h3>Table of Contents</h3>
<p class="toc">
<a href="#intro">1.</a>
Introduction<br />
<a href="#purpose">1.1.</a>
Purpose<br />
<a href="#conventions">1.2.</a>
Conventions<br />
<a href="#requirements">1.3.</a>
Requirements<br />
<a href="#terminology">1.4.</a>
Terminology<br />
<a href="#overview">2.</a>
Overview<br />
<a href="#overview-user-and-provider">2.1.</a>
Users and providers<br />
<a href="#overview-data-structure">2.2.</a>
Trees, Objects and Attachments<br />
<a href="#overview-network-topology">2.3.</a>
Network topology<br />
<a href="#overview-messages">2.4.</a>
Messages<br />
<a href="#overview-bindings">2.5.</a>
Bindings<br />
<a href="#data-structure">3.</a>
Data structure<br />
<a href="#objects">3.1.</a>
Objects<br />
<a href="#data-structure-fields">3.2.</a>
Object attributes<br />
<a href="#obj-trees">3.3.</a>
Trees<br />
<a href="#data-structure-attachments">3.4.</a>
Attachments<br />
<a href="#std-objs">3.5.</a>
Provisioned Objects<br />
<a href="#network-topology">4.</a>
Network Topology<br />
<a href="#network-topology-client">4.1.</a>
Client<br />
<a href="#network-topology-server">4.2.</a>
Server<br />
<a href="#messages">5.</a>
Messages<br />
<a href="#msg-type">5.1.</a>
Types<br />
<a href="#msg-request">5.2.</a>
Request<br />
<a href="#msg-request-options">5.2.1.</a>
Options<br />
<a href="#msg-request-auth">5.2.2.</a>
Auth<br />
<a href="#msg-request-get">5.2.3.</a>
Get<br />
<a href="#msg-request-list">5.2.4.</a>
List<br />
<a href="#msg-request-create">5.2.5.</a>
Create<br />
<a href="#mgs-request-patch">5.2.6.</a>
Patch<br />
<a href="#msg-request-delete">5.2.7.</a>
Delete<br />
<a href="#msg-request-read">5.2.8.</a>
Read<br />
<a href="#msg-request-write">5.2.9.</a>
Write<br />
<a href="#msg-response">5.3.</a>
Response<br />
<a href="#msg-type-notification">5.4.</a>
Notification<br />
<a href="#msg-status-codes">5.5.</a>
Status codes<br />
<a href="#msg-status-codes-100">5.5.1.</a>
Informal 1xx<br />
<a href="#msg-status-codes-200">5.5.2.</a>
Successful 2xx<br />
<a href="#msg-status-codes-300">5.5.3.</a>
Redirection 3xx<br />
<a href="#msg-status-codes-400">5.5.4.</a>
Client error 4xx<br />
<a href="#msg-status-code-500">5.5.5.</a>
Server Error 5xx<br />
<a href="#msg-fowarding">5.6.</a>
Forwarding<br />
<a href="#bindings">6.</a>
Bindings<br />
<a href="#bindings-ws">6.1.</a>
WebSocket binding<br />
<a href="#bindings-ws-connection-initiation">6.1.1.</a>
Connection Initiation<br />
<a href="#bindings-ws-format">6.1.2.</a>
Format<br />
<a href="#bindings-ws-serialization">6.1.3.</a>
Serialization<br />
<a href="#bindings-https">6.2.</a>
HTTPS binding<br />
<a href="#bingings-http-mapping">6.2.1.</a>
Mapping<br />
<a href="#bindings-http-session-management">6.2.2.</a>
Session management<br />
<a href="#authentication-registration">7.</a>
Authentication and Registration<br />
<a href="#auth-anonymous">7.1.</a>
Anonymous<br />
<a href="#auth-sasl">7.2.</a>
SASL<br />
<a href="#auth-server">7.3.</a>
Server to server<br />
<a href="#registrations">7.4.</a>
Registration<br />
<a href="#policies">8.</a>
Policies<br />
<a href="#access-control">8.1.</a>
Access control<br />
<a href="#pol-groups">8.2.</a>
Groups<br />
<a href="#pol-subscriptions">8.3.</a>
Subscriptions<br />
<a href="#pol-attachments">8.4.</a>
Attachments<br />
<a href="#pol-auth">8.5.</a>
Authentication<br />
<a href="#pol-msg-forwarding">8.6.</a>
Message forwarding<br />
<a href="#discovery">9.</a>
Discovery<br />
<a href="#discovery-dns">9.1.</a>
DNS<br />
<a href="#discovery-well-known">9.2.</a>
Well known<br />
<a href="#rfc.references1">10.</a>
References<br />
<a href="#rfc.authors">§</a>
Author's Address<br />
</p>
<br clear="all" />
<a name="intro"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.
Introduction</h3>
<a name="purpose"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.1"></a><h3>1.1.
Purpose</h3>
<p>The Federated Object Storage Protocol (FOSP) is an application-level protocol
for exchanging structured and unstructured data generated by users of different providers.
It is designed to fulfill the needs of online social networks by combining necessary features into one simple protocol.
</p>
<p>FOSP aims to provide three core features:
</p>
<ol class="text">
<li>Store data online and support standard operations on it.
</li>
<li>Enforce access control on the data, for users from different hosts, without central authentication.
</li>
<li>Notify users when data is added, removed or has changed.
</li>
</ol><p>
</p>
<p>All these features must be available in a federated network.
Furthermore, some non-functional requirements are imposed.
The protocol needs to be data agnostic and should support structured, unstructured and meta-data.
It also must be as simple as possible, e.g. it must be easy to implement and it should be possible to write easy to deploy applications for it.
</p>
<a name="conventions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.2"></a><h3>1.2.
Conventions</h3>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a>.
</p>
<p>This document also makes use of the augmented Backus-Naur Form (<a class='info' href='#RFC5234'>[RFC5234]<span> (</span><span class='info'>Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.</span><span>)</span></a>) to formally describe the syntax of messages.
</p>
<a name="requirements"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.3"></a><h3>1.3.
Requirements</h3>
<p>FOSP builds on existing protocols and data formats.
The transport protocol for FOSP messages currently is the WebSocket protocol as defined in <a class='info' href='#RFC6455'>[RFC6455]<span> (</span><span class='info'>Fette, I. and A. Melnikov, “The WebSocket Protocol,” December 2011.</span><span>)</span></a> and a HTTP (<a class='info' href='#RFC7230'>[RFC7230]<span> (</span><span class='info'>Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing,” June 2014.</span><span>)</span></a>) binding is in the works.
Other options may be added in the future.
Objects are serialized into the JavaScript Object Notation (JSON) according to <a class='info' href='#RFC7159'>[RFC7159]<span> (</span><span class='info'>Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format,” March 2014.</span><span>)</span></a>.
Besides these technical dependencies, FOSP is inspired by WebDAV (<a class='info' href='#RFC4918'>[RFC4918]<span> (</span><span class='info'>Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.</span><span>)</span></a>) and XMPP (<a class='info' href='#RFC6120'>[RFC6120]<span> (</span><span class='info'>Saint-Andre, P., “Extensible Messaging and Presence Protocol (XMPP): Core,” March 2011.</span><span>)</span></a>) and has similarities to LDAP (<a class='info' href='#RFC4370'>[RFC4370]<span> (</span><span class='info'>Weltman, R., “Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control,” February 2006.</span><span>)</span></a>).
</p>
<a name="terminology"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.4"></a><h3>1.4.
Terminology</h3>
<p>This document uses a number of terminologies to refer to concepts found in FOSP.
</p>
<blockquote class="text"><dl>
<dt>provider</dt>
<dd>An entity that provides storage space on the Internet for the data of users.
It is identified by a fully qualified domain name.
</dd>
<dt>server</dt>
<dd>A FOSP server stores the data of users of a certain provider.
The term server applies to the the software that processes request as well as to the machine that runs the software.
For fault tolerance and load balancing purposes, a provider might deploy multiple servers.
</dd>
<dt>client</dt>
<dd>A FOSP client is a program a user uses to communicate with a FOSP server.
It facilitates accessing the data of the user that is stored on the server.
</dd>
<dt>message</dt>
<dd>A message is the basic unit of communication in FOSP.
Messages come in three different flavors.
</dd>
<dt>request</dt>
<dd>A request is a message sent from a client to a server.
It is used to retrieve or alter data.
</dd>
<dt>response</dt>
<dd>A response is a message sent from a server to a client.
It is always sent as an answer to a request and contains the status of the request and possibly data.
</dd>
<dt>notification</dt>
<dd>A notification is a message that is sent by servers when changes happen to an object.
</dd>
<dt>object</dt>
<dd>An object is the basic unit of data in FOSP.
It consists of structured data expressed in JSON.
</dd>
<dt>attachment</dt>
<dd>An attachment is a binary or text file that is associated with an object.
Each object can only have one attachment.
</dd>
<dt>tree</dt>
<dd>The objects of a users form a tree structure.
Each object has exactly one parent object, except for the root object.
There exists exactly one tree per user.
</dd>
</dl></blockquote><p>
</p>
<a name="overview"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.
Overview</h3>
<p>This section provides a short overview.
It is intended to familiarize with the concepts of FOSP.
It does not contain information that is not covered in the rest of the document except for the information about users and providers and can be skipped.
</p>
<a name="overview-user-and-provider"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2.1"></a><h3>2.1.
Users and providers</h3>
<p>FOSP concerns itself with data created by users.
Users store their content on the servers of providers and can share it by setting the appropriate access rights for other users.
Each user is registered with one provider.
The user has an unique name at the provider that together with the domain name of the provider forms his or her identifier, similar to an Email address.
However users can still share their content with friends that are registered with different providers.
</p>
<p>Providers are companies or individuals that provide storage to users.
A provider is identified by a fully qualified domain name.
Similar to Email and XMPP, everybody can be a provider by simply hosting his or her own FOSP server.
The servers of different providers communicate to allow users of different providers to share data.
</p>
<a name="overview-data-structure"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2.2"></a><h3>2.2.
Trees, Objects and Attachments</h3>
<p>The basic data units that can be stored on the server have a well defined structure and we call them objects.
We chose this name because they are objects in the sense of the JSON specification.
Other familiar terms for a JSON object might be dictionary, hash map of associative array.
They consist of key-value pairs where each key is a string and each value is one of the values allowed by JSON.
Most of the key-value pairs have a special meaning, for example there is a key-value pair that stores the access control list.
</p>
<p>All objects are part of a tree.
For each user, one such tree exists and the root object of the tree is named like the user.
Each object can thus be uniquely identified by its path, e.g. [email protected]/social/me.
</p>
<p>To store data that can not be expressed in JSON, each object can have an attachment.
The attachment has the same resource name as the object but is modified using special requests.
</p>
<a name="overview-network-topology"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2.3"></a><h3>2.3.
Network topology</h3>
<p>FOSP follows the client-server paradigm.
The network topology is similar to the SMTP or XMPP network.
A provider operates one or more server that handle the domain of the provider.
A user can use a client to connect to a server of a provider where he or she is registered and request data.
</p>
<p>The server can connect to a server of a different provider to forward request it can not process itself.
This is the case when the request concerns an object that is not stored by this server because it belongs to a user of a different provider.
</p>
<a name="overview-messages"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2.4"></a><h3>2.4.
Messages</h3>
<p>The communication between FOSP clients and servers is segmented into messages.
There a three different kind of messages: requests, responses and notifications.
</p>
<p>To create, alter or delete objects and attachments, a client sends a request to the server.
When the request is processed, the server sends a response.
If the request concerns an object that the server does not store, it may be forwarded to a server that does store it.
</p>
<p>As users and clients might be interested in changes to objects and attachments, they can subscribe to events on objects.
When a server makes changes to objects or attachments, it can send notifications to clients that inform about events that happened.
</p>
<a name="overview-bindings"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2.5"></a><h3>2.5.
Bindings</h3>
<p>The messages are transported using existing protocols.
A definition of how FOSP messages are transported through an existing protocol is called binding.
</p>
<p>The currently defined binding is the WebSocket binding.
An HTTP binding, which will not support all FOSP features, is also being worked on.
</p>
<a name="data-structure"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.
Data structure</h3>
<p>FOSP allows users to store structured data in objects and everything else in attachments, which each belong to an object.
The objects are all part of a tree and each user owns one such tree.
</p>
<a name="objects"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.1"></a><h3>3.1.
Objects</h3>
<p>We refer to the basic unit of data, that can be manipulated in the FOSP network, as an object.
An object consists of key-value pairs.
The constraints for keys and values are the ones described by the JSON specification.
Each object has by default specific key value pairs that have a special meaning, for example, the key “owner” contains the identifier of the user who created the object.
When transferring objects in messages, the object is serialized according to the JSON specification.
In the rest of the document we will refer to a key-value pair of an object either as an attribute or a field of an object.
</p><br /><hr class="insert" />
<a name="fig-object-example"></a>
<p>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
{
"created": "2007-03-01T13:00:00Z",
"updated": "2008-05-11T15:30:00Z",
"owner": "[email protected]",
"acl": {
"owner": {
"data": [ "read", "write" ],
"acl": [ "read", "write" ],
"subscriptions": [ "read", "write" ],
"children": [ "read", "write", "delete" ]
},
"users": {
"[email protected]": {
"data": [ "read", "not-write" ],
"acl": [ "read", "not-write" ],
"subscriptions": [ "read", "not-write" ]
}
}
},
"subscriptions": {
"users": {
"[email protected]": {
"events": [ "created", "updated" ],
"depth": 1
}
}
},
"attachment": {
"name": "hatter.jpg",
"type": "image/jpeg",
"size": 140385
},
"type": "text/plain",
"data": "Just plain text"
}
</pre></div>
<p>
</p><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 1 </b></font><br /></td></tr></table><hr class="insert" />
<p>Each object is part of a tree of objects that belong to a user.
Therefore, each object can be addressed by an internationalized resource identifier (IRI <a class='info' href='#RFC3987'>[RFC3987]<span> (</span><span class='info'>Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.</span><span>)</span></a>).
The syntax for an object borrows from the IRI definition and is as follows.
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
<dfn>resource-id</dfn> = <span class='rep'>1*</span><cite class='id'>iunreserved</cite> "<span class='str'>@</span>" <cite class='id'>ihost</cite> <cite class='id'>ipath-absolute</cite>
</pre></div><p>
</p>
<a name="data-structure-fields"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.2"></a><h3>3.2.
Object attributes</h3>
<p>Most attributes of an object have a well defined meaning.
The servers have to ensure that the content of these attributes adheres to the specification and that users do not make changes that are not allowed.
<a class='info' href='#fig-object-example'>Figure 1</a> shows an example of an objects with all the fields described here.
Currently we define the following attributes and their values:
</p>
<blockquote class="text">
<p>The “owner” field is set by the server on creation of the object and contains the identifier of the user who created the object as a string.
It determines the ownership of this object and is used when enforcing access rights.
The user MUST NOT be able to set the field to a different value.
</p>
<p>The “created” (birth time) field is set by the server to the date of creation of the object.
It is stored as a string, formatted according to the ISO 8601 standard and must always be in the UTC time zone.
The user MUST NOT be able to set the field to a different value.
</p>
<p>Similar the “updated” (modify time) is set to the current date each time the object is altered and is not to be set by the users directly.
It is stored just like “created”.
In the future it might be used to allow client side caching similar to ETags in HTTP.
The user MUST NOT be able to set the field to a different value.
</p>
<p>The “data” field is where the user should store the payload and may contain any valid value.
The “type” field should contain a string that describes the content type of the “data” field, similar to MIME types.
These two fields are the only fields where the user can store arbitrary data.
The server MUST allow the user to store any data in these fields.
</p>
</blockquote><p>
</p>
<p>Furthermore, there are the three fields “acl”, “subscriptions” and “attachment” that contain more complex objects.
</p>
<p>The “acl” field stores information about access rights in form of an object.
It is read by the server to enforce access control.
</p>
<blockquote class="text">
<p>The acl object can have the following fields: “owner”, “users”, “groups”, “other”
</p>
<p>The value of the “owner” and “other” field is a set of rights
</p>
<p>A set of rights is an object where each key identifies a certain scope the right applies to, and the value is a string array of permissions.
For example, the key ”acl” means that the permissions apply to the acl field of the object.
Currently allowed values for the key are “acl”, “data”, “subscriptions“, “children“.
The permissions can be “read”, “write“ and “delete”.
They can also be prefixed with “not-“ to revoke a right, which is necessary because rights are inherited.
This will be further explained in <a class='info' href='#access-control'>Section 8.1<span> (</span><span class='info'>Access control</span><span>)</span></a>.
</p>
<p>The value of the “users” and “groups” field is an object.
In these objects, each key identifies a user or a group and the related value is a set of rights.
</p>
</blockquote><p>
</p>
<p>The “subscriptions” field stores information about subscriptions.
It is read by the server to determine which users have to be notified on changes to an object.
</p>
<blockquote class="text">
<p>It contains an object and each key is the identifier of a user.
</p>
<p>The value is an object with the fields: “events” and “depth”
</p>
<p>The value of “events” is an array of strings which identify an event, the value of “depth” is an integer between -1 and infinity
</p>
</blockquote><p>
How this field is evaluated by the server is explained in <a class='info' href='#pol-subscriptions'>Section 8.3<span> (</span><span class='info'>Subscriptions</span><span>)</span></a>.
</p>
<p>The “attachment” field is only present if this object has an attachment.
It contains an object with three fields.
</p>
<blockquote class="text">
<p>The “name” field contains a string with the file name.
</p>
<p>The “size” field contains the number of bytes of the attached file.
The value of this field MUST be set by the server whenever a WRITE request changes the size of the file.
The value of this field MUST NOT be set by a user.
</p>
<p>The “type” field contains a string with the mime-type of the attached file.
</p>
</blockquote><p>
</p>
<a name="obj-trees"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.3"></a><h3>3.3.
Trees</h3>
<p>In FOSP, all objects are part of a tree of objects.
Therefore, all objects have a parent object, except for the root object of a tree.
Consequently, all objects can have child objects.
For each user there exists one tree of objects and the root node of this tree is named like the identifier of the user.
The tree of the user is stored on the servers that are responsible for the domain of the provider where the user is registered.
<br /><hr class="insert" />
<a name="fig-tree-example"></a>
<p>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+--------------------+
+---+------------+---+
| |
| |
+---+--+ +--+---+
|config| |social|
+------+ +----+-+
|
|
++-+
+----------> |me|
| +--+
+
[email protected]/social/me
</pre></div>
<p>
</p><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 2 </b></font><br /></td></tr></table><hr class="insert" />
<a name="data-structure-attachments"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.4"></a><h3>3.4.
Attachments</h3>
<p>As files, like pictures and documents, are also shared via social networks, FOSP supports saving binary files.
For each object, one file can be stored as an attachment.
This way, files can be addressed with the same schema and the objects they are attached to can provide the meta-data.
If an object has a belonging file, it is extended by a new attribute named “attachment”.
In this attribute, the "size", file "name", and MIME "type" of the file is stored.
The attached file is read and written using special requests.
</p>
<a name="std-objs"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.5"></a><h3>3.5.
Provisioned Objects</h3>
<p>Some objects in the tree of a user will be used by the server to obtain configuration options.
For example [email protected]/config/groups will contain the mappings from users to groups that are valid for the tree [email protected].
These objects will be created by the server when the user first registers with it.
</p>
<a name="network-topology"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.
Network Topology</h3>
<p>In the FOSP network, agents are either clients or servers.
</p>
<a name="network-topology-client"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4.1"></a><h3>4.1.
Client</h3>
<p>A user connects, using a client, to the server of their provider.
We refer to this server as the home server of the user.
To manipulate or access data, the user uses the client to send requests.
</p>
<p>A client can be any programm that understands the FOSP protocol.
</p>
<a name="network-topology-server"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4.2"></a><h3>4.2.
Server</h3>
<p>A server is a software running on a machine on the internet, that processes requests of clients.
Each server belongs to one provider that is identified by a domain name.
For load balancing purposes, more than one server per domain/provider might be used.
To keep the examples simple, we nevertheless assume that there is one server per provider.
</p>
<p>A request can act upon a resource.
If the resource is not managed by the server the user is connected to, the server will relay the request to the responsible server.
Hence, FOSP servers may open connections to other FOSP servers.
</p><br /><hr class="insert" />
<a name="fig-network-topology"></a>
<p>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+--------------+ +--------------+
|alice@ | |queen@ |
|wonderland.lit| |wonderland.lit|
+------------+-+ +-+------------+
| |
| |
| |
+--v--------v--+
|wonderland.lit|
| |
+---+------^---+
| |
| |
+---v------+---+
|realworld.lit |
| |
+--^-----------+
|
|
+-----------+--+
| sister@ |
| realworld.lit|
+--------------+
</pre></div>
<p>
</p><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 3 </b></font><br /></td></tr></table><hr class="insert" />
<a name="messages"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.
Messages</h3>
<p>Messages are the basic unit of communication in the FOSP network.
There are three different types of messages which serve different purposes.
How a message is serialized depends on the protocol that is used to transport the message.
</p>
<a name="msg-type"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.1"></a><h3>5.1.
Types</h3>
<p>Each message has a specific type, which determines the kind of purpose this message serves.
The type is implicitly given in the way that the content of the message determines it’s type.
For now there are only three types of messages needed to support all functionality.
The types are requests, responses and notifications.
Should there be the need for additional types of messages, a new one can be added in later versions of the protocol.
</p>
<p>All messages can have headers and a body, similar to HTTP messages and are distinguished by their main attributes.
Requests and notifications usually act on, or are emitted from an object or an attachemnt.
The identifier of the object or attachemnt is then part of the request.
If a request does not act upon an object, the identifier is replaced with an asterisk.
</p>
<a name="msg-request"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2"></a><h3>5.2.
Request</h3>
<p>Requests are sent from clients to servers to authenticate or manipulate objects.
A request consists of ...
</p>
<blockquote class="text">
<p>a request type
</p>
<p>optionally an identifier of a resource that it manipulates
</p>
</blockquote><p>
</p>
<p>The content of the body depends on the type of request.
For example, the body of a GET or DELETE request is empty and the body of a CREATE request contains the new object.
In general the body is a JSON object, except for the WRITE request that has the byte representation of the file as the body.
</p>
<p>The server MUST always responde to a request with a response message.
Depending on the request, the server must check access rights and whether a certain object exits, bevor the request can be processed.
If the user does not have sufficent rights or an required object does not exist (e.g. a parent object when creating a child), a failure response MUST be sent.
When the request is successfully processed, a success response MUST be sent.
Depending on the request, it may contain information in its body, like the object that was requested, or an attachment that was read.
</p>
<p>The request types are described in the following sections.
</p>
<a name="msg-request-options"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.1"></a><h3>5.2.1.
Options</h3>
<p>The OPTIONS request is used to discover the capabilities of the server.
Currently, the only use is to detect supported SASL mechanisms.
When detecting capabilities of the whole server, the request URL is replaced by "*".
</p>
<p>The server MUST return a 200 response and a body that contains information about it's capabilities.
The returned object MUST contain a field named "sasl" which in turn contains an object with a field named "mechanisms".
This field contains an array of all supported SASL mechanisms.
</p>
<p>In the future, the OPTIONS request might be used to discover allowed operations on resources.
</p>
<a name="msg-request-auth"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.2"></a><h3>5.2.2.
Auth</h3>
<p>The AUTH request is used to authenticate the client.
The authentication uses the SASL framework.
How SASL messages are transported is defined in <a class='info' href='#auth-sasl'>Section 7.2<span> (</span><span class='info'>SASL</span><span>)</span></a>.
Multiple requests might be needed to successfully authenticate, depending on the mechanism.
</p>
<p>
The server verifies that the authentication is successfull and sents a success response or a failed response otherwise.
All future request are made in the name of this authenticated user.
How the state is kept depends on the transport protocol used.
It can for example either be a tied to network connection, or be a cookie supplied in each request.
</p>
<a name="msg-request-get"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.3"></a><h3>5.2.3.
Get</h3>
<p>The GET request is used to retrieve an object.
The resource identifier in the request denotes the object that should be returned.
The server MUST ignore any content in the body of the request.
</p>
<p>If the request was successfull, the object is returned in the body of the response..
Even on success, not the whole object might be returned as the user might have the right to read some attributes but not others.
</p>
<a name="msg-request-list"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.4"></a><h3>5.2.4.
List</h3>
<p>The LIST request is used to discover all child objects of a certain object.
The resource identifier specifies the object of which the children should be returned.
</p>
<p>If successfull, the response contains an array of names of the child objects.
</p>
<a name="msg-request-create"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.5"></a><h3>5.2.5.
Create</h3>
<p>The CREATE request is used to store new objects on the server.
The resource identifier is the desired location for the new object.
The body containes the object to store.
</p>
<p>On success, an empty success response is returned and the object is stored at the given location.
</p>
<a name="mgs-request-patch"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.6"></a><h3>5.2.6.
Patch</h3>
<p>The PATCH request is used to update an already existing object on the server.
The resource identifier specifies the object that should be updated.
The body containes an object with the differences that should be applied to the object.
The semantics of the patch object and the algorithm to apply it are the ones defined in <a class='info' href='#RFC7396'>[RFC7396]<span> (</span><span class='info'>Hoffman, P. and J. Snell, “JSON Merge Patch,” October 2014.</span><span>)</span></a>.
</p>
<p>The differences are merged into the object as follows.
If the original object does not have an attribute the differences object has, the attribute is copied to the object.
If the original object already has an attribute the differences object has and the new value is "null", the attribute is deleted from the object.
If the original object already has an attribute the differences object has and the value is not "null", the attribute is replaced with the new attribute except when the value of the old and the new attribute are both an object.
In this case the merging is done on the attribute recursivly as it is on the whole object.
</p>
<p>On success, the updated object is returned.
</p>
<a name="msg-request-delete"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2.7"></a><h3>5.2.7.
Delete</h3>
<p>The DELETE request is used to remove an object from a tree.
The resource identifier specifies the object that should be removed.
</p>
<p>If the object that should be deleted has children, the DELETE request MUST fail and a 409 response MUST be returned.
In the future, a header might be supported to enable recursive deleting of objects.