Intranet/Hosting Toolkit | [table of contents]

`v1.11 November 30th 2001` | CFX_Permissions OPEN-SOURCE NT DLL for Cold Fusion 4.0.1 and up Lewis A. Sellers http://www.intrafoundation.com/ihtk.html ihtk@intrafoundation.com

FOREWORD This is an Allaire Cold Fusion Extension Tag (CFX). It is for use with Allaire Cold Fusion Servers 4.0.1 (and up) running on Microsoft NT. It was written by Lewis A. Sellers of Intrafoundation Software. CFX_Permissions allows you to manage shares, mapped network drives and NTFS file permissions (ACLs). This functionality, in combination with CFX_UserManager, allows you to create folders on shared or local drives they will allow or deny access depending on NT Users and group memberships. Please read the version history for current tag status before emailing questions. | C O N T E N T S `Foreword` General Permissions `Version History`

`top`

## G E N E R A L

### ABOUT

#### <CFX_Permissions ACTION="ABOUT">

The tag itself returns a couple variables back no matter what you do (PermissionsDescription, PermissionsVersion and PermissionsError). These are always available unless there is a catastrophic failure of the tag.

Additionally you can use the ABOUT function to return more detailed information on the tag. The fields returned are mostly only of interest for curiosity or in debugging a situation.

Note below that though the tag returns it's SerialNumber, it's not used currently, and hasn't been for a very long time, but probably will be again soon.

For the curious, it also proves the total number of lines of c/c++ that the current build was using. This includes the scant comments in the source code. For instance, this build of the tag has 2180 lines of code.

Description
  The general product description.
Version
  The version number of the software, ie 2.0.
Quality

  The quality field will be one of the following four: "Alpha", "Beta", "Gamma" or "Omega". Quality relates the quality control status of the version of the tag you're currently using.

  Alpha code is highly unstable and shouldn't be trusted for anything. Do not use on production machines.

  Beta code is close to being finish and it is in a debugging phase. Do not use on production machines.

  Gamma code is for use on production machines. As far as the beta testers have determined it works as it should.

  When a product goes Omega that generally means it is long used Gamma code that is now no longer being maintained.

SubVersion
  The subversion number of the software, ie 4 for "2.0beta4".
SerialNumber
  Currently unused.
Lines
  The total lines of c/c++ code in the software.
BuildDate
  The ODBC DATETIME when the tag was last compiled (built).
Evaluation
  Boolean field (0 or 1). 1 indicates the version of the tag you're using is a time-limited evaluation version. 0 is full commercial.
ExpirationDate
  The ODBC DATETIME date when the tag will stop working.

`top`

## P E R M I S S I O N S

Windows NT and Windows 2000 have a file system available called NTFS (NT File System). Unlike the FAT file systems of DOS, Windows 95 and Windows 98 it has a file security system integrated into it. The security system is based on NT user and group names and various permission types you wish to assign them for a file or folder.

The true inner workings of the NTFS ACL are rather bizzare, but for your purposes this has all been distilled and isolated into three (3) access types (ALLOW, DENY and REVOKE) and eight (8) permissions (RWXDPOCF).

### Users and Groups

When working with permissions you will name the user or group you are giving access to or denying from a file or folder. When created all files and folders have a few users or groups added to them by default, such as SYSTEM and Everyone. This is normal.

As a general rule you shouldn't delete or modify any of these unless you know what you're doing.

NOTE: Everyone is a special account name which simply signifies the permissions you grant to everyone else who you've not specifically named.

### Access Types

There are only three basic access types involved with file security: ALLOW, DENY or REVOKE. If you add an ALLOW access type to a file for a user you grant them certain permissions (see below) such as being able to read the file or list the contents of a directory.

When you add a DENY to a file for a user, say "mrsmith", then you deny specific permissions to this file to the account "mrsmith".

REVOKE simply deletes all ALLOW or DENY access types on the specified file for the user named. That is, it removes all reference to the user from the file, good or bad.

### Permissions

Permissions. In reality NT has a complicated tangle of permission masks and ACE structures, but we're not going to get into that. For our purposes there are only eight (8) permission types: RWXDPOCF. What they do varies slightly depending on whether we're talking about a file or a folder, but they are, more fully:

R "Read"
  For files:

  Allows viewing the file's data

  For directories:

  Allows viewing the names of files and subdirectories

W "Write"
  For files:

  Allows changing the file's data

  For directories:

  Allows adding files or subdirectories

X "eXecute"
  For files:

  Allows running the file if it is a program

  For directories:

  Allows changing to subdirectories in the directory

D "Delete"
  For files:

  Allows deleting the file

  For directories:

  Allows deleting the directory

P "change Permissions"
  For files:

  Allows changing the file's permissions

  For directories:

  Allows changing the directory's permissions

O "take Ownership"
  For files:

  Allows taking ownership of the file

  For directories:

  Allows taking ownership of the directory

C "Change"
  Change (RWXD)
F "Full"
  Full control (ie, RWXDPO)
r "Generic Read"
  Generic read. For Windows 2000.
w "Generic Write"
  Generic write. For Windows 2000.
x "Generic eXecute"
  Generic Execute. For Windows 2000.
a "Generic All"
  Generic All. For Windows 2000.

Under Windows NT folders, btw, are treated as any other file in many respects even though their permissions, as related above, have slightly different effects. The major difference with a folder you can specify the permissions that files created in that folder will inherit.

To add inherited permissions to a folder, simply use lowercased permission letters. That is: "rwxdpocf" instead of "RWXDPOCF". Note that inherited permissions are kept seperate from normal permissions. THIS is why when you do the PERMISSIONS function on a folder you will see double and triple entries for users. Some rows are for normal permissions. Others are for the inherited ones.

Permissions, btw, are valid only on NTFS file systems, which are an option under Windows NT and Windows 2000 only. You can not use any of this functionality on simple consumer-grade operating systems such as Windows 98.

### SID and the AccessMask

Some of these functions may return the fields SID and AccessMask. You can safely just ignore these fields if you wish, but, for those of you who hardcore into managing your file permissions they can be very useful for working through the occasional difficult permissions problem that may come up. A SID, if you wish to know, is a Security Identifier. It's how windows actually uniquely identifies a user, etc across multiple domains. The AccessMask is the binary representation of the permissions codes (in this case, in hexidecimal).

As I said, you can completely ignore these fields. But if you need them they're there.

### PERMISSIONS

#### <CFX_Permissions ACTION="PERMISSIONS">

FIELDS
Type | string
AccountType | string
Domain | string
User | string
IsInherited | string
Permissions | string
SID | SID string
AccessMask | hexadecimal

OPTIONAL
Query | string

REQUIRED
Action | PERMISSIONS
Domain | string
File or Folder | string

Lists permissions relating to a specific folder. Permissions (or ACL, ie Access Control Lists) is a somewhat complex thing under NT. In general however the purpose of permissions is to specific the name of a user or a group and what can of access they are to have to this folder.

Type
  Allow, Deny
AccountType
  "User" "Group" "Domain" "Alias" "Well Known Group" "Deleted Account" "Invalid" "Unknown"
IsInherited
  This field is a simple way to determine if the row refers to (inherited) directory-related permissions or not.

Is is possible for a file to have permissions set for a user that no longer exists. In this case both User and domain will be blank.x

Example: `<CFX_Permissions ACTION="PERMISSIONS" FOLDER="w:\user\lsellers" QUERY="lsellers">`

### SEARCH

#### <CFX_Permissions ACTION="Search">

FIELDS
Type | string
AccountType | string
Domain | string
User | string
IsInherited | string
Permissions | string
SID | SID string
AccessMask | hexadecimal

OPTIONAL
Query | string

REQUIRED
Action | SEARCH
Domain | string
File or Folder | string

Similiar to PERMISSIONS, this allows to to specify the User and TYPE you are specifically looking for. It returns only records matching these.

TYPE can be of the strings: "Allow", "Deny" or "Any".

Example: `<CFX_Permissions ACTION="Search" FOLDER="w:\user\mrsmith\" User="mrsmith" TYPE="DENY">`

### ALLOW

#### <CFX_Permissions ACTION="Allow">

REQUIRED
Action | ALLOW
File or Folder | string
User or Group | string
Permission | string

Grants access permissions to a specific user or group.

Examples: `<CFX_Permissions ACTION="Allow" FOLDER="w:\user\mrsmith" User="mrsmith" PERMISSION="RWXD">`
`<CFX_Permissions ACTION="Allow" FOLDER="w:\user\mrsmith" User="mrsmith" PERMISSION="RWXD" INHERIT="YES">`
`<CFX_Permissions ACTION="Allow" FOLDER="w:\user\mrsmith\papers\" GROUP="techgroup" PERMISSION="RX">`
`<CFX_Permissions ACTION="Allow" FILE="w:\user\mrsmith.finger.txt\" User="mrsmith" PERMISSION="RW">`

### DENY

#### <CFX_Permissions ACTION="Deny">

REQUIRED
Action | DENY
File or Folder | string
User or Group | string
Permission | string

Denies access to the folder for a specific user or group.

Example: `<CFX_Permissions ACTION="Deny" FOLDER="w:\user\mrsmith\papers\" User="bob" PERMISSION="RX">`

### REVOKE

#### <CFX_Permissions ACTION="Revoke">

REQUIRED
Action | REVOKE
File or Folder | string
User or Group | string
Permission | string

Removes access or denial of access to the folder for a specific user or group.

Example: `<CFX_Permissions ACTION="Revoke" FOLDER="w:\user\mrsmith\" User="exemployee">`

### CACLS

#### <CFX_Permissions ACTION="CACLS">

FIELDS
Type | string
Domain | string
Owner | string
StandardRights | string
AccessRights | string
SpecificRights | string
ControlFlags | string
AccountType | string
CACLS | string

OPTIONAL
Query | string

REQUIRED
Action | CACLS
File or Folder | string
User or Group | string

This function has little practical use except perhaps for debugging your ACL settings. It is similiar to PERMISSIONS but, unlike the predigested data that function returns, this gives you the rather raw low-level data. Most of it will probably be a complete mystery to you, but if you want to know what the permissions data REALLY looks like -- this is it.

The CACLS field, btw, synthesises all this raw data into a "CACLS" compatible text string (or tries -- it should be close). If you've been using the CACLS command line tool before hand, then this should make you feel right at home.

Example: `<CFX_Permissions ACTION="CACLS" FOLDER="w:\user\mrsmith" QUERY="s">`

`top`

## VERSION HISTORY

- 1.10 January 3rd 2001.

  Added IHTKPASSWORD. Upgraded reporting code.

- 1.9 October 27th 2000.

- "Invalid tpye" was changed to "Invalid"
- "Unknown type" was changed to "Unknown"
- Cleaned up tests. Added shares tests.
- Added ability to set AccessMask in raw hexidecimal.
- 1.8 October 3rd 2000.

  A few final issues regarding W2K were addressed. Added some W2K fine-grain control while I was at it (the bulk of the CFX_Permissions code really hadn't been changed since the NT4 Era).

- 1.7 September 19th 2000.

  Upgraded error reporting code to v1.2.

- 1.6 August 31st 2000.

  NEW TAG: As mentioned for a while now CFX_NFS was finally torn into two new tags: CFX_Permissions and CFX_Shares. CFX_NFS is now "untouchable" and no further modifications or corrections to it's code base will be made. If you're still using NT 3.51 or NT4 then the CFX_NFS functions may work better for you. CFX_Permissions and CFX_Shares are meant to primarly work on NT5 (W2K) but effort will be made to make them backward compatible with legacy NT versions where possible.

  Although most of the code for CFX_Permissions is the same as was in CFX_NFS, made a few changes to field names compared to the deprecated CFX_NFS. Also...

  - Fixed CACLS bug that could crash the tag.
  - Cleaned up docs
  - Added more W2K support
- 1.5 August 9th 2000.

  - Fixed LocalDrives loss of precision for Tom. It wasn't accurately displaying partitions greater than 4gb (32-bits) when returning the field. Made the output 64-bits, ie, good for up to 1.84467441e19 bytes.
  - Added FreetoUser field for LocalDrives.
  - Fixed CACLS bug that occurs with unknown accounts types.
- 1.4 August 5th 2000.

  To be honest I don't remember what changes I made for 1.4 it's been so long. It was something minor but I didn't make any notes of it at the time. I believe it was an amplification of something said in the tests to avoid confusion.

- 1.3 July 3,4 2000.

  Completely rewrote all the function code except that relating to permissions. This way should be much better for large networks. Should have done it this way to begin with... but I didn't know then the MS internals that I know now.

  Still having some difficulties with mapped network drives. There are currently some scope issues with NETWORKDRIVES and MAPNETWORKDRIVE that are being investigated. All other functions are, as far as is know, functioning correctly. Hope to have this resolved by the next release.

  Added a few new functions, and since it's the holidays (vespucia's independance day) and no one's had a chance to really make production use of the v2 code yet, I changed some of the function fields. :) Head's up.

  (I hate legacy code getting in the way of improvements or having the code become overly complex and more apt to unforseen failure. Moreso since this software is running on a couple different US Mil & Space Support sites. Don't want anything blowing up that's not supposed too.)

  - Added DOMAINS
  - Added NETWORKPRINTERS
  - Changed SERVERS (faster, completely different than CFX_UserManager's SERVERS function)
  - Added NETWORKNEIGHBORHOOD
- 1.2 June 30 2000

  Oops. Forgot to clean up the Permissions documentation and a few of the network drive functions. Sorry about that. Was in such a rush to get the thing out before the holiday weekend it slipped my mind. Should be fixed now.

  I'll up the ums2.1 with Permissions1.2 in a few days.

- 1.1 June 28 2000.

  Some issues with deleted user accounts were addressed and the documentation cleaned up.

  Sorry about the photos. When I have time I'll scan in more artist imagery.

- 1.0 June 18, 25 2000.

  All of the functionality of this tag comes from the 2.0betas of CFX_UserManager. It seemed logical to strip out all the newly written file-centric code and place it all in it's own tag. Anyone who has used the 2.0betas 1 through 5 will be immediately familiar with most of the functionality of the new tag. Some of the names and parameters have changed, but the essense is the same.

`top`
`f i n i`
`-{ts '2001-12-03 03:35:33'} /ihtkdocs/Permissions/index.cfm-`