User Access

Social OS employs a role-based security model.

Access to the API is controlled by keys consisting of a token and a
password; each being a twelve-character (or more, this is a configurable
parameter) alphanumeric string.

Each account has one or more long-term keys, plus session keys created
as required and expiring when no longer in use. Individual keys are
restricted to specific roles, providing limited access to the API – for
example, providing read-only access on the user’s messages for
integration with an external application.

There are two types of account: User and Admin. User accounts are the
normal basis for interaction with the system; messages are created by
and belong to users, as are data structures such as lists, stacks, and

Admins are not recognised as Users and cannot create messages or engage
in other interaction in their own right. The primary tasks of Admins are
creating and managing users, and monitoring and managing the flow of
data and the operation of the application.

Admins can also perform actions on behalf of Users. To prevent fraud (or
simple misattribution), all actions are logged, with Admin actions
easily distinguishable from User actions. Admins have no access to
modify these logs.

Specific to Admins are two methods available on most objects: Suspend
and Activate. The essential effect of a suspension is to remove the
object from normal activity, without actually deleting the data:

  • A suspended key cannot be used to log in.

  • A suspended user cannot log in with any key.

  • A suspended list, stack, or group can be queried directly by the
    owner, but cannot be updated, cannot be accessed by other users
    (even if set for public access), and cannot be used as an argument
    to other queries.

Passwords are stored as PBKDF2-SHA512, with a 128-bit salt. Hashing of
permanent keys uses 10,240 rounds; session keys use 1024 rounds. (Again,
these are configurable parameters.) The reasoning here is that 10,000+
rounds of SHA512 is a significant overhead on a system that may be
required to handle billions of API requests per day. Since session keys
expire quickly, the passwords need only be secure enough that it is
impractical to crack any passwords before they expire.

API Access

Core API access is provided over HTTPS , using Basic Authentication.
Access to the Message Stack (currently in development) is via SMTPS,
IMAPS, POP3S, NNTPS, the secure versions of standard mail and news
protocols, and via XMPP and AMQP, which include SSL/TLS support in the

Admin functions are accessed via a separate API, distinct from the User
API so that it can be selectively protected by firewall rules, VPN
access, or two-factor authentication, or some combination of these
methods as appropriate.

Access control is based on a combination of API endpoint and access
method, such as the URL and verb in HTTP. In the HTTP API, for example,
a user (or key) may be allowed to GET messages but not POST them.

Privacy Model

Privacy is set at the object level – a message, a user, and so on. It is
not implicitly inherited; in other words, if a user record is set to
private, that does not make the user’s messages inherently private. The
application must ensure that the private flag is set on future messages,
and update the flag on older messages if that is also desired.

Access to private data is allowed under a few simple rules:

  1. If an Admin user is requesting the data, and has explicitly bypassed
    the privacy check using he Skip-Privacy header, all data is visible.
    This is necessary for data maintenance operations, because otherwise
    (for example) developers could not create routines to back up and
    restore private data.

    Normal users, of course, have no access to this functionality. If
    the Admin user does not explicitly bypass privacy, they revert to
    normal privacy checks for the user presented in the As-User header.

  2. The currently logged-in user owns the object, or is the object
    (when retrieving the user’s own user record, a common operation).

  3. Messages may optionally contain recipient lists (to, cc, bcc). If
    the user is listed as a recipient, they automatically have access to
    the message data.

  4. Some objects have attached ACLs (Access Control Lists) – a subtype
    of the List object. If an object has a valid Read ACL and the user
    is in the list, they have access to the object data.

  5. Messages may optionally belong to a Network, another subtype of
    List. If the message belongs to the network, and the user making the
    request is a member of that network, they have access to the
    message. (This does not apply to the user data of other members of
    the network.)

Privacy is currently enforced at the output stage of the request, as
some rules are difficult to represent at the database layer. This means
that a request may retrieve private data from the database, and then
discard it later if it fails the privacy check. Work is planned in
future versions of Social OS to optimise this so that privacy checks
move, as much as possible, to the database layer.

One occasionally visible effect is in pagination: If a user requests
(say) 20 records matching a given query, and some records are private
and not accessible, fewer than 20 records will be returned.