FX::FXACL Class Reference
[Writing secure code]

#include <FXACL.h>

List of all members.


Detailed Description

Provides a portable Access Control List.

Microsoft Windows NT provides an excellent security system based upon Access Control Lists as indeed does SE-Linux, the C3 secure form of Linux. While ACL based security is not inherently secure (ie; mathematically proveable as secure) it's still not bad at all. This class permits portable control of system ACL's and on systems without them (POSIX), it provides a reasonable emulation.

Unfortunately, Win32 code rarely bothers with NT security and so if you do try to use it extensively, quite a lot of other code just falls over. This is almost certainly resulting from the amazingly obtuse, overly low-level Win32 security API which because it's so hard to understand really is badly designed. There should at least have been an extra higher-level API for it but I guess security isn't so important at Microsoft :(

The major difficulty limiting the usefulness of this class is that underlying most ACL based systems is a very long integer which uniquely identifies an entity (FX::FXACLEntity). The big problem is manipulating portably this long integer - what FXACLEntity provides is about as much as is common across all platforms.

Where possible, for construction and writing use the methods in all FX::QIODevice derived classes - these are called permissions() and setPermissions(). Usually a static method is provided as well to aid accessing entities not belonging to the local process.

Note that denies are processed before grants, though in the order of the entries within the ACL.

Usage:

For POSIX systems, they provide a minimal user, group & public (other) read, write & execute bits per thing plus the concept of an owner. This is represented by FXACL as those three things in that particular order using the special entities FX::FXACLEntity::owner() and FX::FXACLEntity::everything() if they have something enabled - there are never any deny entries. FXACL will complain if you try setting permissions on anything other than the ACL's owner or group. You can set permissions for public (FX::FXACLEntity::everything()) on all systems.

The POSIX permissions map onto FX::FXACL::Permissions as follows for directories:

The POSIX permissions map onto FX::FXACL::Permissions as follows for files: takeownership is always set on POSIX systems if the user is root. If not, it's always unset.

On NT, the situation is quite a lot more complex. Different entities have different mapping of permission bits - for files, the permissions just happen to map nicely onto NT ones except that readattr and writeattr also specify NT extended attributes as well as normal ones. I think the nice mapping happened because I thought of every possible operation you'd like to prevent and obviously so did the designers of NT (ie; Dave Cutler). One caveat on NT is that file and directory permissions share the same space, so if list is true then you get read file access. There is a slight difference though as read-via-list does not apply SYNCHRONIZE permission which will cause a problem if you ever try to wait on a file handle. Best use file permissions for files and directory permissions for directories.

For pipes, read and write do the obvious. append or createdirs permit another instance to be created. execute applies the SYNCHRONIZE permission so it's possible to create a synchronise-only named pipe (useful).

For memory mapped sections, read and write are again obvious. append permits extending of the mapped section. deletefile enables deletion of the mapped area. copyonwrite is specially for mapped sections and enables copy-on-write access.

For all entities on NT, readattrs, writeattrs, readperms, writeperms and takeownership are available.

When specifying permission bits, you can either use the setX() methods in the FX::FXACL::Permissions structure (these can be chained together) or the more C-style macros prefixed with FXACL_ - which you choose depends on the moment. In particular you may find the FXACL_GENREAD, FXACL_GENWRITE and FXACL_GENEXECUTE macros of interest.

On NT particularly, watch out for forgetting to set the execute (traverse) permission for directories - NT ignores this permission when the process' owner is the same as the directory's but doesn't if they're different.

On NT, the system does not permit you to set ownership of something to other than the current user. You can work around this by authenticating the desired owner entity using FXACLEntity::isLoginPassword() first and then setting it as owner of the ACL before applying.

Writing portable code:

If you're writing FXACL using code which must run on POSIX and NT, firstly consider using hostOSACLSupport() to use better facilities when available. Future versions of TnFOX will almost certainly support POSIX capabilities or other enhanced security facilities and your code can become magically enabled via a simple recompile with a newer version.

Past that, as NT was originally written to be POSIX compliant, through only using FXACLEntity::owner() and FXACLEntity::everything() in entries and only using FX::FXACL::Permissions::setGenRead(), FX::FXACL::Permissions::setGenWrite() and FX::FXACL::Permissions::setGenExecute() member functions (or their equivalent macros) you can have one code which works with identical semantics everywhere. Note however that NT is not POSIX Unix and you can introduce subtle security holes if you're not careful - for example, the inheritability of ACL's in NT can cause any permissions you set to be totally ignored.

Note that on Apple MacOS X, setting permissions on Shared Memory Objects is not possible. The call is a no-op on this system.

Definition at line 238 of file FXACL.h.

Public Types

typedef FXuint Perms
 Unknown
 File
 Directory
 Pipe
 MemMap
enum  EntityType {
  Unknown, File, Directory, Pipe,
  MemMap
}

Public Member Functions

 FXACL (EntityType type=Unknown, const FXACLEntity &owner=FXACLEntity::currentUser())
 FXACL (const FXString &path, EntityType type)
 FXACL (void *h, EntityType type)
 FXACL (int fd, EntityType type)
 FXACL (const FXACL &o)
FXACLoperator= (const FXACL &o)
 ~FXACL ()
bool operator== (const FXACL &o) const
bool operator!= (const FXACL &o) const
EntityType type () const
void setType (EntityType type)
bool hasInherited () const
void setHasInherited (bool newval)
FXuint count () const
void insert (const FXACLIterator &it, const Entry &entry)
void remove (const FXACLIterator &it)
FXACLIterator begin () const
FXACLIterator end () const
void prepend (const Entry &entry)
void append (const Entry &entry)
const FXACLEntityowner () const
void setOwner (const FXACLEntity &entity)
bool check (Perms what) const
void checkE (Perms what) const
FXString report () const
FXString asString () const
void writeTo (const FXString &path) const
void writeTo (void *h) const
void writeTo (int fd) const
FXDLLLOCAL void * int_toWin32SecurityDescriptor () const

Static Public Member Functions

static FXACL default_ (EntityType type, bool readOnly, int flags=0)
static ACLSupport hostOSACLSupport ()
static void resetPath (const FXString &path, const FXACL &dirs, const FXACL &files)

Friends

class FXACLIterator

Classes

struct  ACLSupport
 Denotes how much security support the host OS provides. More...
struct  Entry
 An entry within the ACL. More...
struct  Permissions
 Contains the permissions of an entity. More...


The documentation for this class was generated from the following file:
(C) 2002-2009 Niall Douglas. Some parts (C) to assorted authors.
Generated on Fri Nov 20 18:32:37 2009 for TnFOX by doxygen v1.4.7