Read Me

Key Manager is written to aid in distributing authorization to multiple 
remote servers.

################################################################################

Copyright (C) 2008 Jason Price

This file is part of key-manager.

key-manager is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

key-manager is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this key-manager.  If not, see <http://www.gnu.org/licenses/>.

################################################################################

NOTE:

    This is a general document describing the working of key-manager.  For
    install instructions, please see the README file.  For the license, see
    the LICENSE file.  For command line options run 'key-manager -h', or
    read the USAGE file.

PURPOSE:

    Key-manager is designed to help distribute ssh keys among multiple
    logons for many different computeres.  The short goal is to have a
    single host which is the 'ssh gateway' to the rest of the enterprise.
    Users would log into a 'management user' on this single host, and would
    unlock the ssh key for that 'management user'.  Once these two
    authentications are finished, they would have passwordless
    authentication to all hosts/users which had been delegated to them.

LIMITATIONS:

    This has been relativly well tested on RHEL4/5 and Ubuntu Linux.  It
    should be fairly easy to extend to other UNIX-like OS.  The big
    limitation/challenge will be the subtly different text and usage around
    'useradd' and 'passwd'.  Since I'm working with these commands through
    an expect-like interface, and these commands are a little different
    everywhere, well, you can expect some challenges.  The good news is
    that these limitations only apply to the ssh gateway.  The remote hosts
    only need to understand ssh.

DEFINITIONS:

    GROUP: As used in key-manager, it is a named entity which can have zero
    or more remote logons associated with it.  Each group has a single
    local user name on the management host associated with it (for example
    the 'all' group's local user is 'mgrall' by default).  

    MASTERGROUP: Typically called 'all' with the user 'mgrall' associated
    with it.  This group is the 'management' group with access to all
    logons under management.  This is needed to do maintenance within the
    system, to add/delete keys, update user settings, modify which users
    have access to which logons, etc.

    MASTERUSER: Typically called 'mgrall', this is the user associated with
    the MASTERGROUP.

    SSH GATEWAY: This is a host which users will log into.  It is where
    key-manager is installed and configured from.  Users will log into this
    host, and once they pass the double authentication, will be able to use
    effective passwordless authentication to manage multiple servers.
    Note, this host needs to be well secured for obvious reasons.

    LOGON: a user/host pair: say user postgres on host dbserver1.  A logon can
    be in three states with regards to key manager: 1) not under management 2)
    under management, but not distributed to other groups (only the mastergroup
    has access), and 3) distributed to other groups.  Moving a logon between
    each state requres a seperate key-manager command.

GENERAL DOCUMENTATION:

Key Manager's purpose in life is to allow you to create single users which
can access arbitrary groups of other user/host pairs via ssh keys.

For example, say you had 20 UNIX hosts, 10 running databases (accessed via
a postgres user), and 10 running webservers (accessed via a webmaster
user).  On your ssh gateway, key-manager could create 3 groups: root, web
and dba.  The root group (username mgrroot on the ssh gateway by default)
could be given access to the root user on all 20 hosts.  The web group
(username mgrweb) could be given access to the webmaster user on the 10
hosts, and the dba group could be given access to the postgres user on the
other 10 hosts.

But these divisons are completely arbitrary.  A group of developers could
be given root access to 3 web servers, and postgres access to 2 database 
servers, or root to 1 web server, webmaster to two others, and database to
3 servers.

Or you could fully distribute this process and have an mgr account for each
user.  This would allow VERY fine grained distribution, at the expense of more
management.

Any logon which is brought under management can be added to any group.
However, I do suggest putting some thought into your naming structure if you
get complicated.

Key Manager is designed such that there is a single ssh gateway host which
is allowed access to all other logons you want to have under 'management'.

This host must have network/firewall permissions to access all the hosts
you need to control via ssh (port 22).

The theory is that a single user on the ssh gateway represents each
group.  The group name is arbitrary.  There is a string which is prepended
to each group name to form the username, to make administration a little
easier.  By default this string is 'mgr', but you can set it at install
time.

There is one 'super group' which is used for management of the system.
That's the 'all' group (though this is also an arbitrary string, settable
at install time).  The mgrall user will have access to every logon which is
under management.

Since these accounts are obviously security concerns, there are two layers
of defense built into key-manager.  First, each management user has two
different passwords associated with it: one is the actual login password to
the user on the ssh gateway.  The second is the passphrase for the ssh key
associated with that group's user.  Key Manager generates secure, yet somewhat
human readable/rememberable passwords.  Look for the 'nicepass' function if
you're curious, but by default these passwords are 9 characters long, with 6
alpha characters, 2 numeric characters and 1 non-alpha numeric character.

If you can log into the system as a group account, this does not
automagically give you access to everything that group has access to.  You
must also have the ssh key password.

If you suspect that the private side of the key pair is compromised, Key
Manager allows you to regenerate all the keys in the system, either with
new key passwords, or keeping the same key passwords, depending on which
option you pass.  This is useful to tie in with a password expiration
policy.

A simple workflow follows:

1) As root, create a new group with 'key-manager -n'.
2) As mgrall, make sure the appropriate hosts are 'initialized' or brought
   under management: 'key-manager -i'.  This adds the user/host pair to the
   mgrall group.
3) As mgrall, add the user/host pair to the new group with 'key-manager -a'.

As root, frequently running the 'key-manager -S' to sync all users with the
state file is a good idea.  This keeps the access_<user> files up to date.

The access_<user> files are a list of hosts which that group can access as
<user>.  Each group account has these lists maintained via the sync.  These
files are accessed by the km_batch_copy and km_batch_execute commands.
km_batch_copy copies a file over to all hosts under that groups management.
The km_batch_execute runs a command on all hosts under management.  It takes a
directory as an argument, and that directory will be filled with
<hostname>.<timestamp> files containing the output of that command.

Key-manager also provides a bulk initialize for large numbers of hosts
(key-manger -J), and a bulk add login to group (key-manager -A).  You can
find details of this file format in the USAGE file, or by running the
commands (you'll be allowed to <ctrl>-c out before anything happens).

Running 'key-manager -h' (or without arguments after an install) will give 
you the user appropriate commands.  Root can do some things, and mgrall can
do some things.  There is some overlap, but most functions are unique to
each user.