fosp.html

<!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">&nbsp;TOC&nbsp;</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">&nbsp;</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&nbsp;10 of RFC&nbsp;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 &ldquo;work in progress.&rdquo;</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>&nbsp;
Introduction<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#purpose">1.1.</a>&nbsp;
Purpose<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#conventions">1.2.</a>&nbsp;
Conventions<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#requirements">1.3.</a>&nbsp;
Requirements<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#terminology">1.4.</a>&nbsp;
Terminology<br />
<a href="#overview">2.</a>&nbsp;
Overview<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview-user-and-provider">2.1.</a>&nbsp;
Users and providers<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview-data-structure">2.2.</a>&nbsp;
Trees, Objects and Attachments<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview-network-topology">2.3.</a>&nbsp;
Network topology<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview-messages">2.4.</a>&nbsp;
Messages<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview-bindings">2.5.</a>&nbsp;
Bindings<br />
<a href="#data-structure">3.</a>&nbsp;
Data structure<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#objects">3.1.</a>&nbsp;
Objects<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#data-structure-fields">3.2.</a>&nbsp;
Object attributes<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#obj-trees">3.3.</a>&nbsp;
Trees<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#data-structure-attachments">3.4.</a>&nbsp;
Attachments<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#std-objs">3.5.</a>&nbsp;
Provisioned Objects<br />
<a href="#network-topology">4.</a>&nbsp;
Network Topology<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#network-topology-client">4.1.</a>&nbsp;
Client<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#network-topology-server">4.2.</a>&nbsp;
Server<br />
<a href="#messages">5.</a>&nbsp;
Messages<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-type">5.1.</a>&nbsp;
Types<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request">5.2.</a>&nbsp;
Request<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-options">5.2.1.</a>&nbsp;
Options<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-auth">5.2.2.</a>&nbsp;
Auth<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-get">5.2.3.</a>&nbsp;
Get<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-list">5.2.4.</a>&nbsp;
List<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-create">5.2.5.</a>&nbsp;
Create<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mgs-request-patch">5.2.6.</a>&nbsp;
Patch<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-delete">5.2.7.</a>&nbsp;
Delete<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-read">5.2.8.</a>&nbsp;
Read<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-request-write">5.2.9.</a>&nbsp;
Write<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-response">5.3.</a>&nbsp;
Response<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-type-notification">5.4.</a>&nbsp;
Notification<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-status-codes">5.5.</a>&nbsp;
Status codes<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-status-codes-100">5.5.1.</a>&nbsp;
Informal 1xx<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-status-codes-200">5.5.2.</a>&nbsp;
Successful 2xx<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-status-codes-300">5.5.3.</a>&nbsp;
Redirection 3xx<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-status-codes-400">5.5.4.</a>&nbsp;
Client error 4xx<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-status-code-500">5.5.5.</a>&nbsp;
Server Error 5xx<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#msg-fowarding">5.6.</a>&nbsp;
Forwarding<br />
<a href="#bindings">6.</a>&nbsp;
Bindings<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bindings-ws">6.1.</a>&nbsp;
WebSocket binding<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bindings-ws-connection-initiation">6.1.1.</a>&nbsp;
Connection Initiation<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bindings-ws-format">6.1.2.</a>&nbsp;
Format<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bindings-ws-serialization">6.1.3.</a>&nbsp;
Serialization<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bindings-https">6.2.</a>&nbsp;
HTTPS binding<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bingings-http-mapping">6.2.1.</a>&nbsp;
Mapping<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bindings-http-session-management">6.2.2.</a>&nbsp;
Session management<br />
<a href="#authentication-registration">7.</a>&nbsp;
Authentication and Registration<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#auth-anonymous">7.1.</a>&nbsp;
Anonymous<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#auth-sasl">7.2.</a>&nbsp;
SASL<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#auth-server">7.3.</a>&nbsp;
Server to server<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#registrations">7.4.</a>&nbsp;
Registration<br />
<a href="#policies">8.</a>&nbsp;
Policies<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#access-control">8.1.</a>&nbsp;
Access control<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#pol-groups">8.2.</a>&nbsp;
Groups<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#pol-subscriptions">8.3.</a>&nbsp;
Subscriptions<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#pol-attachments">8.4.</a>&nbsp;
Attachments<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#pol-auth">8.5.</a>&nbsp;
Authentication<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#pol-msg-forwarding">8.6.</a>&nbsp;
Message forwarding<br />
<a href="#discovery">9.</a>&nbsp;
Discovery<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#discovery-dns">9.1.</a>&nbsp;
DNS<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#discovery-well-known">9.2.</a>&nbsp;
Well known<br />
<a href="#rfc.references1">10.</a>&nbsp;
References<br />
<a href="#rfc.authors">&#167;</a>&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1.1"></a><h3>1.1.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1.2"></a><h3>1.2.&nbsp;
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., &ldquo;Key words for use in RFCs to Indicate Requirement Levels,&rdquo; March&nbsp;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, &ldquo;Augmented BNF for Syntax Specifications: ABNF,&rdquo; January&nbsp;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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1.3"></a><h3>1.3.&nbsp;
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, &ldquo;The WebSocket Protocol,&rdquo; December&nbsp;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., &ldquo;Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing,&rdquo; June&nbsp;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., &ldquo;The JavaScript Object Notation (JSON) Data Interchange Format,&rdquo; March&nbsp;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., &ldquo;HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),&rdquo; June&nbsp;2007.</span><span>)</span></a>) and XMPP (<a class='info' href='#RFC6120'>[RFC6120]<span> (</span><span class='info'>Saint-Andre, P., &ldquo;Extensible Messaging and Presence Protocol (XMPP): Core,&rdquo; March&nbsp;2011.</span><span>)</span></a>) and has similarities to LDAP (<a class='info' href='#RFC4370'>[RFC4370]<span> (</span><span class='info'>Weltman, R., &ldquo;Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control,&rdquo; February&nbsp;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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1.4"></a><h3>1.4.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2.1"></a><h3>2.1.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2.2"></a><h3>2.2.&nbsp;
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. alice@wonderland.lit/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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2.3"></a><h3>2.3.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2.4"></a><h3>2.4.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2.5"></a><h3>2.5.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3.1"></a><h3>3.1.&nbsp;
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": "alice@wonderland.lit",
  "acl": {
    "owner": {
      "data": [ "read", "write" ],
      "acl": [ "read", "write" ],
      "subscriptions": [ "read", "write" ],
      "children": [ "read", "write", "delete" ]
      },
    "users": {
      "alice@wonderland.lit": {
        "data": [ "read", "not-write" ],
        "acl": [ "read", "not-write" ],
        "subscriptions": [ "read", "not-write" ]
      }
    }
  },
  "subscriptions": {
    "users": {
      "alice@wonderland.lit": {
        "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>&nbsp;Figure&nbsp;1&nbsp;</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, &ldquo;Internationalized Resource Identifiers (IRIs),&rdquo; January&nbsp;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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3.2"></a><h3>3.2.&nbsp;
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&nbsp;1</a>&nbsp;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&nbsp;<a class='info' href='#access-control'>Section&nbsp;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&nbsp;<a class='info' href='#pol-subscriptions'>Section&nbsp;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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3.3"></a><h3>3.3.&nbsp;
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>

   +--------------------+
   |alice@wonderland.lit|
   +---+------------+---+
       |            |
       |            |
   +---+--+      +--+---+
   |config|      |social|
   +------+      +----+-+
                      |
                      |
                     ++-+
        +----------&gt; |me|
        |            +--+
        +
alice@wonderland.lit/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>&nbsp;Figure&nbsp;2&nbsp;</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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3.4"></a><h3>3.4.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3.5"></a><h3>3.5.&nbsp;
Provisioned Objects</h3>

<p>Some objects in the tree of a user will be used by the server to obtain configuration options.
    For example alice@wonderland.lit/config/groups will contain the mappings from users to groups that are valid for the tree alice@wonderland.lit.
    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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.4.1"></a><h3>4.1.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.4.2"></a><h3>4.2.&nbsp;
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>&nbsp;Figure&nbsp;3&nbsp;</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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.1"></a><h3>5.2.1.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.2"></a><h3>5.2.2.&nbsp;
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&nbsp;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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.3"></a><h3>5.2.3.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.4"></a><h3>5.2.4.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.5"></a><h3>5.2.5.&nbsp;
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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.6"></a><h3>5.2.6.&nbsp;
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, &ldquo;JSON Merge Patch,&rdquo; October&nbsp;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">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.7"></a><h3>5.2.7.&nbsp;
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.
      
</p>
<p>If successfull, a succeeded message is returned and the object is permanently removed.
      
</p>
<a name="msg-request-read"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.8"></a><h3>5.2.8.&nbsp;
Read</h3>

<p>The READ request is used to read the attachment.
      The resource identifier specifies the object of which the attachment should be read.
      
</p>
<p>The success response body contains the raw bytes of the attachment.
      
</p>
<a name="msg-request-write"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.2.9"></a><h3>5.2.9.&nbsp;
Write</h3>

<p>The WRITE request is used to write to the attachment.
      The resource identifier specifies the object of which the attachment should be written.
      The body contains the raw bytes of the attachment.
      
</p>
<p>The success response is empty.
      
</p>
<a name="msg-response"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.3"></a><h3>5.3.&nbsp;
Response</h3>

<p>Responses are sent from servers to clients when a request has been processed.
    A response has ...
    </p>
<blockquote class="text">
<p>a type, either “SUCCEEDED” or “FAILED”.
</p>
<p>a status code, an integer greater zero.
</p>
</blockquote><p>
    
</p>
<p>The body of a response depends on the request that is answered.
    For a CREATE or DELETE request it would be empty, for a GET request it would be the object that was requested.
    In case of a READ request it would contain the raw bytes of the attachment.
    
</p>
<p>The status code is explained in&nbsp;<a class='info' href='#msg-status-codes'>Section&nbsp;5.5<span> (</span><span class='info'>Status codes</span><span>)</span></a>.
    
</p>
<p>An FAILED response SHOULD contain an object describing the error that occured.
    The object should contain a "message" attribute with a string value that explains the error.
    
</p>
<a name="msg-type-notification"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.4"></a><h3>5.4.&nbsp;
Notification</h3>

<p>Notifications are sent from servers to clients when objects change and the client
    has subscribed to those changes. A notification consists of ...
    </p>
<blockquote class="text">
<p>an event which is one of “CREATED”, “UPDATED” or “DELETED”.
</p>
<p>a resource identifier.
</p>
</blockquote><p>
    
</p>
<p>The notifications are sent when a request triggers an event, for example CREATE triggers a CREATED event.
    If the event equals DELETED then the body of the notification must be empty.
    Otherwise it should contain the new version of the object.
    
</p>
<p>When and to who notifications are sent is explained in&nbsp;<a class='info' href='#pol-subscriptions'>Section&nbsp;8.3<span> (</span><span class='info'>Subscriptions</span><span>)</span></a>.
    
</p>
<a name="msg-status-codes"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.5"></a><h3>5.5.&nbsp;
Status codes</h3>

<p>The status codes reuse and extend the status codes used in HTTP.
    They are wildly known and also used in similar fashion in other protocols.
    The status codes are also divided into the same classes, with the same meaning.
    Not all status codes of HTTP are used, but all are reserved and MUST NOT be used for custom statuses.
    
</p>
<a name="msg-status-codes-100"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.5.1"></a><h3>5.5.1.&nbsp;
Informal 1xx</h3>

<p>The 1xx status codes are not used at the moment.
      A client MUST ignore any such responses and continue to wait for a final response.
      
</p>
<a name="msg-status-codes-200"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.5.2"></a><h3>5.5.2.&nbsp;
Successful 2xx</h3>

<p>The 2xx status codes indicate that the request was successful.
      </p>
<blockquote class="text"><dl>
<dt>200 OK</dt>
<dd>The request has succeeded.
</dd>
<dt>201 Created</dt>
<dd>The request has succeeded and a new object has been created.
</dd>
<dt>204 No Content</dt>
<dd>The request has succeeded but no content is returned.
	This can be for example the case when a DELETE request has been sent.
	
</dd>
</dl></blockquote><p>
      
</p>
<a name="msg-status-codes-300"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.5.3"></a><h3>5.5.3.&nbsp;
Redirection 3xx</h3>

<p>The 3xx status codes indicate that the requested object can be found elsewhere.
      </p>
<blockquote class="text"><dl>
<dt>301 Moved Permanently</dt>
<dd>The object was moved permanently and is now found at the location indicated in the "Location" header.
        Moving objects is not yet supported but might be in the future.
        Clients SHOULD be able to understand this status and in case of a GET, LIST or READ request MAY resent the request with the new location.
        However, a client MUST never automatically resent the request if the request alters the object, e.g. is a CREATE, PATCH, DELETE or WRITE request.
        
</dd>
<dt>304 Not Modified</dt>
<dd>If the request did contain a condition that checks for the modification date and the object did not change, the server SHOULD respond with this status code.
        Conditional requests are not supported yet, but might be in the future.
        
</dd>
<dt>310 Additional data needed</dt>
<dd>This status code can only be returned while authenticating.
        If the used SASL mechanism requires the server to return a challenge before continuing authentication, this response code MUST be returned.
        
</dd>
</dl></blockquote><p>
      
</p>
<a name="msg-status-codes-400"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.5.4"></a><h3>5.5.4.&nbsp;
Client error 4xx</h3>

<p>The 4xx status codes indicate that the client made an error.
      </p>
<blockquote class="text"><dl>
<dt>400 Bad Request</dt>
<dd>The request could not be parsed by the server due to malformed syntax.
</dd>
<dt>401 Unauthorized</dt>
<dd>The client tried to send a request that needs authentication but is not yet authenticated.
	The client must make a successful AUTH request bevor retrying this request.
	
</dd>
<dt>403 Forbidden</dt>
<dd>The client does not have the necessary permissions.
	If the server MUST only return this status if the client is already authenticated.
	
</dd>
<dt>404 Not Found</dt>
<dd>The object the client requested could not be found.
</dd>
<dt>405 Method Not Allowed</dt>
<dd>The request method is not allowed on this object.
	This status can be returned if a client tries to READ and attachment of an object without attachment.
	
</dd>
<dt>409 Conflict</dt>
<dd>The request could not be completed due to a conflict with an resource.
	This status MUST be returned by the server if the client tries to create an object that already exists.
	
</dd>
<dt>412 Precondition Failed</dt>
<dd>If the request did contain a condition and condition is not satisfied, then the server MUST return this status.
	Conditional request are not supported yet, but might be in the future.
	This status can also be returned if a new object should be created but the parent object does not exist.
	
</dd>
<dt>413 Request Entity Too Large</dt>
<dd>The server might choose to accept only messages smaller than a certain size.
	In this case, if a client tries to send a larger message, the server CAN respond with this status and drop the request.
	
</dd>
</dl></blockquote><p>
      
</p>
<a name="msg-status-code-500"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.5.5"></a><h3>5.5.5.&nbsp;
Server Error 5xx</h3>

<p>The 5xx status codes indicate an error in the server.
      </p>
<blockquote class="text"><dl>
<dt>500 Internal Server Error</dt>
<dd>The server could not process the request due to an internal error.
	
</dd>
<dt>501 Not Implemented</dt>
<dd>The server does not support the requested functionality.
	
</dd>
<dt>502 Bad Gateway</dt>
<dd>The server tried to forward the request, but was unsuccessful.
	This might be because the authentication failed, the remote server rejected the connection or other reasons.
	If the remote server can not be reached at all, 504 SHOULD be returned instead.
	
</dd>
<dt>503 Service Unavailable</dt>
<dd>The server can currently not process any requests but will likly be able to in the near future.
	
</dd>
<dt>504 Gateway Timeout</dt>
<dd>The server tried to forward the request but could not reach the upstream server at all.
	This can be a permanent problem and indicate that the requested object does not exist on any remote server at all.
	
</dd>
</dl></blockquote><p>
      
</p>
<a name="msg-fowarding"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5.6"></a><h3>5.6.&nbsp;
Forwarding</h3>

<p>If a request applies to a resource that is not stored by the home server of the user, the server can forward it to a server that does store it.
    In this case, the server MUST insert an additional "From" header that contains the full username of the user that sent the request.
    Similar, when a server sends a response to a forwarded request, an additional "To" header is added.
    This also applies if a notification is to be sent to a user of a different provider.
    
</p>
<a name="bindings"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6"></a><h3>6.&nbsp;
Bindings</h3>

<p>Bindings define how a FOSP message is transported via an existing protocol.
  Currently a binding for the WebSocket protocol is defined and a binding for HTTP is being worked on.
  
</p>
<a name="bindings-ws"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
WebSocket binding</h3>

<p>The WebSocket binding provides a way of sending FOSP messages of WebSocket messages.
    It was chosen because it is the only bidirectional protocol currently supported in browsers.
    The client SHOULD NOT use an unsecure WebSocket connection.
    A server SHOULD NOT accept an unsecure WebSocket connection other then for testing and debugging purposes.
    
</p>
<a name="bindings-ws-connection-initiation"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.1.1"></a><h3>6.1.1.&nbsp;
Connection Initiation</h3>

<p>To send messages to a server over WebSockets, a connection has to be established first.
      How the server address, port and URL path are determined for a given domain is discussed in&nbsp;<a class='info' href='#discovery'>Section&nbsp;9<span> (</span><span class='info'>Discovery</span><span>)</span></a>.
      In the WebSocket handshake, the Sec-WebSocket-Protocol MUST be set to "fosp".
      
</p>
<a name="bindings-ws-format"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.1.2"></a><h3>6.1.2.&nbsp;
Format</h3>

<p>The FOSP messages is formatted similar to a HTTP request/response.
      The ABNF definition reuses existing definitions from the IRI definition, in particular "iunreserved", "ihost" and "ipath-absolute".
      
</p><br /><hr class="insert" />
<a name="fosp-abnf"></a>

<p>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
<dfn>message</dfn>       = <cite class='id'>request</cite> / <cite class='id'>response</cite> / <cite class='id'>notification</cite>

<dfn>request</dfn>       = <cite class='id'>request-type</cite> <cite class='key'>SP</cite> ( <cite class='id'>resource-id</cite> / "<span class='str'>*</span>" )
                <cite class='key'>SP</cite> <cite class='id'>sequence-number</cite> <cite class='key'>CRLF</cite> <cite class='id'>headers</cite> [ <cite class='key'>CRLF</cite> <cite class='id'>body</cite> ]

<dfn>request-type</dfn>  = "<span class='str'>OPTIONS</span>" / "<span class='str'>AUTH</span>" / "<span class='str'>CREATE</span>" / "<span class='str'>GET</span>" / "<span class='str'>LIST</span>"
                / "<span class='str'>PATCH</span>" / "<span class='str'>DELETE</span>" / "<span class='str'>READ</span>" / "<span class='str'>WRITE</span>"

<dfn>response</dfn>      = <cite class='id'>response-type</cite> <cite class='key'>SP</cite> <cite class='id'>response-status</cite>
                <cite class='key'>SP</cite> <cite class='id'>sequence-number</cite> <cite class='key'>CRLF</cite> <cite class='id'>headers</cite> [ <cite class='key'>CRLF</cite> <cite class='id'>body</cite> ]

<dfn>response-type</dfn> = "<span class='str'>SUCCEDED</span>" / "<span class='str'>FAILED</span>"

<dfn>notification</dfn>  = <cite class='id'>event-type</cite> <cite class='key'>SP</cite> <cite class='id'>resource-id</cite> <cite class='key'>CRLF</cite> <cite class='id'>headers</cite> [ <cite class='key'>CRLF</cite> <cite class='id'>body</cite> ]

<dfn>event-type</dfn>    = "<span class='str'>CREATED</span>" / "<span class='str'>UPDATED</span>" / "<span class='str'>DELETED</span>"

<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>

<dfn>headers</dfn>       = <span class='rep'>*</span>( <cite class='id'>header</cite> <cite class='key'>CRLF</cite> )

<dfn>header</dfn>        = <cite class='id'>header-key</cite> "<span class='str'>:</span>" <cite class='id'>header-value</cite>

<dfn>header-key</dfn>    = <cite class='key'>ALPHA</cite> <span class='rep'>*</span>( <cite class='id'>ALPHANUM</cite> / "<span class='str'>-</span>" ) <cite class='id'>ALPHANUM</cite>

<dfn>header-value</dfn>  = <span class='rep'>1*</span><cite class='key'>VCHAR</cite>

<dfn>ALPHANUM</dfn>      = <cite class='key'>ALPHA</cite> / <cite class='key'>DIGIT</cite>

<dfn>body</dfn>          = <span class='rep'>*</span><cite class='key'>OCTET</cite>
</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>&nbsp;Figure&nbsp;4&nbsp;</b></font><br /></td></tr></table><hr class="insert" />

<p>The definitions might be relaxed in the future.
      
</p>
<a name="bindings-ws-serialization"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.1.3"></a><h3>6.1.3.&nbsp;
Serialization</h3>

<p>Messages are serialized into a blob of bytes and sent inside a single WebSocket message.
      Most of the message is text and MUST be UTF-8 encoded, only the body is either a valid JSON object, UTF-8 encoded, or raw bytes.
      The second case occurs when an attachment is up- or downloaded.
      The beginning and end, e.g. the length of a message must be determined from lenght of the WebSocket message.
      
</p>
<p>When a message contains binary data that is not UTF-8 encoded text, e.g. a WRITE request, a binary WebSocket message MUST be used.
      Otherwise, when the whole message is valid UTF-8 encoded text, a text WebSocket message CAN be used.
      
</p>
<a name="bindings-https"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
HTTPS binding</h3>

<p>The HTTPS binding is developed because it might be simpler for clients to process large up- or downloads via HTTPS.
    However, it does not support all of FOSPs functionality because notifications can not be sent over HTTPS (at least over HTTP/1.1).
    A client SHOULD NOT issue FOSP requests over plain HTTP.
    A server SHOULD NOT allow HTTP based requests other then for testing and debugging purposes.
    
</p>
<p>This binding is not finalized and SHOULD NOT be implemented except for the further development of this binding.
    
</p>
<a name="bingings-http-mapping"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
Mapping</h3>

<p>Each FOSP request is transported as an HTTP request.
      The request identifier is used as the HTTP method.
      The HTTP request-URI MUST be the absolute URI of the FOSP object.
      The HTTP headers are the FOSP headers.
      The HTTP body is the FOSP body.
      
</p>
<a name="bindings-http-session-management"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
Session management</h3>

<p>To support authenticated requests, a FOSP server that supports the HTTP binding MUST return a cookie in a success response to a AUTH request.
      With this cookie, the client MUST be able to make authenticated requests.
      
</p>
<a name="authentication-registration"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7"></a><h3>7.&nbsp;
Authentication and Registration</h3>

<p>Currently, authentication is done, using a SASL (<a class='info' href='#RFC4422'>[RFC4422]<span> (</span><span class='info'>Melnikov, A., Ed. and K. Zeilenga, Ed., &ldquo;Simple Authentication and Security Layer (SASL),&rdquo; June&nbsp;2006.</span><span>)</span></a>).
  Which mechanisms are supported can be discovered using the OPTIONS request.
  The PLAIN (<a class='info' href='#RFC4616'>[RFC4616]<span> (</span><span class='info'>Zeilenga, K., Ed., &ldquo;The PLAIN Simple Authentication and Security Layer (SASL) Mechanism,&rdquo; August&nbsp;2006.</span><span>)</span></a>) authentication mechanism SHOULD be supported by any implementation.
  
</p>
<p>As encryption of the transport protocol is mandatory in production use of FOSP, the SASL security layer is not used.
  
</p>
<a name="auth-anonymous"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
Anonymous</h3>

<p>A client may sent request without being authenticated.
    All requests are then assumed to be performed by an anonymous user.
    
</p>
<p>However, once the client started authentication, it SHOULD NOT sent any request except for those needed for the authentication.
    All requests that are sent before successfully completing the authentication MUST still be performed as anonymous user.
    
</p>
<a name="auth-sasl"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7.2"></a><h3>7.2.&nbsp;
SASL</h3>

<p>The service name specified by this protocol's profile is "fosp".
    
</p>
<p>To initiate authentication and to exchange SASL messages, the AUTH request is used.
    Depending on the mechanism, multiple requests might be needed to successfully authenticate.
    In this case the server MUST respond with a not final response code in the range of 3xx.
    The SASL messages are transported as JSON objects in the bodies of the requests and responses.
    All SASL message objects consist of an object with a "sasl" field.
    This field contains an object with the actual SASL message.
    
</p>
<p>The authentication is initiated by the client with a AUTH request.
    The SASL object in the body MUST contain a field called "mechanism" that specifies the SASL mechanism to be used.
    Furthermore, it MUST contain a field called "authorization-identity" that contains the fully qualified user name of the user that should be authenticated.
    Optionally, the object CAN contain a field called "initial-response", containing the initial response of the client, if the mechanism specifies one.
    The initial response MUST be BASE64 (<a class='info' href='#RFC4648'>[RFC4648]<span> (</span><span class='info'>Josefsson, S., &ldquo;The Base16, Base32, and Base64 Data Encodings,&rdquo; October&nbsp;2006.</span><span>)</span></a>) encoded.
    An empty initial response is indicated by an empty string, while no initial response is indicated by the absence of the "initial-response" field.
    
</p>
<p>Depending on the mechanism and the previously exchanged messages, the server can either respond with a challenge or an authentication outcome.
    If a challenge is returned by the server, it MUST be returned with a status code 310.
    The body of the response then contains a SASL object with a "challenge" field that contains the challenge in BASE64 encoding.
    If an authentication outcome is returned, it MUST be returned with a status code 200 on success or with a status code 401 on failure.
    The body of this response contains a SASL object with a "outcome" field that contains the outcome in BASE64 encoding.
    Additional data can be provided, BASE64 encoded, in the "additional-data" field.
    If there is additional data but it is empty, then the field MUST be the empty string.
    Otherwise, if there is no additional data, the field MUST NOT be present.
    
</p>
<p>If the server does return a challenge with a 310 status code, the client will sent a new AUTH request.
    The new request contains a SASL object with the "response" field, containing the SASL response, BASE64 encoded.
    
</p>
<p>Once the authentication was completed successfully, all further requests are processed in the name of the authenticated user.
    A second authentication SHOULD not be attempted on the same connection/session and a server MAY reject all further AUTH requests.
    
</p>
<a name="auth-server"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7.3"></a><h3>7.3.&nbsp;
Server to server</h3>

<p>When a server opens a connection to another server, the authentication can be done using DNS.
    The connecting server must provide a domain name it wants to be authenticated for.
    The accepting server then does the server discovery process described in&nbps;<a class='info' href='#discovery-dns'>Section&nbsp;9.1<span> (</span><span class='info'>DNS</span><span>)</span></a>&nbsp; and compares the resolved IP address to the address of the connecting server.
    If the IP addresses match, the authentication is successful.
    
</p>
<p>This section might be refined in the future and additional methods of server to server authentication might be added.
    
</p>
<a name="registrations"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7.4"></a><h3>7.4.&nbsp;
Registration</h3>

<p>The registration of a new user account is no longer part of the FOSP protocol.
    In general, out-of-band registration is preferred.
    It can either be done by the user via a web formular or the accounts can be provisioned, for example in a coporate network from a directory server.
    In the future, a possibility of creating and account via an CREATE request might be specified.
    
</p>
<a name="policies"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8"></a><h3>8.&nbsp;
Policies</h3>

<p>Besides implementing the technical specification of the protocol, the server has to enforce a set of policies.
  These policies describe how the server interprets the objects to enforc access control and send notifications for subscriptions.
  They also define constraints on certain attributes of objects and constraints on whether or not a message should be forwarded.
  
</p>
<a name="access-control"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
Access control</h3>

<p>As stated in <a class='info' href='#data-structure-fields'>Section&nbsp;3.2<span> (</span><span class='info'>Object attributes</span><span>)</span></a>, each object can save access control information.
    A valid entry in the access control list consists of the identifier of a user or a group of users and a list of rights.
    The access control list contains the field "owner" which defines the rights of the object owner.
    It also contains the field "users" that in turn contains an object.
    In this object, each key is a fully qualified user name and the value are the rights of the user.
    Furthermore, it contains a "groups" field that contains an object.
    This object contains keys which correspond to a group as described in <a class='info' href='#pol-groups'>Section&nbsp;8.2<span> (</span><span class='info'>Groups</span><span>)</span></a> and contain the rights of this group.
    At least, the access control list contains a "others" field.
    This field contains rights for all users, even anonymous users.
    
</p>
<p>Manipulation of different parts of the object can require different rights, for example, altering access control information requires the “write” right in the "acl" key.
    Because the objects are part of a tree, we can use inheritance to set access rights for a whole subtree by setting the appropriate access control information on the root of the sub-tree.
    This way the rights on an object are the sum of the rights on this object and all it’s ancestors.
    To still be able to have less rights on a child object, rights can be prefix with “not-” to explicitly remove a right, for example “not-write”.
    The server must enforce access control for an object in the following way.
    </p>
<ol class="text">
<li>Check if the right in question is set on the current object
</li>
<li>If it is set positive (e.g. not prefixed with “not-”) grant access
</li>
<li>If it is set negative (e.g. prefixed with “not-”) deny access
</li>
<li>If is is not set, go to the parent object and repeat from step 1.
</li>
<li>If the current object is already the root object, deny access
</li>
</ol><p>
    For a given user, in each step, the server has to check whether the right exists either in the corresponding "users" field, a "groups" field of a group to which the user belongs or in the "others" field of the access control list.
    Furthermore, if the user is the owner of the object which should be accessed, the "owner" field of the object and its ancestors is checked too.
    
</p>
<p>
    The following keys are supported:
    </p>
<blockquote class="text"><dl>
<dt>data</dt>
<dd>determines whether a user can read the "data", "type", "created", "updated" and "owner" fields and whether he or she can write the "data" and "type" fields.
</dd>
<dt>acl</dt>
<dd>determines whether a user can read and write the "acl" field.
</dd>
<dt>subscriptions</dt>
<dd>determines whether a user can read the subscriptions field and whether he or she can add an entry with his or her username.
</dd>
<dt>attachment</dt>
<dd>determines whether a user can read or write the attachment and the "attachment" field.
</dd>
<dt>children</dt>
<dd>determines whether a user can list, add or remove child objects.
</dd>
</dl></blockquote><p>
    
</p>
<a name="pol-groups"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
Groups</h3>

<p>To be able to set rights for a group of people, the user must first be able to define groups and store them at a well known place on the server.
    Right now, each group is only valid for the tree that it is defined in.
    
</p>
<p>The group name in the ACL MUST start with a "/".
    It denotes the path to the group object, relative to the tree of the current object.
    For example, a group could be "/config/groups/close-friends".
    The server would then retrieve the object "&lt;user@domain&gt;/config/groups/close-friends", to find out the members of the group.
    
</p>
<p>A group object is just a regular FOSP object.
    The "type" field MUST contain the string "x-group".
    The "data" field contains the group definition.
    It MUST contain a "members" field which contains an array.
    The array holds all fully qualified names of users in this group.
    
</p>
<a name="pol-subscriptions"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
Subscriptions</h3>

<p>Similar to the access control information, subscriptions can be set on objects so that a user will be notified when changes occur.
    A subscription consists of an identifier of a user, a list of events to subscribe to and a “depth”.
    The depth is used to subscribe to events from all child objects to a certain depth.
    When a change happens on an object, the server must use the following algorithm to determine which users must be notified.
    </p>
<ol class="text">
<li>Read the “subscriptions” from the current object.
      
</li>
<li>For each subscription: If the event that occurred is in the list of subscribed events and the distance of the current object to the object where the event occurred is smaller or equal to the “depth” of the subscription or the “depth” is equal to “-1”, add the user of this subscription to the list of users that should be notified.
      The distance between two objects is 0 if they are the same object, 1 if one is the parent of the other and so on.
      
</li>
<li>Go to the parent of the current object and repeat from step 1. unless the current object is the root object.
      
</li>
</ol><p>
    An important aspect to consider when sending notifications that include the new version of the object, is that every user who will be notified might be allowed to only see different parts of the object.
    Therefore, the server has to calculate the view of the object per user to prevent leaking of data a user might not be allowed to see.
    
</p>
<a name="pol-attachments"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
Attachments</h3>

<p>As explained in <a class='info' href='#data-structure-attachments'>Section&nbsp;3.4<span> (</span><span class='info'>Attachments</span><span>)</span></a>, each object can have a file as attachment.
    However, attachments will likely not be stored together with objects, but in a storage that is more suitable for files.
    Depending on how the server implements operations on attachments, it is possible that there exists an attachment for an object in the storage but the object itself is missing the “attachment” field.
    In any case the behavior of the server should be consistent.
    Hence, if there is no attachment field in the object then the attachment should be deleted and an attachment should only be readable if there is an attachment field in the object.
    
</p>
<a name="pol-auth"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
Authentication</h3>

<p>Most of the operations a user performs in FOSP probably require some access rights.
    To enforce these access rights, a user must be authenticated and therefore be able to authenticate with the server.
    As a server might forward requests on behalf of a user, the remote server must also be able to verify that the server is authorized to forward requests for the user.
    Therefore, servers must also authenticate each other.
    
</p>
<p>The authentication methods are described in <a class='info' href='#authentication-registration'>Section&nbsp;7<span> (</span><span class='info'>Authentication and Registration</span><span>)</span></a>.
    
</p>
<a name="pol-msg-forwarding"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
Message forwarding</h3>

<p>In general, a server should accept forwarded messages from another server.
    However it MUST authenticate the remote server first, before processing any other requests or sending any notifications.
    
</p>
<p>A server does not need to accept forwarded requests from other servers, if it shouldn’t be part of the federated network.
    This allows FOSP to be used in cooperate environments or other closed environments where federation with the outside world is not allowed.
    
</p>
<p>In any case, a server MUST never accept a forwarded request if the user of the request is not on the domain of the server that forwarded the request.
    For example, if server A, that is authenticated for domain “example.net”, authenticates to server B and then forwards a request of user “alice@wonderland.lit”, server B MUST close the connection.
    The user from which the request originates MUST be specified in the "From" header of the request.
    
</p>
<a name="discovery"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.9"></a><h3>9.&nbsp;
Discovery</h3>

<p>To be able to connect to a server, the client has to first determine the correct address of the server.
  The server is determined using the domain name of the user name.
  There are two different ways of determining the server address, a DNS based one and by retrieving a JSON object from a "well-known" location.
  The second approach is added as web application clients are unable to perform DNS lookups directly.
  
</p>
<a name="discovery-dns"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.9.1"></a><h3>9.1.&nbsp;
DNS</h3>

<p>The discovery via DNS uses SRV records (<a class='info' href='#RFC2052'>[RFC2052]<span> (</span><span class='info'>Gulbrandsen, A. and P. Vixie, &ldquo;A DNS RR for specifying the location of services (DNS SRV),&rdquo; October&nbsp;1996.</span><span>)</span></a>).
    Unfortunately, the current format of SRV records is limited as it only includes one transport protocol.
    DNS based discovery is therefore OPTIONAL until we are certain that the defined record format is acceptable.
    
</p>
<p>To discover a WebSocket based FOSP server for wonderland.lit, a DNS lookup for _fosp._wss._tcp.wonderland.lit with the record type SRV hast to be performed.
    Similar, to discover a HTTP based FOSP server, _fosp._https._tcp.wonderland.lit has to be resolved.
    
</p>
<a name="discovery-well-known"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.9.2"></a><h3>9.2.&nbsp;
Well known</h3>

<p>When DNS lookups are not possible, the server address can also be discovered by retrieving a JSON object.
    In accordance with <a class='info' href='#RFC5785'>[RFC5785]<span> (</span><span class='info'>Nottingham, M. and E. Hammer-Lahav, &ldquo;Defining Well-Known Uniform Resource Identifiers (URIs),&rdquo; April&nbsp;2010.</span><span>)</span></a> the object MUST be located at https://&lt;domain&gt;/.well-know/fosp.
    A client SHOULD NOT accept this file over plain HTTP.
    
</p>
<p>This response, if successful, MUST contain an JSON object and SHOULD have the "Content-Type" header set to "application/json".
    The object MUST either contain an "https-tcp" attribute with a string value of an valid HTTP URL or a "wss-tcp" attribute with a string value of a valid WebSocket URL or both.
    
</p>
<a name="rfc.references1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>10.&nbsp;References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; BCP&nbsp;14, RFC&nbsp;2119, March&nbsp;1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC5785">[RFC5785]</a></td>
<td class="author-text">Nottingham, M. and E. Hammer-Lahav, &ldquo;<a href="http://tools.ietf.org/html/rfc5785">Defining Well-Known Uniform Resource Identifiers (URIs)</a>,&rdquo; RFC&nbsp;5785, April&nbsp;2010 (<a href="http://www.rfc-editor.org/rfc/rfc5785.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC6120">[RFC6120]</a></td>
<td class="author-text">Saint-Andre, P., &ldquo;<a href="http://www.rfc-editor.org/info/rfc6120">Extensible Messaging and Presence Protocol (XMPP): Core</a>,&rdquo; RFC&nbsp;6120, DOI&nbsp;10.17487/RFC6120, March&nbsp;2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC6455">[RFC6455]</a></td>
<td class="author-text">Fette, I. and A. Melnikov, &ldquo;<a href="http://www.rfc-editor.org/info/rfc6455">The WebSocket Protocol</a>,&rdquo; RFC&nbsp;6455, DOI&nbsp;10.17487/RFC6455, December&nbsp;2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC7230">[RFC7230]</a></td>
<td class="author-text">Fielding, R., Ed. and J. Reschke, Ed., &ldquo;<a href="http://www.rfc-editor.org/info/rfc7230">Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</a>,&rdquo; RFC&nbsp;7230, DOI&nbsp;10.17487/RFC7230, June&nbsp;2014.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC7159">[RFC7159]</a></td>
<td class="author-text">Bray, T., Ed., &ldquo;<a href="http://www.rfc-editor.org/info/rfc7159">The JavaScript Object Notation (JSON) Data Interchange Format</a>,&rdquo; RFC&nbsp;7159, DOI&nbsp;10.17487/RFC7159, March&nbsp;2014.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4918">[RFC4918]</a></td>
<td class="author-text">Dusseault, L., Ed., &ldquo;<a href="http://www.rfc-editor.org/info/rfc4918">HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)</a>,&rdquo; RFC&nbsp;4918, DOI&nbsp;10.17487/RFC4918, June&nbsp;2007.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4370">[RFC4370]</a></td>
<td class="author-text">Weltman, R., &ldquo;<a href="http://www.rfc-editor.org/info/rfc4370">Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control</a>,&rdquo; RFC&nbsp;4370, DOI&nbsp;10.17487/RFC4370, February&nbsp;2006.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC5234">[RFC5234]</a></td>
<td class="author-text">Crocker, D., Ed. and P. Overell, &ldquo;<a href="http://www.rfc-editor.org/info/rfc5234">Augmented BNF for Syntax Specifications: ABNF</a>,&rdquo; STD&nbsp;68, RFC&nbsp;5234, DOI&nbsp;10.17487/RFC5234, January&nbsp;2008.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC3987">[RFC3987]</a></td>
<td class="author-text">Duerst, M. and M. Suignard, &ldquo;<a href="http://www.rfc-editor.org/info/rfc3987">Internationalized Resource Identifiers (IRIs)</a>,&rdquo; RFC&nbsp;3987, DOI&nbsp;10.17487/RFC3987, January&nbsp;2005.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC7396">[RFC7396]</a></td>
<td class="author-text">Hoffman, P. and J. Snell, &ldquo;<a href="http://www.rfc-editor.org/info/rfc7396">JSON Merge Patch</a>,&rdquo; RFC&nbsp;7396, DOI&nbsp;10.17487/RFC7396, October&nbsp;2014.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4422">[RFC4422]</a></td>
<td class="author-text">Melnikov, A., Ed. and K. Zeilenga, Ed., &ldquo;<a href="http://www.rfc-editor.org/info/rfc4422">Simple Authentication and Security Layer (SASL)</a>,&rdquo; RFC&nbsp;4422, DOI&nbsp;10.17487/RFC4422, June&nbsp;2006.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4616">[RFC4616]</a></td>
<td class="author-text">Zeilenga, K., Ed., &ldquo;<a href="http://www.rfc-editor.org/info/rfc4616">The PLAIN Simple Authentication and Security Layer (SASL) Mechanism</a>,&rdquo; RFC&nbsp;4616, DOI&nbsp;10.17487/RFC4616, August&nbsp;2006.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4648">[RFC4648]</a></td>
<td class="author-text">Josefsson, S., &ldquo;<a href="http://www.rfc-editor.org/info/rfc4648">The Base16, Base32, and Base64 Data Encodings</a>,&rdquo; RFC&nbsp;4648, DOI&nbsp;10.17487/RFC4648, October&nbsp;2006.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2052">[RFC2052]</a></td>
<td class="author-text">Gulbrandsen, A. and P. Vixie, &ldquo;<a href="http://www.rfc-editor.org/info/rfc2052">A DNS RR for specifying the location of services (DNS SRV)</a>,&rdquo; RFC&nbsp;2052, DOI&nbsp;10.17487/RFC2052, October&nbsp;1996.</td></tr>
</table>

<a name="rfc.authors"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>Author's Address</h3>
<table width="99%" border="0" cellpadding="0" cellspacing="0">
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">Felix K. Maurer</td></tr>
<tr><td class="author" align="right">Email:&nbsp;</td>
<td class="author-text"><a href="mailto:felix.maurer@student.kit.edu">felix.maurer@student.kit.edu</a></td></tr>
</table>
</body></html>