policies.xml

<?xml version="1.0" encoding="UTF-8"?>
<section anchor="policies" title="Policies">
  <t>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.
  </t>
  <section anchor="access-control" title="Access control">
    <t>As stated in <xref target="data-structure-fields" />, 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 <xref target="pol-groups" /> 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.
    </t>
    <t>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.
    <list style="numbers">
      <t>Check if the right in question is set on the current object</t>
      <t>If it is set positive (e.g. not prefixed with “not-”) grant access</t>
      <t>If it is set negative (e.g. prefixed with “not-”) deny access</t>
      <t>If is is not set, go to the parent object and repeat from step 1.</t>
      <t>If the current object is already the root object, deny access</t>
    </list>
    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.
    </t>
    <t>
    The following keys are supported:
    <list style="hanging">
      <t hangText="data">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.</t>
      <t hangText="acl">determines whether a user can read and write the "acl" field.</t>
      <t hangText="subscriptions">determines whether a user can read the subscriptions field and whether he or she can add an entry with his or her username.</t>
      <t hangText="attachment">determines whether a user can read or write the attachment and the "attachment" field.</t>
      <t hangText="children">determines whether a user can list, add or remove child objects.</t>
    </list>
    </t>
  </section>
  <section anchor="pol-groups" title="Groups">
    <t>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.
    </t>
    <t>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.
    </t>
    <t>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.
    </t>
  </section>
  <section anchor="pol-subscriptions" title="Subscriptions">
    <t>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.
    <list style="numbers">
      <t>Read the “subscriptions” from the current object.
      </t>
      <t>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.
      </t>
      <t>Go to the parent of the current object and repeat from step 1. unless the current object is the root object.
      </t>
    </list>
    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.
    </t>
  </section>
  <section anchor="pol-attachments" title="Attachments">
    <t>As explained in <xref target="data-structure-attachments" />, 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.
    </t>
  </section>
  <section anchor="pol-auth" title="Authentication">
    <t>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.
    </t>
    <t>The authentication methods are described in <xref target="authentication-registration" />.
    </t>
  </section>
  <section anchor="pol-msg-forwarding" title="Message forwarding">
    <t>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.
    </t>
    <t>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.
    </t>
    <t>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.
    </t>
  </section>
</section>