                    Security/2 (c) 2002-2005 by nickk
                    _________________________________

CONTENTS
________

 1. Introduction
 2. Security/2 content
 3. Security/2 concepts
 4. Installation
 5. SSES.SYS usage
 6. USER.EXE usage
 7. ACLS.EXE usage
 8. SU.EXE usage
 9. WHOAMI.EXE usage
10. SHVIO.EXE and SHPM.EXE usage
11. SHPM2.EXE usage
12. LOGOFF.EXE usage
13. KILL.EXE usage
14. PASSWD.DLL usage
15. User and ACL's managing API
16. USERCTL.DLL API
17. Bugs And Limitations
18. LICENSE
19. Supporting the project
20. Author and credits

1. Introduction
_______________

 Security/2 is a multi-user system for OS/2. It provides controlled access to
 files, drives, drivers and other OS/2 stuff, based on access control list
 for each user.
 Security/2 has modular structure and can be easily (i hope ;)) extended and
 provides a API for developers to enable their applications be multi-user.

2. Security/2 content
_____________________

 sses.sys     - Core driver of Security/2. It controls the access to files, 
                processes, etc.

 sesmgr.dll   - replacement for OS/2 standard sesmgr.dll to control the
                starting of independent session with DosStartSession.

 ssesctl.exe  - sses.sys controller, it provides sses.sys with user information
                and access control lists (ACL).

 passwd.dll   - user and its ACL's managing module. It is called by ssesctl.exe
                to manage, authenticate and authorize users. Passwd.dll keeps
                userbase in unix-like 'passwd' file and user ACL's in plain text
                'acls' file. It can be replaced if you want to keep user and
                ACL's bases in different formats and places.

 userctl.dll  - user-end interface to sses.sys. It is called by users manage
                user and ACL's base, registering a new user, etc.

 user.exe     - simple text-mode user managing utility. It uses userctl.dll and
                can be easily replaced if you want some more comfortable gui
                tool.

 acls.exe     - simple text-mode ACL's managing utility. It uses userctl.dll and
                can be easily replaced if you want some more comfortable gui
                tool.

 su.exe       - analog to unix 'su' command. It runs a specified command or
                user shell under another user. Uses userctl.dll

 whoami.exe   - analog to unix 'who am i'. It returns the name of the user who
                called it. Uses userctl.dll

 shpm.exe     - simple PM local logon without logoff possibility. Uses userctl.dll

 shpm2.exe    - Multiple PM local logon. Uses userctl.dll

 shvio.exe    - simple VIO local logon. Uses userctl.dll

 logoff.exe   - Local logoff utility. Uses userctl.dll

 wkill.dll    - the kill process plugin to WatchCat. Uses userctl.dll. See 
                WatchCat documentation for usage information.

3. Security/2 concepts
______________________

 The Security/2 controls a number of OS/2 API functions such as DosOpen,
 DosKillProcess, etc. When such functions are being executed, sses.sys checks
 if the calling user has authority to execute this function on called resource
 by his access control lists.

 Each element of this lists has a mask of resource and the number of rights on
 it. The rights can be READ, WRITE, CREATE, DELETE, EXECUTION, START SESSION.
 The masks are ordinal file masks like 'c:\os2\*'.
 The possible wildcards are '*', '?', [...], [^...] which means any number of
 symbols, any symbol, any symbol from the list, any symbol not included in the
 list. The masks are case insensitive.

 There are a special masks - <user> which means the rights for managing users,
 <acl> which means the rights for managing ACL's and <dll> withe the only 
 apliable right 'x' which means that all dll allowed to read, allowed to be
 executed (loaded) . The EXECUTION right in <user> mask means the right for 
 registering a new user (i.e. su).

 The access control lists are scanned from beginning to end until the given
 object name matches mask from element of list.

 There is no mask/right for killing processes. Each user can kill only his
 processes, root user can kill any process.

 When system starts only root user is registered and has rights for everything.


4. Installation
_______________

 To install Security/2 run install.exe from the Security/2 distributive package.
 The GUI installation interface will guide you throw the installation procedure.
 After installation reboot your computer.

 For unattanded installation use the following switches of install.exe:

 -d <dir>    - directory to install Security/2 to. Default is X:\Security,
               where X - your boot drive.
 -i          - unattanded installation. Do not display GUI installation dialog.
               With -i switch Security/2 instalation will not require PM to be
               existed in the system.
 -r          - replace existing configuration. This will reset previously 
               installed configuration files - \Security\etc\passwd 
               and \Security\etc\acls
 -n          - do not change system CONFIG.SYS file. The \Security\etc\config.sys 
               will be created containing Security/2 dependent lines. You can 
               switch to this config.sys later manually. If -n switch is not
               chosen the \Security\etc\config.sys will contain backup copy of
               the system config.sys after installation.
 -l <logon>  - install logon shell. Possible values : none (default), shpm2, 
               shpm, shvio.
 -s <switch> - sses.sys switch to add (if <switch> starts from +) or remove
               (if <switch> starts from -). Possible switched: logging (adds 
               /logbuf:65535 /logresult:deny switches to sses.sys, --logsuck to
               ssesctl, off by default), no16bitcontrol (adds /no16bitcontrol to
               sses.sys, off be default), suanyuser (adds /suanyuser to sses.sys,
               on by default), alloweffective (adds /alloweffective to sses.sys,
               on by default). To specify several sses.sys switches use several 
               -s switches. I.e. to switch on logging and switch off /suanuser
               use : -s +logging -s -suanuser.

 The Security/2 package include wkill.dll - a kill process plugin for
 WatchCat utility. After installation it will be placed to \Security\dll 
 directory. To use this plugin with Watchcat, copy wkill.dll WatchCat 
 installation directory. Refer WatchCat documentation for further information.

 The installation procedure creates two default users in your system - 
 'root' with password 'root' who have access to everything and 'test'
 with password 'test' who has access to everything except your config.sys file.

 If you've chosen installation of any of three local logon facilities, use any
 of these users to logon after rebooting the system.

5. SSES.SYS usage
_________________

 basedev=sses.sys [<options>]

 Options:

 /restrictroot        - allow loading acls for root user for restricting root
                        user rights. Def is do not allow.
 /suanyuser           - allow root user to register another users without specifying
                        the password. Use this option with care when local
                        logon shell is used.
 /somcompat           - handle a special case when PMSHELL.EXE runs SOMDD.EXE.
                        Use this option i.e. when you experience troubles running
                        Lotus SmartSuite. It is strongly recommended to use this
                        option along with PM multi local logon.
 /ctlthreads:<number> - the number of ssesctl threads. Def is 2. Max is 256.
 /maxusers:<number>   - the maximum number of concurrently working users.
                        Def is 75, max is 601
 /maxpids:<number>    - the maximum number of concurrently running pids for
                        each user. Can be reduced (not increased) in user
                        creation. Def is 65535, max is 65535
 /maxaclsecs:<number> - the maximum number of cuncurrently active ACL's section.
			Def is 512, max is 4096.
 /maxacls:<number>    - the maximum number ACL's for each section. Def is 1159,
                        max is 39568.
 /aclstrategy:<strat> - the strategy to check user permissions. Valid strategies:
                        'firstmatch' - applying the rights of the first acl with
                        matching mask.
                        'actionmatch' - scanning the acls list until the acl with
                        with matched both mask and action right or acl with
                        matched mask and 'deny' right. 
                        Def is firstmatch.
 /sesmgr:<path>       - the path to your session manager (protshell). Def
                        is '*PMSHELL.EXE'.
 /logbuf:<number>     - the size of logger buffer in bytes. The size of
                        0 bytes means that logging is switched off. To get
                        log just 'type SSESDD$'. Def is 0, max is 1048576
 /logaction:<number>  - the set af actions to log. The number is the desired 
                        superposition of ACT_* constants given in usertype.h
 /logresult:<type>    - the type of action checking results to log. Valid types
                        are : 'deny' - log denied actions only, 'allow' - log
                        allowed actions only, 'all' - log all actions.
 /no16bitcontrol      - do not use 16 bit hooks. This will switch off priority
                        control, but can solve traps on some WARP3/WARP4 systems.
                        If you experience a trap during system boot after 
                        installing Security/2, first try to add this key to sses.sys.
 /noflagprocesscheck  - disable of DosFlagProcess controlling
 /alloweffective      - allow register so-called "effective" user from root
                        process. First process registered under "effective" user
                        can be reverted back to root privilege with 
                        DosUserUnsetEffectiveUser() Security/2 API function.
 /q                   - be quiet.

 When loging is enabled in sses.sys (with /logbuf, etc keys), root user can read
 from \DEV\SSESDD$ log messages with DosRead function. The ssesctl.exe does it
 when --logsuck key specified (see next section). The format of log messages is:

user(pid): action: object: result

 where user   - username
       pid    - pid of caller process
       action - requested action (r - read, w - write, x - execute, c - create, 
                 d - delete, k - kill, s - start session)
       object - name of object to apply action to, can be name of file, driver
                 or one of special objects (<user> - userbase, <dll> - any dll,
                 <acl> - aclbase, <timecrit> - timecritical priority setting, 
                 createvdm - create VDM, setdatetime - date/time setting)
                 or process pid in case of kill action.
       result - result of checking the permissions, can be : A - allow, D - deny

6. SSESCTL.EXE usage
____________________

 ssesctl.exe [options]

 Options:

 --threads  <num>     - the number of ctl threads (def: 2)
 --userbase <dllname> - the name of user and ACL base managing dll (def: PASSWD)
 --source   <path>    - the path to userbase source (file). This will be passed
                        to user and ACL base managing dll (def: none)
 --loadroot           - load root acls on start (def: do not load)
 --logfile  <path>    - the path to logfile (def: none - logging to console)
 --logsuck  [<num>]   - enable logging the SSES.SYS. num - log polling interval
                        in seconds (def: 10)
 -q                   - be quiet on console
 -v         <num>     - verbosity level (0 - 10) (def: 0)


6. USER.EXE usage
_________________

 user <command> [<options>] [<user1> [<user2>] ... ]

 Commands:

 -a, --add         - Add user
 -c, --change      - Change user
 -u, --update      - Update given user by the info from database
 -l, --list        - Display database entries for specified users.
                     If no users specified, all users will be listed.
 -r, --remove      - Remove user
 -t, --test        - Test password for given user
 -h, --help        - Display usage information
 -v, --version     - Display program version

 Options:
 -q, --quiet       - Be quiet (dont be too wordy)
 -p, --password    - Set specified password (do not ask interactively)
 -d, --directory   - Set home directory (default = ${HOME})
 -s, --shell       - Set user shell (default = ${COMSPEC})
 -e, --remoteshell - Set user remote shell (default = user shell)
 -g, --groups      - Set user groups (separated it by ';')
 -m, --pidmax      - Set maximum number of pids  for user
 -o, --comment     - Set comment (i.e. user full name, etc)

7. ACLS.EXE usage
_________________

Usage: acls.exe command [option/s] [section]

 Commands:

 -a, --add         - Add ACL's to section(s)
 -s, --set         - Set new or replace old section(s)
 -l, --list        - Display ACL's for specified section(s)
                     If no section specified, all section with
                     matching type will be listed.
 -r, --remove      - Remove specified section(s)
 -u, --update      - Update users (reload user ACL's into SSES driver) with 
                     specified ACL's section(s). If there are no sections 
                     specified, users with all sections of given type will be
                     updated.
 -h, --help        - Display usage information
 -v, --version     - Display program version

 Options:

 -f, --file        - The source file for add and set commands
 -t, --type        - The type of specified section(s)

 The type of section depends on used user and ACL's managing module. Generally,
 the section type is a number, but there are several predefined names : 'all'
 (0) means section with any type (default), 'user' (3) means user section,
 'group' (4) means group section, 'first' (1) - first section, 'last' (2) -
 last section (as defined in passwd.dll user manager).

 When add or set commands specified acls.exe searches for requested sections
 in given in -f option file, which has the same format as 'acls' file for
 passwd.dll (see below), except that there are no section id's. I.e. the section 
 of 'first' type will have the [first] header, not [123:first], etc.

 When the type set to 'all' all sections with matching name will be processed.

8. SU.EXE usage
_______________

 SU.EXE is a analog to UNIX su program to switch to another user. It 
 logs on a new user and runs its shell, specified in userbase. By OS/2 
 restrictions you wont by able to run PMSHELL.EXE as user shell with su if one
 PMSHELL is already running.

Usage: su.exe [option/s] [username]
 -p, --password     - Specify a password for user in command line. Use it with 
                      care, thus it is a potential security threat
 -s, --shell        - Set user shell to override the one from userbase
 -r, --remoteshell  - Use remoteshell from user base as a user shell
 -c, --command      - Pass a single command to the user shell. You can use it
                      switch to run the processes under some user privileges
                      from the batch files, i.e. 'su -p passwd -c apache.cmd user'
 -m, --sessmgr      - Switch session manager to selected user also. Beware, if
                      you'll switch your PMSHELL (usual session manager) to some
                      user with su, all sessions started from WPS will be 
                      registered under that user. To switch session manager back
                      to root, use 'su -m root' under the session owner by
                      previously selected user, or under the root session.
 -h, --help         - Display usage information
 -v, --version      - Display program version

 If username is not specified or specified as '-' su assumes root user to log on.

9. WHOAMI.EXE usage
___________________

Usage: whoami.exe

 WHOAMI is a analog to UNIX 'who am i' program and displays the uid and name of
 the user of the process which starts whoami.exe. The output of the whoami looks
 like:

0 root

 That means that the owner of the whoami's parent process is user 'root' with
 uid 0.

10. SHVIO.EXE and SHPM.EXE usage
________________________________

 SHVIO.EXE is a VIO local logon shell. On user logon it runs user's shell with
 DosExecPgm call. If the logged user's shell is PMSHELL, the users wont be able
 to logoff thus the first PMSHELL in the system cant be killed never. If the
 user's shell is not PMSHELL, user can logoff by closing all his processes, then
 the new logon dialog will be displayed. The SHVIO.EXE does not set USER_INI and
 SYSTEM_INI system variables, used by PMSHELL, so the config.sys settings, if 
 any, with be used by PMSHELL, if it will be set as user's shell.

 SHPM.EXE is a single PM local logon shell. On user logon it initialize PMSHELL
 and run user's shell as RUNWORKPLACE. The user can never logoff, but he still
 can switch to another user with su utility for selected processes.

 SHVIO.EXE and SHPM.EXE take no parameter. To set them up as a logon shell, set
 the following line in your CONFIG.SYS:

PROTSHELL=<Drive>:\<Path>\SHVIO.EXE 

 OR

PROTSHELL=<Drive>:\<Path>\SHPM.EXE 

11. SHPM2.EXE usage
___________________

 SHPM2.EXE is a multiple PM local logon shell. It runs as a RUNWORKPLACE shell 
 under PMSHELL. On user logon is starts user's shell and waits for its closing
 abd then locks desktop and displays next logon dialog. To logoff user it is 
 sufficient to kill main user's shell, that was run by SHPM2.EXE.
 To set up SHPM2.EXE as a user's shell, set the following lines in your CONFIG.SYS:

PROTSHELL=<Drive>:\OS2\PMSHELL.EXE 
RUNWORKPLACE=<Drive>:\<PATH>\SHPM2.EXE  [options]

 Where options are:

 -l <filename>      - log actions to filename
 -v <level>         - set log verbosity level (0..10)

 SHPM2.EXE loads environment variables from %HOME%\environment file before it
 starts a user shell. %HOME%\environment file has the following format:

; some comment
# some comment
REM also some comment
VARIABLE1=VALUE1
VARIABLE2=VALUE2
...

 If some environment variable already exists, it will be overrided except of 
 %HOME%, %USER%,%USERSHELL%, %RUNWORKPLACE% - this ones are set by user info 
 from Security/2 userbase and can be changed in %HOME%\environment.

12. LOGOFF.EXE usage
____________________

 LOGOFF.EXE is a local user logoff utility that ends all user's processes and
 thus logs off the user. Before shutting down user processes, it will ask user,
 if he is sure to logoff.
 To logoff user with leaving some of the user's processes running, run 
 'logoff -s' to close user's main shell for display next logon dialogue (if 
 SHPM2 or SHVIO local logon is used).

Usage: logoff.exe [-y/--yes] [-s/--shell] [-9/--hardkill] [-?/-h/--help]

 -y/--yes           - assume yes to 'Are You Sure' question
 -s/--shell         - close only main user shell. Other user processes stay running
 -9/--hardkill      - kills user processes DosUserKillProcess, which will skip
                      exception handlers of user's processes, but could kill bad
                      processes more successfully
 -?/-h/--help       - display help

13. KILL.EXE usage
__________________

 KILL.EXE is a one more analogue to UNIX kill utility. The main difference from
 existing OS/2 kill utilities is that it executes DosUserKillProcess for kill -9.

Usage:  kill [-signal] pid... or kill -l to list available signals

 The -signal could be either the number (i.e. kill -9) or the signal name 
 (i.e. kill -SIGKILL).

 List of available signals:

  4) SIGTERM    - Software Termination (default)
  6) SIGINT     - Interrupt (Ctrl-C)
  9) SIGKILL    - Unconditional Kill
 10) SIGBREAK   - Break (Ctrl-Break)

14. PASSWD.DLL usage
____________________

 The passwd.dll keeps user info in unixlike passwd file and ACL's in text mode
 acls file. The default locations are %ETC%/passwd for passwd and %ETC%/acls
 for ACL's file. To specify another location use

 ssesctl.exe --source <passwd path>?<ACL's path>

 The Security/2 installation places passwd and acls files to \security\etc
 directory and set appropriate --source key for ssesctl.exe in CONFIG.SYS.

 PASSWD format:
 --------------
 Each line in passwd file represents one user. It has format :

   user:pass:uid:maxproc:groups:home:shell:remoteshell:comment

 where,
    user        - user name
    pass        - md5-hashed password
    uid         - user ID
    maxproc     - maximal number of processes for user
    groups      - user groups separated by ';'
    home        - user home dir path
    shell       - shell path and parameters
    remoteshell - shell path and parameters
    comment     - comment

 Example:
 test:$1$PNPG$16dsrtHRTlu0F4FeV0sBq0:100:50:testgroup1;testgoup2:$d\home\test:$D\OS2\CMD.EXE:$D\OS2\VIOSTART.EXE --debug:Vasya Pupkin Incorporeited

 This is user test from group testgroup with uid (user id) = 100. Home dir is
 d:\home\test. User shell is d:\os2\viostart.exe with --debug switch.
 Maximal number if processes for this user is 50.
 The uid = 0 means root user.

 ACLS format:
 ------------
 The ACL's are divided into sections. There can be sections [id:first], 
 [id:last], [id:u:username], [id:g:groupname] where id is a section id > 0
 and < 0x80000000.

 [id:first] contains ACL's which will be placed to the top of the ACL list for
 each user except root.

 [id:last] contains ACL's which will be placed to the bottom of the ACL list for
 each user except root.

 [id:u:username] section contains ACL's specific for 'username' user.
 They will be placed after [first] section ACL's.

 [id:g:groupname] section are the ACL's specific for 'groupname' group. They 
 will be placed after [u:username] section ACL's, before the [last] section.

 The format of each section is:

[id:first]
; <allowed actions> <mask>
cwdr c:\docs\*
* c:\os2\*
- *myporno*

 The possible rights to actions :

 c - grant create
 w - grant write
 d - grant delete
 r - grant read
 x - grant execute
 s - grant start session
 - - deny all actions
 * - allow all actions

 <mask> is the resource (filename, device driver name, ...) mask. The SSES 
kernel driver compares this masks to the given name when OS/2 sends a 
request to open/read/write/... some resource.

 Besides the resorce name masks, there are special masks:

   '<user>' - defines the rights for user managing :
 c - create new user
 d - delete user
 w - change and update user
 r - get user info
 x - relogin to another user (su), register new user

   '<acl>' - defines the rights for acls managing :
 c - set new acls
 d - delete acls
 w - change existing acls
 r - get acls info

   '<dll>' - there only one only right 'x' is appliable to that mask, which 
means that all dll's that can be read can be also executed (i.e. loaded).

   '<timecrit>' - there only one only right 'x' is appliable to that mask, 
which means that user can set timecritical priority class to its processes.

 The ';' means comment. The rest of line after ';' will be ignored.

 There are special directives allowed in acls file:
 #include somefile.txt - includes file somefile.txt
 #define aaa bbb       - defines aaa=bbb, below this line all 'aaa' words
                         will be considered as 'bbb'
 #undef aaa            - cancels previous definition of 'aaa'

15. User and ACL's managing API
_______________________________

 See usertype.h and userbase.h.

 All listed functions must provide the functionality listed for corresponding
 DosUser* function.

 The pszSource parameter for all these calls may contain a string which
 describes source of the userbase (i.e. passwd and ACL's files location). If
 pszSource is NULL, then default values are used.

 If size of the provided buffers is too small to hold all data, then
 functions return required buffer length in the variable pointed by pcbBuffer
 parameter. In this case error code ERROR_MORE_DATA is returned if pBuffer
 parameter is not NULL and NO_ERROR if pBuffer is NULL.

 For user_query and other API's of this group, which return user info (user
 name, group, shell, etc., i.e. when the maximum buffer size is known) do not
 return error if the given buffer size is too small to hold all data - just
 return as much data as fit into buffer. If user_updatecallback is
 registered, it should be called for each operation which changes ACL's of the
 user. If this callback is not registered, user_change (when MaxProc value is changed),
 ACL_set, ACL_add and ACL_update MUST return ERROR_ACCESS_DENIED. Remember, 
 that user_aclquery MUST use provided allocMemory callback to allocate memory 
 for ACL's buffer.

 When you set user id's and ACL section id's remember that uid = 0 is reserved 
 for root, uid = -1 and section id = -1 or 0 are reserved for 'no id' value;

16. USERCTL.DLL API
___________________

 See usertype.h and userctl.h.

 All functions which accept buffer length parameter (pcbBuffer) return
 required buffer size being called with pBuffer parameter set to NULL.
 In this case variable pointed by pcbBuffer should be set to 0 before call.

17. Bugs And Limitations
________________________

 Some OS/2 kernels has errors is SES KPI. I.e. 14.062 traps somewhere when
 CallGate16 callback is defined. So, some systems may trap during boot if
 SSES.SYS is installed. If you run into this problem, you can either
 add /no16bitcontrol to sses.sys (this  will switch off priority control
 feature and also wont control some other 16 bit API calls) or replace OS2KRNL
 to another revision. 14.086 kernels from ACP2 works ok.
 Security/2 wont work together with AVP monitor, because the latter also
 intercepts the system calls like Security/2 does (using SEC32.SYS driver).

18. LICENSE
___________

 The software is free for personal, uncommercial use. For commercial use you 
 should obtain a special license. Contact author (dev.nul@mail.ru) to obtain 
 such license.

 And, of course:

 THIS SOFTWARE IS PROVIDED BY THE AUTHOR OR CONTRIBUTORS ``AS IS'' AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 OR SERVICES; LOSS OF USE, DATA, SEX OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 LIABILITY, OR TORT (INCLUDING NEGLIGENCE, SHIT ON CARPET OR OTHERWISE) 
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 POSSIBILITY OF SUCH DAMAGE.

19. Supporting the project
__________________________

 If you want to support Security/2 project, please, make your donation on
 BMT Micro site at https://secure.bmtmicro.com/ECommerce-OffSite/11980001.html
 or on Mensys at http://shop.mensys.nl/uk/security2.

 Also, visit the Security/2 homepage at http://os2.kiev.ua/en/sses.php

20. Author
__________

 nickk, dev.nul@mail.ru

 Big thanks for big help to :
 ----------------------------
 sunlover
 zuko
 Sergey I. Yevtushenko, es@os2.ru
 Alex Taylor for his shpm2_beauty.
 all those brave guys, who run this software and send me bugreports.
