doc/implementation.rst

   1 Implementation details
   2 ======================
   3
   4 Functionality level
   5 -------------------
   6
   7 The IEEE 1003.1e draft 17 ("POSIX.1e") describes a set of 28 functions.
   8 These are grouped into three groups, based on their portability:
   9
  10 - first group, the most portable one. All systems which claim to support
  11   POSIX.1e should implement these:
  12
  13      acl_delete_def_file(3), acl_dup(3), acl_free(3), acl_from_text(3),
  14      acl_get_fd(3), acl_get_file(3), acl_init(3), acl_set_fd(3),
  15      acl_set_file(3), acl_to_text(3), acl_valid(3)
  16
  17 - second group, containing the rest of the POSIX ACL functions. Systems
  18   which claim to fully implement POSIX.1e should implement these:
  19
  20      acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3),
  21      acl_copy_entry(3), acl_copy_ext(3), acl_copy_int(3),
  22      acl_create_entry(3), acl_delete_entry(3), acl_delete_perm(3),
  23      acl_get_entry(3), acl_get_permset(3), acl_get_qualifier(3),
  24      acl_get_tag_type(3), acl_set_permset(3), acl_set_qualifier(3),
  25      acl_set_tag_type(3), acl_size(3)
  26
  27 - third group, containing extra functions implemented by each OS. These
  28   are non-portable version. Both Linux and FreeBSD implement some extra
  29   functions.
  30
  31 Thus we have the level of compliance. Depending on whether the system
  32 library support the second group, you get some extra methods for the ACL
  33 object.
  34
  35 The implementation of the second group of function can be tested by
  36 checking the module-level constant HAS_ACL_ENTRY. The extra
  37 functionality available on Linux can be tested by additional HAS_*
  38 constants.
  39
  40 Internal structure
  41 ------------------
  42
  43 The POSIX draft has the following stuff (correct me if I'm wrong):
  44
  45 - an ACL is denoted by acl_t
  46 - an ACL contains many acl_entry_t, these are the individual entries in
  47   the list; they always(!) belong to an acl_t
  48 - each entry_t has a qualifier (think uid_t or gid_t), whose type is
  49   denoted by the acl_tag_t type, and an acl_permset_t
  50 - the acl_permset_t can contain acl_perm_t value (ACL_READ, ACL_WRITE,
  51   ACL_EXECUTE, ACL_ADD, ACL_DELETE, ...)
  52 - functions to manipulate all these, and functions to manipulate files
  53
  54 Currently supported platforms
  55 -----------------------------
  56
  57 For any other platforms, volunteers are welcome.
  58
  59 Linux
  60 ~~~~~
  61
  62 It needs kernel 2.4 or higher and the libacl library installed (with
  63 development headers, if installing from rpm). This library is available
  64 on all modern distributions.
  65
  66 The level of compliance is level 2 (see IMPLEMENTATION), plus some extra
  67 functions; and as my development is done on Linux, I try to implement
  68 these extensions when it makes sense.
  69
  70
  71 FreeBSD
  72 ~~~~~~~
  73
  74 The current tested version is 7.0. FreeBSD supports all the standards
  75 functions, but 7.0-RELEASE seems to have some issues regarding the
  76 acl_valid() function when the qualifier of an ACL_USER or ACL_GROUP
  77 entry is the same as the current uid. By my interpretation, this should
  78 be a valid ACL, but FreeBSD declares the ACL invalid. As such, some
  79 unittests fail on FreeBSD.
  80
  81 Porting to other platforms
  82 --------------------------
  83
  84 First, determine if your OS supports the full 28 functions of the
  85 POSIX.1e draft (if so, define HAVE_LEVEL2) or only the first 11
  86 functions (most common case, meaning only HAVE_LEVEL1).
  87
  88 If your OS supports only LEVEL1, modify ``setup.py`` as appropriately;
  89 unfortunately, the functionality of the module is quite low.
  90
  91 If your OS supports LEVEL2, there is a function which you must define:
  92 testing if an acl_permset_t contains a given permission. For example,
  93 under Linux, the acl library defines::
  94
  95     int acl_get_perm(acl_permset_t permset_d, acl_perm_t perm);
  96
  97 under FreeBSD, the library defines ``acl_get_perm_np`` with a similar
  98 syntax. So just see how this is implemented in your platform and either
  99 define a simple macro or a full function with the syntax::
 100
 101     static int get_perm(acl_permset_t permset_d, acl_perm_t perm);
 102
 103 which must return 1 if the permset contains perm and 0 otherwise.
 104
 105
 106 .. Local Variables:
 107 .. mode: rst
 108 .. fill-column: 72
 109 .. End: