Sysmask configuration ---------------------------------------------- Sysmask configuration is only an option. Sysmask can be used without configuration and without daemon, either via the utility /bin/sysmask, or via direct calls to the sysmask system call. However, interactive security behaviors can only be defined in sysmask configuration. And sysmask configuration takes effect only when the daemon smkd is active. Some basic sysmask configuration work can be done using the menu based interface sysmaskadm. ---------------------------------------------- Sysmask configuration works for processes with tokens. Each process may carry up to two sysmask tokens, one system-level token and one user-level token. Tokens are inherited by child processes and threads, in the same way as mask sets. System tokens can be used by system administrators for access control of ordinary users and system daemons. User tokens can be used by ordinary users for access control of softwares they launch. Each token takes an integer value between 1 and 65535. Up to 65535 system tokens and 65535 user tokens can be defined on the system. In the configuration files as well as for /bin/sysmask, tokens can be invoked using their values: s1, s2, s3, ..., s65535 for system tokens, u1, u2, u3, ..., u65535 for user tokens. You may also define aliased token names in the file /etc/sysmask/tokens. The system token s1 is reserved for use of sysmask initiation, and is attached to the alias name "init". It should not be used for other purposes. Also, the masks s65535 and u65535 are reserved for token inhibitor (processes already having a system or user token are not allowed to take another token at the same level). Their associated configurations should not be modified. ------------------------------------------------ Each token may have one associated configuration directory. If the directory is missing, the token mask is empty. However, if the process sets selective access control masks (ropen, wopen, sockop, exec), the empty token will totally block the corresponding accesses. This is because the access control of a token defaults to deny (for obvious security reasons). For system tokens, the configuration directory is under /etc/sysmask/sys/, so for example the directory /etc/sysmask/sys/111/ is associated to token s111. The entrance point /etc/sysmask/sys is only accessible by root, and if you have defined denyid in /etc/sysmask/smkdrc, the gid of the files will be automatically changed to that id, in order to make sure that processes with denyid mask set cannot access it. User tokens can have system-default configuration directories under /etc/sysmask/user/, in the same way as system tokens, for example with the directory /etc/sysmask/user/1024/ associated to token u1024. the content of /etc/sysmask/user/ should be world readable. Moreover, each user can have their own user token definitions, under $HOME/.sysmask/. For example, if the home of user guest is /home/guest, the existence a directory /home/guest/.sysmask/1024/ will tell sysmask to look there for definitions for u1024, when the euid of the process equals guest. Please note that it is the effective uid of the process that matters here, not the real uid! You are free to put comment lines (those starting with '#') into configuration files. Doing so will not hurt performance, as these files are cached and compiled by sysmask at runtime. ------------------------------------------------- The following files in a token directory defines the behavior of a token. Other files may be put into the directory, but they will have no effect on the token. mask Defines the masks associated with the token. Masks defined in this file will be added to that of the process, when the token is installed. If this file is missing, empty mask is associated to the token. open Defines file access rights: read, write, path checking. It is effective only when one of the following masks are set: ropen, wopen. exec Defines file access rights for execution. It is effective only when the mask "exec" is set, while "execve" is unset. call Defines system call daemon exception access rights. Its syntax is the same as for open and exec, with a system call translated to a path name under the form "/call_number/call_name". For example, "fork" is translated to "/2/fork". Wildcards work similarly as for files. socket Defines socket access rights. It is effective only when the mask "sockop" is set, while "socketcall" is unset. If one of the files "open", "exec", "call", "socket" is missing, the corresponding access control defaults to deny. This will probably lead to unexpected behavior even if the corresponding selective masks are unset in the mask definition of the token, because the process might have another token at a different level, under which the selective masks are set. In such a case, the missing file effectively transforms the selective mask into a hard one, whatever the definition for the other token is. This will probably prevent the process from working correctly. When one of these files is not used in the token, create one allowing access to everything. Various limitations on these files can be found in smkd.h. -------------------------------------------------- Each of the above configuration files is a plain text file, with a same syntax structure. Each file should be composed of one or more lines. A line is a string of characters terminated by the new-line character, unless the latter is escaped by the backslash character '\'. Lines may have arbitrary length, but the total length of a file is limited (to 64K for the time being). The file is divided into blocks. Adjacent blocks are separated by one or more blank lines. Lines containing only space characters are also considered blank. Each block consists of one or more non-blank lines. A line starting with '#' is a comment line. Such a line is not considered as blank, but has no effect otherwise. Inserting comments to configuration files has no effect on sysmask performance, as these files are semi-compiled then cached by smkd. A block is composed of the following 4 parts in the order given below. Each part may contain 0 or several lines. 1: precondition lines starting with the character '>'. The rest of the line under the format name=value (or name!=value for negated test). 2. pathnames lines defining pathname matching rules. Each line contains a pathname template with possibly embedded wildcard characters and variable substitutes. 3. postcondition Each line is under the format name=value (or name!=value) with no prefix. 4. action Each line is under the format name=value with no prefix. Here "name!=value" doesn't make sense. With the exception of mask file which can have only one block with only the action part containing mask definition actions, any other file can have up to 1024 blocks each (see smkd.h), with rules defined as follows. The blocks are parsed according to their order in the file. If precondition of a block is non-empty, then pathname must be non-empty, or the block has no effect. If both precondition and pathname are missing, the block is called "condition block". In this case, the postcondition lines are checked. If one of the conditions is not met, the parsing stops and the access is refused. Otherwise parsing continues to the next block, taking into account some definitions in the action part (see below). If the pathname part is non-empty, it is a normal block. First, the precondition lines are checked. If one of the conditions is not met, the rest of the block is skipped and parsing continues to the next block. Otherwise, pathname lines are checked. (Socket addresses are translated into pathname syntax; see the corresponding text.) If none of the pathname lines matches the pathname of the request, parsing continues to the next block. Otherwise, postcondition is checked. If one is not met, parsing stops and the access is refused. Otherwise, the access is accepted and parsing stops after the action lines of the block. If no matching block is found reaching the end of the file, the access is refused. --------------------------------------------------- Macros All the token definition files accept macros. A macro substitution can be invoked using the character '%' followed by a pair of parentheses enclosing the macro name. Macros are defined in the file /etc/sysmask/macros. Macro definitions can be nested. Macros allow the definition of system-wide configuration data in a unique place. They are also used for feedback configuration. When a token accepts feedback configuration, special macros are used whose definitions depend on the behavior of the processes under its protection. More precisely, when sysmask is put under feedback mode for the token, access requests (system calls, files, network) are registered by sysmask under a special feedback form, instead of being refused. The registered access feedbacks can then be collected and manually edited before commiting to the macro file so that they are allowed in the future. --------------------------------------------------- Pathname Each file access check goes against the pathname submitted to the kernel by the process. It the submitted pathname is not absolute, it is prepended by the absolute pathname of the current working directory, with respect to the root directory of the process. Therefore, the submitted pathname always starts with '/'. Slight uniformization is performed before the submitted pathname is put to matching check. "/some_path_dir/." or "/some_path_dir/" is replaced by "/some_path_dir". A line in the pathname part of the configuration matches the submitted pathname if the two are exactly the same textually. Matching also occurs if after variable substitution, the definition line contain wildcard characters that match the submitted pathname. Variable substitution occurs if the line contains the character '%'. In this case, the string %% is replaced by % %h is replaced by the home directory of the euid of the process, as defined in /etc/passwd. %i is replaced by the decimal numeric value of the euid of the process. %s is replaced by the default shell of the euid of the process. %u is replaced by the user name of the euid of the process. Wildcard characters are '*' and '?', in their usual sense under a shell command line. Namely, '?' matches any character except '/', or '.' if it immediately follows a '/'. '*' matches any string of characters not containing '/'. Moreover, A string "**" matches any string of characters. Special action is taken when directory backup ("/../" or "/.." at the end of pathname) is found within a "**" matching: if the rest of the filename matches the line, parsing stops at the current block and the access is refused. If the line starts with a '*', this character acts as "**". (If you want to wildcard only the first path component, use "/*/rest_of_the_path".) If the line ends with a '/', it acts as if two stars are appended: "/some_path/" is equivalent to "/some_path/**". -------------------------------------------------- Conditions All the condition names are valid both for precondition and for postcondition. Here are the available condition names, possible values and their meanings. Name: maskset Value: names of masks Meaning: For the condition to be met, all the masks given here must be set in the requesting process. This concerns only the first and the second mask sets. The capacity masks and system call exceptions have no effect. Name: maskunset Value: names of masks Meaning: As for maskset, but all the masks given in the value must be unset. Name: pathlim Value: a positive numerical value Meaning: The condition is met if the length of the submitted pathname does not exceed the given value. Name: namelim Value: a positive numerical value Meaning: The condition is met if any component (the string between two consecutive '/') has length not exceeding the given value. Name: depthlim Value: a positive numerical value Meaning: The condition is met if the depth of the pathname does not exceed the given value. ATTENTION depth starts by 1, including the root directory "/"! Name: backlim Value: a positive numerical value Meaning: The condition is met if the pathname contains a number of directory backups ("/../"); that exceed the given value. Name: uid Value: a list of numerical values, ranges or user names, separated by white spaces or commas. A range is two numerical values joined by the character '-', with no embedded spaces. For example, "1-999, 65535, nobody". Meaning: The condition is met if the euid (or the corresponding user name) of the process matches one of the items in the list. Name: call Value: a list of numerical values, ranges or system call names, separated by white spaces or commas. A range is two numerical values joined by the character '-', with no embedded spaces. For example, "chdir, symlink, 100-103". There is also a special call value, "backup", which is matched when the intermediate path before a directory backup is tested. This can be used to selectively deny directory backups. Meaning: The condition is met if the system call (or its number number) matches one of the items in the list. This test obviously makes no sense in the call file. Name: thistoken Value: a list of primary token names, such as s1,u1000,s10. No alias token names are accepted. Meaning: The condition is met if the token appears in the list. This condition is mainly used for conditional macro definitions. Name: refuse Value: a list of keywords, separated by white spaces or commas. Possible keywords and their meanings: space Pathname contains white spaces or new lines: space, '\t', '\f', '\v', '\n', '\r'. newline Pathname contains new line character: '\f', '\v', '\n', '\r'. ctrl Pathname contains control characters (characters with values between 1 and 31, except tab '\t' and new line '\n'). special Pathname contains one of the following: ()[]{}*?\<>|'"&$ unusual Pathname contains characters that are not alphanumeric or one of "./-_+", or one of the components starts with '-'. chroot The process has a different root as smkd. realroot The process has the same root as smkd. hardlink The (regular) file has a link count greater than 1. This keyword only applies to postcondition, and takes effect only for read-write file openings. symlink Pathname contains symbolic links. This keyword only applies to postcondition. backup Pathname contains directory backup (/../). Meaning: The condition is met if none of the keywords listed in the value matches the submitted filename. ---------------------------------------------- Actions Here are the available action names, possible values and their meanings. Only the following actions are effective in the mask file: mask, trigger, tcount, tmask Only the following actions are effective in a condition block: checkuid, options Name: access Value: for exec and socket, "allow" or "deny", default to "allow". for open, empty, "r", "w" or "rw", default to empty. Meaning: This is the main access definition for the block. Note the difference of default for the different context. Name: newuid Value: numeric value or user name Meaning: switch to the new euid. This is available only for exec, and only if the executed file is a binary. Name: newgid Value: numeric value or group name Meaning: same as newuid, but for egid. Name: checkuid Value: a numeric uid or user name Meaning: uid for additional permission check. Available only for exec and open but affects also path check. If this is defined, the requested file and the path leading to it must be accessible to this checkuid, in addition to the euid of the process. Name: mask Value: list of masks Meaning: add more active masks to the process. For the mask file, this line defines the default active mask for the token. If a file access is checked twice by the follow option, both masks (and their triggers) are applied. Name: trigger Value: trigger name or value Meaning: Trigger to install. For the mask file, this line defines the default mask trigger for the token. For other files, this pushes the existing trigger of the process to the active mask and installs the new trigger, if the trigger values are different. Name: tcount Value: a positive numerical value Meaning: The new trigger count. This line takes effect only if a new trigger is defined. Name: tmask Value: list of masks Meaning: Masks to put to the triggered mask set. Name: newtoken Value: numerical token value (WARNING token name cannot be used here) Meaning: Switch to the new token at the same token level as the current token. The actual mask definition of the process will be purged (together with newusertoken, these are the only places where a process can unset its masks), to be replaced by the default mask definition of the new token. If this is a system token, the existing user token of the process, if any, will also be removed. If this is a user token, the existing system token of the process, together with its masks, will be retained. User token definitions have no right to change the system token of a process. If a file access is checked twice by the follow option, only the token of the first check may be applied. Name: newusertoken Value: numerical token value (WARNING token name cannot be used here) Meaning: This can only be done by a system token. The actual mask definition of the process will be purged (together with newtoken, these are the only places where a process can unset its masks), to be replaced by the default mask definition of the system token plus that of the new user token. If the process already has a user token, it will be replaced by the new one. If a file access is checked twice by the follow option, only the token of the first check may be applied. Name: time2live Value: a positive numerical value Meaning: The number of seconds the process is allowed to live, whether running or sleeping. If the process has orphan mask set, all its children will also be killed when the time limit is reached. If this action is defined in the mask file, the time limit applies to all processes in a token session. Name: sizelim Value: a positive numerical value Meaning: The maximum memory size of the process (code+data+stack), in megabytes. Name: options Value: a list of option keywords, separated by commas or white spaces. Possible keywords and their meanings: debug Activate debugging under the condition that log mask is set. Debug output is in the log file /var/log/smkd.log, but only root can read it. Only for sysmask debugging, avoid using it in normal situations. debug2 Activate detailed matching tracing starting from the next block. But not for the current one! Implies debug. feedback Log matching requests for later feedback to configuration. follow If symbolic links are encountered in the current name resolving, recheck the physical file name. For open and exec. keepuid Do not follow suid bit of execution (in case suid mask cannot be set). Only valid for exec. This only keeps euid but not egid (for the time being), and will be erased if newuid action is defined at the same time. kill Kill the requesting process. A very brutal action to be employed when you are sure that the process is compromised. tick Decrease the trigger count, and if it reaches 0, add triggered mask set to the active one. There is a special trigger, "tick", that can only be decreased by this option. If a file access is checked twice by the follow option, only the tick of the first check may be applied. ------------------------------------------- The following resource limitation actions act on all processes of a same sysmask session, and are only valid in the mask file. Name: sizelim Value: a positive numerical value Meaning: The maximum memory size of the process (code+data+stack), in megabytes. Name: forklim Value: a positive numerical value Meaning: The maximum number of calls to fork(), clone() and vfork(). Name: forkdepth Value: a positive numerical value Meaning: The maximum depth of forks. Name: forkfreq Value: a positive numerical value Meaning: The maximum frequency of forks per second. Name: proclim Value: a positive numerical value Meaning: The maximum number of active processes and threads.