SREhttp/2 Manual || Edit USERS.CFG

### Specifying usernames/passwords, and INHOUSE addresses, in SREhttp/2

I. | Introduction
I.a | The usernames and passwords, and INHOUESE IPs file (USERS.CFG)
I.b | Examples
I.c | Client Privileges
I.d | Notes
II.a | Advanced options: Dynamic passwords
II.b | Advanced options: Custom Username procedure
III. | Outline of steps used in username lookup & privilege assignation

### I. Introduction

The SREhttp/2 `USERS.CFG` file(s) are used to register users. Each entry in a `USERS.CFG` file contains either a username, a password, and an optional list of client privileges; or a numeric IP address and an optional list of privileges.

Alternatively, you can specify your own procedure for looking up usernames and passwords.

Notes: | The USERS.CFG files (like all SREhttp/2 configuration files) are text files SREhttp/2 uses a default USERS.CFG file (typically located in the SREHTTP2\CFG directory). SREhttp/2 also uses host-specific versions of USERS.CFG (typically located in subdirectories under the SREHTTP2\CFG directory) (see HOSTDATA.HTM for more details on SREhttp/2's `host-specific parameter files`). You can use the SREhttp/2 configurator to modify parameters in any of the USERS.CFG files.

### I.a) The usernames and passwords files (USERS.CFG)

Each entry in a `USERS.CFG` file contains either a username, a password, and client privilege information; or an IP address and client privilege information. It is used when "required privileges" are required in order for a client to obtain a resource. Required privileges are specified, on a selector specific basis, in the `ATTRIBS.CFG` file(s) (see ATTRIBS.HTM for the details).

The structure of a username entry is:
`NAME PASSWORD PRIV1 PRIV2 ?PRIV_SECRET ...`
where:
`NAME` is the case insensitive username
`PASSWORD` is the password, which might be case sensitive
`PRIV1 ...` is an optional list of case-insensitive client privileges.

Or, to enter an IP address...
`INHOUSEIPS numeric_ip_address PRIV1 PRIV2 ...`
where:
`INHOUSEIPS`is the case insensitive word `INHOUSEIPS`
`numeric_ip_address` is a dotted numeric IP address (not a domain name).
`PRIV1 ...` is an optional list of case-insensitive client privileges.

`USERS.CFG`, like other SREhttp/2 CFG files, can be host-specific. As described in HOSTDATA.HTM, SREhttp/2 will use host-specific usernames first, and then (depending on whether the host is "superceding") check for "default" values.

### I.b) Examples

The following are examples of valid entries in `USERS.CFG`.

      DANIEL A11S34WZ SUPERUSER
      MIKE  IOWAMAN    CONSULTANT
      JILL  GOBOTS     INHOUSE
      JOHN  KIOWA      INHOUSE  VENUS  ?MANAGER:JUP1241
      ANONYMOUS *  PUBLIC
      INHOUSEips  201.233.61.*

In the above examples:

- `DANIEL` is given `SUPERUSER` privileges. This could be useful if `DANIEL` needs to reset the server from an out-of-town site ... but it could be dangerous (so use an obscure password)!
- `JILL` and `JOHN` are `INHOUSE` users.
- `JOHN` is given `VENUS` privileges (as well as INHOUSE privileges). He is also given a `MANAGER:JUP1241` "secret privilege" (which could be used as a second level "encrypted password" by the MANAGER addon -- see DYNPWD.TXT for details).
- `ANONYMOUS` is given `PUBLIC` privileges, and can use any password (andis valid across all hosts).
- * means anything matches, and can be used in either the password or username fields.
- All clients with an IP address that matches `201.233.61.*` are given the `INHOUSE` privilege.

### I.c) Client Privileges

Client privileges are used to control access to resources.

Basically ... | If a resource has a set of required privileges assigned to it, then a client is only allowed access to the resource if his client privileges match the required privileges.

What does it mean to match a client privilege? | Two kinds of required privileges can be specified: `ONE_OF` and `MUST_HAVE`. `ONE_OF`: the client must have at one client privilege that is also in the set of `ONE_OF` required privileges. `MUST_HAVE`: the set of client privileges must include each one of the `MUST_HAVE` required privileges.

There are several ways of granting client privileges to a client:

1. Via the SUPERUSERS SREhttp/2 parameter.
2. Using an INHOUSEIPS entry (in USERS.CFG).
3. Using a username and password entry (in USERS.CFG).

In addition to controlling access, client privileges can also be used for encryption, for higher-security access control, and by SREhttp/2 addons. For many of these additional uses, secret client privileges are users.

### I.d) Notes

- INHOUSEIPS

  InHouse IP addresses are automatically granted a set of client privileges.

  The numeric IP address of the client is compared to all of the INHOUSEIPS addresses. If it matches, then the client is automatically granted a set of client privileges.

  Syntax: | `inhouseips numeric.ip.address privs` where: `privs` (optional) : additional client privileges assigned to this client. asterisk (*) can be used as a wildcard within `numeric.ip.address`
  Notes: |

- Clients that match an `INHOUSEIPS` address are always granted the `INHOUSE` client privilege.
- Use numeric IP addresses, not domain names
- If there is no exact match, the best wildcard match is used
- You can have multiple INHOUSEIPS entries.
Example: `inhouseips 192.168.0.* INTERNAL`
`inhouseips 201.101.33.51 ADMIN10 SUBMIN2` `inhouseips 201.192.33.52`

- Case Sensitivity

  In the above examples, all passwords are in upper case.
  For basic authentication, this does not matter -- the client's authentication information is converted to upper case.
  However, for digest authentication case may matter -- SREhttp/2 checks some, but not all, case permutations of the password (entered by the user).

- Legal characters

  Usernames and passwords may contain only the following characters:
  `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_-%$#.`
  Note that exclamation (!), and question (?) are not allowed.

- Commonly Used Client Privileges

  Among other privileges, SREhttp/2 uses: `SUPERUSER, INHOUSE, VIEWMESS, CONTROL, and MESSBOX:*`

  - SUPERUSER gives unlimited access to all resources
  - INHOUSE is the privilege assigned to INHOUSEIPS addresses.
    INHOUSEIPS are set in SREHTTP2.CFG files, see SRE2003.HTM for the details.
  - CONTROL is used by a few `!special` requests
  - VIEMESS is used by the Message Box addon, and the FORUM addon
  - MESSBOX: is used by the Message Box addon

- Secret Privileges

  Privileges that start with `?` (such as `?FINANCE:x13`) are secret privileges. For example, one that specifies `x13` as a shared-secret used by the FINANCE addon.

  When SREhttp/2 sends the `client privileges` to addons (or other external procedures), it will first sort these client privileges into normal and secret privileges. These are then recombined, with the normal privileges first, then a comma, then the secret privileges.

  Example | Assuming an entry (in a USERS.CFG file) of: `USER1 PWDXX mars neptune ?pluto jupiter ?manager:charon` then the following `privileges` will be sent to addons, etc... `mars neptune jupiter , pluto manager:charon` Notes | The comma is used to seperate the normal from the secret privleges The leading `?` is removed from all secret privileges If there are no secret privileges, the comma will not be written. When SREhttp/2 compares client and required privileges, it does not differentiate between normal and secret privileges. That is, it treats them the same. Secret privileges are used by the dynamic passwords facility . Secret privileges should not be reported in a public fashion. For example, the STATUS addon (that comes with SREhttp/2) will not report secret privileges (unless explicitily directed to by a superuser).

  Examples: Secret Privileges used by SREhttp/2 |  | The following secret privileges are used by various components of SREhttp/2, or by SREhttp/2 addons. Typically, the format is `?priv_name:priv_value`, where the `priv_value` is specific to a user. `?ENCRYPT:encryption_key` Used by the Encryption utilities to store client specific encryption keys -- these are short strings the client enters in order to decrypt contents that were encrypted by SREhttp/2. `?TESTDYN:a_password`. Used by the TESTDYN.CMD addon. TESTDYN demonstrates how to use dynamic passwords to control access to specific resources. `?COMMAND:a_priv`. Used by the _COMMAND addon (that issues OS/2 commands to the server) as an extra access-control measure. `?MANAGER:a_priv`. Used by the MANAGER addon as an extra access-control measure.

- Using your own username procedure

  If you want to create a custom username/password procedure, that uses your own databases, you can specify a CUSTOM_USERNAME procedure in PRELOADS.CFG.

  ### II.a) Advanced options: Dynamic passwords

  One of the problems of BASIC AUTHENTICATION (the method supported by most http/1.0 clients) is that passwords can be easily decoded by a "man-in-the-middle". Digest authentication, supported by SREhttp/2 and http/1.1 browsers, largely solves this problem (by encoding passwords using advanced cryptographic techniques). However, until the time that everyone uses http/1.1 browsers, there is a need for some intermediate technique.

  SREhttp/2 provides such a mechanism based on the client and the SREhttp/2 server sharing an encoding mechanism. This requires complementary procedures: one that SREhttp/2 can use to decode a password, and the other for a clent to encode one (i,e.; a program she can run before filling in a password field on the browsers authenticaton screen).

  For details on this capability, see DYNPWDS.TXT.

  ### II.b) Advanced options: Custom username procedures

  Suppose you want to use a custom means of looking up usernames and verifying whether a client is to be granted access to a resource. SREhttp/2 allows you to do this via its `CUSTOM_USERNAME` procedure.

  For example, you might want to use a database manager program to check & store usename/password/privilege information (instead of SREhttp/2's `USERS.CFG`), and to determine whether access is to be granted or not (perhaps using information other then the "required privileges").

  To do this, set the CUSTOM_USERNAME parameter in `PRELOADS.CFG`.

  SREhttp/2 will pass several arguments to a CUSTOM_USERNAME procedure:
  `auth_header,client_address,servername,host_nickname,request,requires`
  where:

  - `Auth_Header`: The value of the authorization request header
  - `Client_address`: the client's numeric IP address
  - `Servername`: the servername to whom this request is directed (say, as specified in a HOST: header)
  - `Host_Nickname`: host_nickname assigned to the servername (possibly DEFAULT).
  - `Request`: the request string (i.e.'GET /foo.bar http/1.0'
  - `Requires`: the required privileges, as drawn from ATTRIBS.CFG
  The `CUSTOM_USERNAME` procedure should return the following:
  `STATUS PRIVILEGE_LIST`
  where the `privilege_list` is optional. Alternatively, the `CUSTOM_USERNAME` can send a response directly to the client (say, a speciallized authorization request).

  The status must be an `X,0,` or `1`:

  - X : Excluded -- let the regular SREhttp/2 username and client privilege lookup procedures do the job instead.
    `PRIVILEGE_LIST` should be empty (SREhttp/2 ignores it).
  - 1 : Logon successful.
    `PRIVILEGE_LIST` is optional. It can include "client privileges" that may be used by SREhttp/2 addons, EXEC procedures, etc.
  - 0 : Logon unsuccessful.
    If `PRIVILEGE_LIST` is empty, SREhttp/2 will send an authorization response.
    Otherwise, `PRIVILEGE_LIST` must contain the response code from a response sent by the `CUSTOM_USERNAME` procedure; typically, this is the value returned by `SRE_COMMAND` or `SRE_AUTH_RESPONSE.`

  #### Notes:

  - Your CUSTOM_USERNAME procedure can use any of the SRE2003 procedures. Of particular interest are:

                 SRE_EXTRACT_USERNAME
                       For extracting the username from the auth_header.
                 SRE_CHECK_USERNAME
                       For checking whether  a given password matches
                       the password used in auth_header
                 SRE_REQFIELD
                        For looking up values of other request headers,
                        such as the Cookie: request header.

  - If you want to use a custom username procedure for only a subset of supported hosts, you can use the NO_CUSTOM_USERNAME parameter in host-specific SREHTTP2.CFG files (to suppress its use for these hosts).
  - Custom username procedures do not have to pay any attention to and of the arguments. In particular, it need not attempt to match client privileges to the `Requires` list.
  - See `SREHTTP2\PROCS\CUST_USR.ERX` for a simple example of a "custom username" procedure.

  ### III) Outline of Username Lookup

  The following outline describes the steps that SREhttp/2 takes whether to grant the client access to the requested resource.

  Selector-specific attributes are looked up | The ATTRIBS.CFG file(s) are examined. In particular, selector-specific required privileges are determined. Note that if there are no selector-specific required privileges defined, then a set default required privileges may be used.
  Check for PUBLIC resources | If this selector belongs to a public realm, then access is always granted.
  Check for `SUPERUSER` clients | If the client is a SUPERUSER, access is always granted. However, depending on the value of the parameter, the client may be sent an authorization response.
  Possibly check a custom username procedure | If a custom username procedure has been defined, call it. Before calling, check if the NO_CUSTOM_USERNAME host-specific parameter or the NO_CUSTOM_USERNAME selector-specific permission has been set. The custom username procedure can Immediately grant access, and assign privileges. Deny access. The custom username procedure can send a custom authorization response, or it can let SREhttp/2 respond. If SREhttp/2 responds, it can use a standard authorization response, or a default failure file, or a selector-specific failure file Ignore. Use the standard SREhttp/2 access control mechanism, as described below.
  Check if there are no required privileges | If there are no required privileges, access is granted. However, depending on the ALWAYS_GET_PRIVS parameter, an authorization response may be sent. The following steps are checked only if there are some required privileges for this resource.
  Is this client an INHOUSEIPS | Check to see if this client is an INHOUSEIPS client. If so, extract the privileges defined in the matching INHOUSEIPS entry. These privileges are compared to the required privileges. If a match is found, the client is granted access. Otherwise, continue checking. Note that, depending on the value of ALWAYS_GET_PRIVS, an authorization response may be sent, even if an acceptable INHOUSEIPS privilege is specifed.
  Check in the USERNAME database | If an authorization request header is not available, an authorization response is sent (perhaps, as noted above, using a default or selector-specific failure file). Once available, the username and password (contained in the authorization request header) are searched for in the USERS.CFG file. If there is no match for this username, another authorzation response is sent. If there is a matching username (and password), but the defined username has not been granted a matching client privilege, then another authorization response is sent. If there is matching username, and the appropriate client privilege(s) have been specified, then access granted.

  > Reviewing: Client privileges can be defined in the SUPERUSER step, in the INHOUSEIPS step, and in the username lookup step. They can also be defined by a custom username procedure. To determine access rights, client privileges are compared to selector-specific required privileges.

  > Also note that client privileges can be used in other parts of SREhttp/2 (such as by SREhttp/2 addons).

  Updated 25 September 2002.