ARPA2 Common Libraries
2.6.2
|
Services often need to make Access Control decisions on Documents and/or the Folders containing them. This is an ACL discipline to structure that.
Here are a few concepts that are useful to understand:
These are general. Document Access references documents under an Access Name following a //<volume>/<path>
grammar. The <volume>
string must not contain any /
symbols, but @
is permitted, perhaps to hint a user. This string combines with an Access Domain to uniquely specify a Document.
ARPA2 Reservoir serves as a Default Volume, denoted by an absent <volume>
string.
ARPA2 Reservoir defines a few concepts worth knowing about:
One might say that an Index defines Links, because the names contained in them resolve to a simple Path.
A canonical URI in ARPA2 Reservoir look like //<domain>/<colluuid>/
for a Collection (note that trailing slash), or //<domain>/<colluuid>/<resuuid>
for a Resource. Since the Access Domain is incorporated in a preceding phase, since users are mapped to their own <colluuid>
and since the <volume>
string is absent, the Access Names for ARPA2 Reservoir take the simplified forms /<colluuid>/
for a Collection and /<colluuid>/<resuuid>
for a Resource.
ARPA2 Reservoir defines rights per Collection, and applies this to all contained Resources, as well as to continued paths. Aliases that do not start with a /<colluuid>/
have no special rights. In terms of the logic of Access Control, this means that the RIGHTS
for the /<colluuid>/
form is looked up for a given Remote Selector, but that all other Paths into ARPA2 Reservoir resolve as KV
, so merely permitted to know about. Specifically note that the RIGHTS
of a Collection pass over to all Resource held underneath it; this is a deliberate simplification of user management; Collections represent an access profile for all the Resources contained directly underneath them. To this end, the anything after /<colluuid>/
is removed before the Access Rights lookup.
Any <volume>
name can be introduced by operators as required, and its RIGHTS
can be bestowed as desired. The form of the Access Name is //<volume>/<path>
and this combines with an Access Domain under which it is defined. The use of //
at the start sets these operator-defined Volumes apart from Access Names as used by ARPA2 Reservoir. End the <path>
with /
if and only if it is a directory; never start a <path>
with a slash however, as that is part of the prefixed //<volume>/
form.
An example of an Access Name for an internally shared NFS export for a company's products could be //products/Food/Organic/BloodOrange.md
and an example Access Name tied to a user could be //john@homedirs/Letters/Love/mary.tex
.
As far as Access Control is concerned the <user>
must be supplied in lowercase and the remainder should be mapped to lowercase inasfar as they are case-insensitive. The general idea being that the Access Name is a UTF-8 string, with its application-specific ideas of normalisation, Access Control refrains from half measures and simply does nothing along these lines.
To use these forms of Access Name, both for ARPA2 Reservoir and operator-defined Volumes, the following Access Type is used under Access Control:
This value was allocated on http://uuid.arpa2.org
for this purpose.
The customary Rules operations for key derivation are used:
rules_dbkey_domain()
to derive a Domain Key for the Access Domain and optional Database Secret;rules_dbkey_service()
to derive a Service Key from the Domain Key and the Access Type for Document Access;rules_dbkey_selector()
is normally used internally to index into the database for the Remote Identity, or an abstraction thereof, in case the database is used as ACL store.The function to call for retrieval of the Access Rights to a Document or Folder is:
The remote
represents the (remote) user intending to access the document with the given xsname
, as defined by Access Name above. We emphasise that the user is (in the most general case) remote, to avoid reducing our view to one that is strictly local. The ACL can be setup with Rules to allow only local access, but all mechanisms are general enough to allow a mixture of local and remote users, and so is the API.
When the opt_acl
is not NULL, it points to a concatenation of Rules, each of which ends in a NUL character. This is the situation where an explicit Ruleset is supplied by the application, supposedly because it is configured into the context that triggers the access request. The total length of the Ruleset, including the very last NUL character, is set in acllen
.
When opt_acl
is NULL, its acllen
is ignored and lookups are done in the database. The opt_svckey
then provides a Service Key of length svckeylen
as derived with rules_dbkey_selector()
and customarily configured in application contexts that trigger access requests. It is possible that applications are sent a hexadecimal form of the Service Key, but it should be brought back into binary form before calling this function.
When optout_actor
is not NULL, it may receive an Actor Identity if one is defined in the applicable access rule. Actor Identities are local aliases for the remote
identity, and may be used for such things as Groups, where a group member identity would be revealed and not the authenticated Remote Identity.
When this function succeeds, it returns true
; in case of operational problems it returns false
and sets errno
to a com_err code. Not finding any Rules for the input data is not an error; it will simply return V
or visitor rights, the lowest grade available. Either return value indicates that the out_rights
can be relied on; for false
it will not include the V
right that is otherwise alway included.
The following attribute is defined:
=g<scene>+<actor>@<xsdomain>
with the Access Domain is used to specify the full Actor Identity; the domain may not be available to access_document()
. This is returned in the optout_actor
field, to be used in unison with the originally supplied remote
to mark an internal or localised identity for the Remote Identity. When processing documents, it may be beneficial to use this value for activity logging, because it can protect the privacy of remote
as long as no abuse tracking is required.Rules that specify Document Access consist of rights assigned under Remote Selectors for a given Access Name. When the database is used, the Remote Selectors are part of the database indexing scheme; when explicit Rulesets are given, including in an LDAP repository that is used to fill the database from, then Remote Selectors are explicitly specified with ~selector
and applied to the following RIGHTS
specifications.
When multiple Remote Selectors match a Remote Identity, then the most concrete of these wins. When multiple RIGHTS
apply for the same concreteness level, so with the same Remote Selector, then all these are combined with bitwise or, meaning that it suffices if a flag is only specified in one of multiple locations. In any case, even when no Remote Selector matches at all, the V
right is included as a "zero" form; it merely specifies the right to visit, but not even to know about the existence of a Document or Folder, let alone read or write it.
The meaningful Access Rights are defined in <arpa2/access.h>
and include
A
for administrative access by humans,S
for automation access to make administrative changes,F
confugration access to a service,T
operation access to start or stop a service without knowing its contents,D
deletion access to resources,C
creation access to resources,X
execution access to make a resource do something, such as accepting connections,W
write access to change a resource,R
read access to retrieve or see a resource,P
prove access to check or prove properties about a resource that are not shown,K
know access to be aware of the existence of a resource,O
owner access to possess a resource without being able to work on it,V
visitor access to be kept in the blind.These rights are pretty much ordered from the highest to the lowest. It is possible to specify them individually with names like ACCESS_WRITE
or to include all lower ones with ACCESS_WRITE_DOWN
for writing, or with ACCESS_WRITE_UP
when matching. Whether this makes sense depends on the application and its desire to be broad in its usage patterns.