#include <FXACL.h>
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.
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:
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.
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.
Public Types | |
| enum | EntityType { Unknown, File, Directory, Pipe, MemMap } |
| typedef FXuint | Perms |
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) | |
| FXACL & | operator= (const FXACL &o) |
| 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 FXACLEntity & | owner () 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... | |
| typedef FXuint FX::FXACL::Perms |
Permissions as an integer.
Types of thing for which an ACL can enumerate security.
| File | This ACL describes a file (FX::FXFile). |
| Directory | This ACL describes a directory. |
| Pipe | This ACL describes a pipe (FX::QPipe). |
| MemMap | This ACL describes memory mapped data (FX::QMemMap). |
| FX::FXACL::FXACL | ( | EntityType | type = Unknown, |
|
| const FXACLEntity & | owner = FXACLEntity::currentUser() | |||
| ) |
Constructs an empty ACL of type type owned by owner.
| FX::FXACL::FXACL | ( | const FXString & | path, | |
| EntityType | type | |||
| ) |
Construct an ACL based on an item in the filing system. You should tend to use the permissions() method in the relevent classes rather than this directly (as NT and POSIX have different conventions)
| FX::FXACL::FXACL | ( | void * | h, | |
| EntityType | type | |||
| ) |
Constructs an ACL based on a NT kernel handle. Avoid using directly.
| FX::FXACL::FXACL | ( | int | fd, | |
| EntityType | type | |||
| ) |
Constructs an ACL based on a POSIX file handle. Avoid using directly.
| EntityType FX::FXACL::type | ( | ) | const |
Returns the type of thing described by this ACL.
| void FX::FXACL::setType | ( | EntityType | type | ) |
Sets the type of thing described by this ACL.
| bool FX::FXACL::hasInherited | ( | ) | const |
Returns if this ACL inherits from a parent ACL.
| void FX::FXACL::setHasInherited | ( | bool | newval | ) |
Sets if this ACL inherits from a parent ACL.
| FXuint FX::FXACL::count | ( | ) | const |
Returns the number of entities listed within this ACL.
| void FX::FXACL::insert | ( | const FXACLIterator & | it, | |
| const Entry & | entry | |||
| ) |
Inserts an entry into this ACL.
| void FX::FXACL::remove | ( | const FXACLIterator & | it | ) |
Removes an entry from this ACL.
| FXACLIterator FX::FXACL::begin | ( | ) | const |
Returns an iterator pointing to the start of the ACL.
| FXACLIterator FX::FXACL::end | ( | ) | const |
Returns an iterator pointing to the end of the ACL.
| void FX::FXACL::prepend | ( | const Entry & | entry | ) |
Prepends an entry to this ACL.
| void FX::FXACL::append | ( | const Entry & | entry | ) |
Appends an entry to this ACL.
| const FXACLEntity& FX::FXACL::owner | ( | ) | const |
Returns the entity owning the thing this ACL describes.
| void FX::FXACL::setOwner | ( | const FXACLEntity & | entity | ) |
Sets the entity owning the thing this ACL describes.
| bool FX::FXACL::check | ( | Perms | what | ) | const |
Checks the ACL if what is permitted by this process.
| void FX::FXACL::checkE | ( | Perms | what | ) | const |
Checks the ACL if what is permitted by this process, throwing a FX::FXNoPermissionException if not.
| FXString FX::FXACL::report | ( | ) | const |
Returns the ACL as a string.
| void FX::FXACL::writeTo | ( | const FXString & | path | ) | const |
Writes the ACL to the specified path in the filing system.
| void FX::FXACL::writeTo | ( | void * | h | ) | const |
Writes the ACL to the specified NT kernel handle. Avoid using directly.
| void FX::FXACL::writeTo | ( | int | fd | ) | const |
Writes the ACL to the specified POSIX file handle. Avoid using directly.
| static FXACL FX::FXACL::default_ | ( | EntityType | type, | |
| bool | readOnly, | |||
| int | flags = 0 | |||
| ) | [static] |
Returns a default ACL with the owner set to the current user and one entry specifying that only the current user has full access except for execute unless bit 2 of flags is set. For flags bit 0 specifies that the user's group has read access, bit 1 specifies write access and bit 2 has the execute bits set too
| static ACLSupport FX::FXACL::hostOSACLSupport | ( | ) | [static] |
Returns what ACL features the host OS supports.
| static void FX::FXACL::resetPath | ( | const FXString & | path, | |
| const FXACL & | dirs, | |||
| const FXACL & | files | |||
| ) | [static] |
Resets a tree on the filing system to have specific permissions, making use of inheritance when available
v1.5.6