FAlse BOttom is a pam module for mapping passwords to actions.

=== Table of contents:
    - Usage;
    - FABO module options;
    - FABO file syntax;
    - Example of a FABO file;
    - Feedback and contributing;

                              === Usage ===

WARNING: Remember that additional passwords decrease security of your
account.

First, install the FABO module: `make install`.

Second, you need to create a FABO files.  Examples described in the next
"Example of a FABO file" section and the examples/ directory.

Creating FABO files steps(field names are case-sensitive):
    1. Create a fabo file. The FABO file perms must be at most
       FABO_MAX_PERMS (by default 0640) and it must be owned by root. You
       must give reading permission to a user personal group, therefore
       only user can read its hashes.
       $ ls -l /etc/fabo_egor
       > -rw-r----- 1 root egor 144 Oct 22 22:14 /etc/fabo_egor
    NOTE: Reason of the restriction is a mobile pincodes,
          because everyone knowing hash of the pincode may
          bruteforce it extremely quickly.
    2. Determine 'user' field i.e. 'user fabouser'.
    3. Determine 'hash' field of password, you can use mkpasswd(1)
       for hash generation.
    4. Determine 'command' field, i.e. 'command /bin/true' recommended
       to use absolute path, no arguments accepted (yet). CMD_MAX_PERMS (by
       default 0755) specifies maximum permissions for executable files
       determined by a 'command' value.
    NOTE: This hardening is done because everybody, who has
          write access to a file that may be executed by root,
          has root privileges.
    5. Determine 'access' field from the set of (permit|deny|depends)
       values.  In any case FABO waits for the end of execution, if you
       want run long-term action you should write a script that detach
       the action and exit with required code.
    6. Check the FABO files with fabo_syntax_checker utility before real
       usage. It can read data from files denoted by arguments:
       # fabo_syntax_checker /etc/fabo_file1 /etc/fabo_file2

NOTE: authentication process should have enough privilleges to read FABO
file and execute commands in it.  For high privilleged tasks (e.g. nuke
LUKS) you should write specific SUID/SGID programs.

Third, add the FABO module to a PAM configuration file for a needed
service.  Only 'auth' type supported.  If you need granted access by FABO
declare 'sufficient' control regime, WARNING that after it FABO takes an
absolute power over other authentication mechanisms i.e. two-step auth can
be bypassed.

    pam_fabo.so [options] fabo_files

TIP: Use an 'optional' control regime, if you don't want to grant access
     via pam_fabo.

Example:
auth    sufficient  pam_fabo.so logfile=/var/log/fabo \
                                errfile=/var/log/fabo \
                                /etc/fabo_egor        \
                                /etc/fabo_altlinux

TIP: Since absolute paths usually are quite long, for convenience you can
     use line extension with an escaped end of line: `\<LF>'.


                       === FABO module options ===

Supported module options:
    logfile=file
        The stdout of the command is appended to file. Use absolute.
    errfile=file
        The stderr of the command is appended to file. Use absolute.

The PAM config syntax doesn't have a blank escaping with '\' or
any quoting, so you cannot use blanks in options argument.

TIP: Due to unpredicable current directory you should use an
     absolute path for the 'file' arguments.


                         === FABO file syntax ===

FABO is ASCII text file with multiple entries.

Newline is valuable, so if you want to multiline field, it must
be escaped by '\'.

Any token can be enclosed in 'apostrophes' or "quotes".

Everything after '#' is a comment.

FABO file formal syntax:

# Ambiguity doesn't matter here
<FABO_FILE> ::= <ENTRY_SEP>     # Handle blank line prefix
                <ENTRY_LIST>
                <ENTRY_SEP>     # Handle blank line suffix

<ENTRY_LIST> ::= <ENTRY_LIST> <ENTRY_SEP> <ENTRY> | <ENTRY> | <EPS>
<ENTRY_SEP> ::= <EPS> | <EOL> <ENTRY_SEP>

# Eliminated left-recursion
<ENTRY_LIST> ::= <ENTRY> <ENTRY_LIST_RIGHT> | <EPS>
<ENTRY_LIST_RIGHT> ::= <ENTRY_SEP> <ENTRY> <ENTRY_LIST_RIGHT>

<ENTRY> ::= <USER_FIELD> <FLD_SEP>
            <HASH_FIELD> <FLD_SEP>
            <COMMAND_FIELD> <FLD_SEP>
            <ACCESS_FIELD> <FLD_SEP>

<FLD_SEP> ::= <ENTRY_SEP>       # Handle blank lines and comments
                                # between fields.

<USER_FIELD> ::= "user" <USERNAME> <EOL>
<HASH_FIELD> ::= "hash" <CRYPTHASH> <EOL>
<COMMAND_FIELD> ::= "command" <CMD_PATH> <EOL>
<ACCESS_FIELD> ::= "access" <ACCESS_MODE> <EOL>

<ACCESS_MODE ::= "permit" | "deny" | "depends"

USERNAME -- login username;
CRYPTHASH -- hashed passphrase in the crypt(5) storage format,
             see also mkpasswd(1) -- useful front end to crypt;
CMD_PATH -- path to command that will be executed, (NOTE: avoid non-ascii
            characters!);
ACCESS_MODE defines login regime:
- permit -- login if there is match;
- deny -- deny regardless of match;
- depends -- login depends of command exit status.


                     === Example of a FABO file ===
============
user    root
hash $y$j9T$NP20g1Kn9CNCe/fAW.qqV1$HMs2P1gF4F/3FiumYadJZzFk9wrNXvtYi2nWCM/W/m3
command /root/nuke_luks_and_shutdown
# We don't need access to shutting down device.
access  deny

user test
hash $2b$05$OE3JfA4kh3iumozJsCscmuXNgUu7UXuxmfrqUnBZ5h4swlilZTwrq
command /home/test/.shred_my_data
access deny

user suspicious
hash $y$j9T$TJUSgzllTgTFDSOV60agS0$ep7yVs6LH1k6aroj.hjB5Lmlcc/2IHHUNp7gzwynq.4
command /root/swap_suspicious_home				# doesn't swap back;)
access permit
===========

Look in the examples/ directory for ideas.


                    === Feedback and contributing ===

Follow the CODESTYLE to be familiar with some considerations about coding
style. It has some benefits, but may be strange especially for those people
whose first programming language was C.

If you find a bug, want a new feature or want to send a patch.

Mail me: "ved ascii(0x40) altlinux ascii(0x2E) org"
