Client Plug-Ins¶
The CernVM-FS client’s functionality can be extended through plug-ins. CernVM-FS plug-ins are binaries (processes) that communicate with the main client process through IPC. Currently the only plug-in interface is for authorization helpers.
Authorization Helpers¶
Client authorization helpers (authz helper) can be used to grant or deny read access to a mounted repository. To do so, authorization helpers can verify the local UNIX user (uid/gid) and the process id (pid) that is issuing a file system request.
An authz helper is spawned by CernVM-FS if the root file catalog contains
membership requirement (see below). The binary to be spawned is derived from
the membership requirement but it can be overwritten with the
CVMFS_AUTHZ_HELPER
parameter. The authz helper listens for commands on
stdin
and it replies on stdout
.
Grant/deny decisions are typically cached for a while by the client. Note that replies are cached for the entire session (session id) that contains the calling process id.
Membership Requirement¶
The root file catalog of a repository determines if and which authz helper should be used by a client. The membership requirement (also called VOMS authorization) can be set, unset, and changed when creating a repository and on every publish operation. It has the form
<helper>%<membership string>
The <helper>
component helps the client find an authz helper. The client
searches for a binary ${CVMFS_AUTHZ_SEARCH_PATH}/cvmfs_helper_<helper>
. By
default, the search path is /usr/libexec/cvmfs/authz
. CernVM-FS comes with
two helpers: cvmfs_helper_allow
and cvmfs_helper_deny
. Both helpers
make static decisions and disregard the membership string. Other helpers can
use the membership string to specify user groups that are allowed to access a
repository.
Authz Helper Protocol¶
The authz helper gets spawned by the CernVM-FS client with stdin
and
stdout
connected. There is a command/reply style of messages. Messages have
a 4 byte version (=1), a 4 byte length, and then a JSON text that needs to
contain the top-level struct cvmfs_authz_v1 { ... }
. Communication starts
with a handshake where the client passes logging parameters to the authz helper.
The client then sends zero or more authorization requests, each of which is
answered by a positive or negative permit. A positive permit can include an
access token that should be used to download data. The permits are cached by the
client with a TTL that the helper can chose. On unmount, the client sends a quit
command to the helper.
When spawned, the authz helper’s environment is prepopulated with all
CVMFS_AUTHZ_...
environment variables that are in the CernVM-FS client’s
environment. Furthermore the parameter CVMFS_AUTHZ_HELPER=yes
is set.
The JSON snippet of every message contains msgid
and revision
integer
fields. The revision is currently 0 and unused. Message ids indicate certain
other fields that can or should be present. Additional JSON text is ignored.
The message id can be one of the following
Code | Meaning |
0 | Cvmfs: “Hello, helper, are you there?” (handshake) |
1 | Helper: “Yes, cvmfs, I’m here” (handshake reply) |
2 | Cvmfs: “Please verify, helper” (verification request) |
3 | Helper: “I verified, cvmfs, here’s the result” (permit) |
4 | Cvmfs: “Please shutdown, helper” (termination) |
Handshake and Termination¶
In the JSON snippet of the hand shake, the CernVM-FS client transmits the fully
qualified repository name (fqrn
string field) and the syslog facility and
syslog level the helper is supposed to use (syslog_facility
,
syslog_level
integer fields). The handshake reply as well as the
termination have no additional payload.
Verification Requests¶
A verification request contains the uid, gid, and pid of the calling process
(uid
, gid
, pid
integer fields). It furthermore contains the
Base64 encoded membership string from the membership requirement
(membership
string field).
The permit has to contain a status indicating success or failure (status
integer field) and a time to live for this reply in seconds (ttl
integer
field). The status can be one of the following
Code | Meaning |
0 | Success (allow access) |
1 | Authentication token of the user not found (deny access) |
2 | Invalid authentication token (deny access) |
3 | User is not member of the required groups (deny access) |
On success, the permit can optionally conatain a Base64 encoded version of an
X.509 proxy certificate (x509_proxy
string field). This certificate is used
by the CernVM-FS client when downloading nested catalogs files as client-side
HTTPS authentication certificate.