________________________________________________________________________ KEYMANAGER README AND HOWTO Hugo Miranda / Administração de Sistemas do Departamento de Informática da Faculdade de Ciências da Universidade de Lisboa ________________________________________________________________________ Version 0.9 / February 2015 Table of Contents _________________ 1 Goal 2 Definitions 3 How it works .. 3.1 Overview .. 3.2 Detailed description .. 3.3 Configuration file syntax 4 Requirements .. 4.1 At the console .. 4.2 At the hosts 5 Installation steps .. 5.1 At the console .. 5.2 At the hosts .. 5.3 Configuration 6 Resync servers 7 Login personalisation at servers 8 Recommendations 9 Conclusions and remarks 1 Goal ====== keymgr is a software package aiming to facilitate the management of passwords of a team of system administrators in a pool of Linux servers. keymgr implements a model where each system administrator owns a unique login, materialised in a ssh asymmetric key pair. keymgr pushes the public key of each system administrator to the servers he is allowed to login. The process is considerably simplified by centralising the public keys and permissions on a single management console and by automatising the majority of the operations necessary to implement this model. 2 Definitions ============= In the reminder of the text, the following concepts are used admin: Any system administrator that should be able to login at one or more servers server: Any host using the keymgr package console: Some host responsible for pushing the admin public keys to servers 3 How it works ============== 3.1 Overview ~~~~~~~~~~~~ To perform its task, keymgr requires that each admin owns an individual ssh' asymmetric key pair. keymgr pushes the set of public keys of the admins allowed to operate some host into it. At the host, all admins share a common Home (in Linux sense) and group (also in Linux sense). Members of this group are allowed to sudo, thus gaining superuser access to the server. The list of the admins allowed to operate each server is defined at a configuration file stored in the console. This configuration file is the single point that concentrates all aspects of admin management. - Adding an admin is as simple as adding its login name to the groups of hosts he is allowed to operate - To remove an admin simply delete its login from the configuration file - Admins are exclusively required to place their public keys at a predefined location on the console to have them updated on all hosts Updates are pushed by the console to the servers by a script. A script running periodically at the hosts receives the keys, verifies their authenticity and updates system configuration (adding and removing users and their keys). To secure the system, the files pushed into the hosts must be signed by a passphrase protected asymmetric key pair at the console. 3.2 Detailed description ~~~~~~~~~~~~~~~~~~~~~~~~ The system uses 3 files: keys.cfg: is a configuration file at the console with 3 configuration directives: hostgroup: arranges hosts and hostgroups in groups (e.g. dbservers, webservers, ...) usergroup: arranges users and usergroups in groups (e.g. dbadmins, webadmins, ...) manage: indicates which users and usergroups can manage which hosts and hostgroups chgkeys: is a bash script to be run at the console. It parses keys.cfg and prepares two files for each host: keymgr.keys: a file containing the ssh public keys of all the admins allowed to access the host keymgr.sig: a file containing a signed digest of keymgr.keys updkeys: is a bash script suitable to be run by cron at each host. By default the script runs silently unless some new files are found. When new keymgr.sig and keymgr.keys are found, the signature is verified. If the file is valid, the script compares the list of admins in the file with those already installed at the system. The local list of admins is updated accordingly and the keys of all admins are updated. keymgr.keys and keymgr.sig are uploaded to the host using scp with a login that must exist at all servers. This is an untrusted user, with restricted privileges and whose single purpose is to support the upload of these files. In particular, the user does not have a shell, should not belong to the superuser group and is not allowed to login. Admins keys can be collected from their home directory at the console or from some "central repository" instantiated as a directory at the console. This model shows to be adequate for handling the majority of the cases related with the management of system administrators. Password compromise, addition and removal of members to the team and changes of roles in the team can all be handled by editing the keys.cfg file accordingly and executing the chgkeys script. The system heavily relies on the asymmetric key pair used for signing keymgr.keys and which is protected by a passphrase. To facilitate the update of this key pair, the keymgr.keys file uploaded to servers may also include the new public key, which will be signed using the old one. Changing this key pair is important for example if some admin left the team and he was aware of the original passphrase. At the servers, admins are recognised by belonging to a particular group (by default, admins). They all share the same home (by default /home/admins) and their list of ssh public keys is accumulated at the .ssh/authorized_keys file. For this to work, sudo permissions must be given to all users belonging to the admins group. 3.3 Configuration file syntax ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Users (admins) are mapped on servers in the config file, stored at the console, by default at /var/keymgr/keys.cfg. This file accepts three distinct specifications: hostgroup: creates a group of hosts usergroup: creates a group of users manage: creates a binding between hosts and users The formal specification of the commands is given by: ,---- | hostgroup : | usergroup : | manage : | | :: [ ] | :: | | :: STRING | :: STRING | :: [ ] | :: | | :: STRING | :: STRING `---- No formal distinction is made between usernames (resp. hostnames) and usergroups (resp. hostgroups). A string is interpreted as a group if it was declared as such in one usergroup (resp. hostgroup) clause. Otherwise it will be considered to be a username (resp. hostname). As an example, consider the following file: ,---- | hostgroup hg1 : h1 h2 | hostgroup hg2 : h3 hg1 | hostgroup hg3 : h1 h3 | usergroup ug1 : u1 u2 u3 | usergroup ug2 : u4 | manage hg3 : u1 u2 #rule A | manage h4 : ug1 u5 #rule B | manage hg2 : ug2 u3 #rule C `---- This file will put in place the following set of permissions (letters in the cells indicate the rule that originated the permission). User/Server h1 h2 h3 h4 ----------------------------- u1 A A B u2 A A B u3 C C C B u4 C C C u5 B After creating the file, make sure to run chgkeys with the "--pretend" argument, which will show the list of permissions to be granted without making any action to install them. 4 Requirements ============== The following software packages must be installed: 4.1 At the console ~~~~~~~~~~~~~~~~~~ - openssl - bash - ssh client - common Unix tools: sed, awk, grep, cut 4.2 At the hosts ~~~~~~~~~~~~~~~~ - openssl - bash - sudo - ssh server - common Unix tools: sed, awk, grep, cut - rssh or scponly shells 5 Installation steps ==================== 5.1 At the console ~~~~~~~~~~~~~~~~~~ - Place files at their expected locations: config: /etc/keymgr/config keys.cfg: /var/keymgr/keys.cfg chgkeys: /sbin or /usr/sbin. Give execution permissions - Edit config and keys.cfg to set it according to your preferences and requirements. Comments and instructions are inline. - Make sure that /etc/keymgr/config is owned by root and that it can only be written by the owner. - create the first signing key pair and put it at the location indicated in the config file (help is inline). To create it, we suggest: ,---- | openssl genpkey -outform PEM -algorithm rsa -des3 -out keymgr.pem | openssl rsa -in keymgr.pem -out keymgr.pub -outform PEM -pubout `---- note that passphrase should be strong and that without it you will not be able to update keys elsewhere - Copy keymgr.pem and keymgr.pub to the location indicated in the config file (by default /var/keymgr) - Create an ssh private/public key pair saving it as keymgr_rsa and keymgr_rsa.pub. A passphrase for this key is optional and will make your life harder when pushing keys as you will be required to type it when pushing keys to servers. - Put keymgr_rsa at the location indicated in KEYMGRF var of the config file and set root ownership and 600 permissions. - have each admin create his own ssh private/public key pair. To create it, we suggest: ,---- | ssh-keygen `---- - copy admins public key to some predefined location (see config file) naming it .pub or leave it at their default location (see chgkeys --help) 5.2 At the hosts ~~~~~~~~~~~~~~~~ Hosts configuration is considerably simplified by the sanity check option (-s) of the updkeys script, which makes an extensive evaluation of the conditions required for the script to work. Before, you'll need to: - Create the keymgr user - Don't set a password - Don't allow him to login (set the shell to rssh or scponly). NOTE: rssh configuration is tricky: you need to add the user to the rsshusers group and edit /etc/rssh.conf to allow scp. Confirm that the configuration is correct by performing a dummy scp before attempting to push keys with chgkeys. - Create .ssh at keymgr home and set its permissions to 700 - To prevent DoS attacks by filling the disk with bogus files, give a very small quota to the keymgr user. Such a DoS attack is only possible if the attacker has access to the (possibly unprotected) keymgr user key pair created above - Place files at their expected locations: config: /etc/keymgr updkeys: /sbin or /usr/sbin. Give execution permissions keymgr.pub: /var/keymgr. This is the file created when setting the console. Set permissions to 600 and ownership to root keymgr_rsa.pub: ~keymgr/.ssh/authorized_keys. Set permissions to 600 and owner keymgr - Create the admins group and /home/admins dir. - You will probably want to create the admins user so that bash config files are copied into it. This user will be automatically deleted after the first update given that the user will not be included in the pushed keys - Create /home/admins/.ssh dir so that the keys can be uploaded and set this dir permission's to 700 - Use visudo to edit the sudoers file, giving unrestricted sudo permissions to members of the admins group. This can be done by adding the following line to /etc/sudoers ,---- | %admins ALL=(ALL) NOPASSWD: ALL `---- Note that the NOPASSWD clause is fundamental given that admins will not have a password defined. To confirm everything is ok, you should first run updkeys -s. You can run it as many times as you want, to make sure that there are no complains. The error report also gives some suggestions on how to fix the problems found. Nothing will happen concerning user creation because no key file has been pushed. As a second step, you can make the first push (use chgkeys at the console). Then run locally updkeys -v (verbose) to make sure everything is ok. Note that if something goes wrong, you may need to push the keys again as updkeys deletes key files and signatures at the end of the run. Once all problems are solved, add updkeys to crontab, at a rate you find adequate. 5.3 Configuration ~~~~~~~~~~~~~~~~~ A large number of configuration parameters can be defined in /etc/keymgr/config. See the comments inline for a description. Note that the same file is used by both chgkeys (at the console) and updkeys (at the servers) but a copy is needed at each server and at the console. 6 Resync servers ================ From a functionality (not security) perspective, the weak point of the system is the need to keep the sync of the signing key, used by the console for signing the admin ssh keys. A change in the signing key that is not incorporated in some of the servers will result in having these servers to reject any subsequent update of either the signing key or of admin's ssh keys. Problems may emerge for example if the signing key is updated: - globally but one or more servers are down; - twice in quick succession, not giving time to all servers to incorporate the first update; The chgkeys script attempts to mitigate this problem by storing the previous key in a .old file and by providing a parameter that allows to specify which signing key should be used. Together, this can be used to push the new key to the servers that were left beyond. However, feel free to use your own backup plans. keymgr leaves the root password unchanged and is recommended that the root login by ssh is disabled. Therefore, if everything goes wrong, it is always possible to physically access the server using the root password and re-sync the system by installing the most up-to-date public key at the /var/keymgr dir. 7 Login personalisation at servers ================================== Admins will share a common Home and group at the servers. However, it is still possible to define personal configuration parameters by extending the standard login scripts with individual ones, using the LOGNAME environment variable. For example: - A personalised command line history can be defined by appending to ~admins/.bashrc ,---- | HISTFILE="${HISTFILE}_${LOGNAME}" `---- which will force the history file to be of the form .bash_history_ - Personalised start-up scripts can be defined by having the system to run an additional script, defined for each user, by appending to ~admins/.bashrc: ,---- | [[ -f ~/.bashrc_${LOGNAME} ]] && . ~/.bashrc_${LOGNAME} `---- This will force the start-up scripts at .bashrc_ (if the file exists) to be run after the common ones 8 Recommendations ================= - Login effort would be considerably simplified if admins make use of the ssh-agent facility (see man ssh-agent) - If the master signature file passphrase is known by admins, update it when removing some admin (otherwise he may create a new file including him again) - Disable ssh root login. This will make your system less vulnerable to brute force attacks. Note that the system was not conceived to update root user ssh key pairs. - Keep the ssh root password in a safe place. In case something goes wrong this will be your backdoor access. We made our best to ensure that the system is kept at a consistent state but cannot promise it and WILL NOT TAKE ANY RESPONSIBILITY FOR IT - Know what you are doing with cipher algorithms. If you think defaults are not strong enough, update the code to make them stronger. Make sure that everything (signing key and admin keys) are passphrase protected. 9 Conclusions and remarks ========================= The team made its best to remove any flaws from the code but will not take any responsibility for problems. Users are strongly suggested to take a look at the code to confirm that it does what it is supposed to do. If you find any problems, we will be happy to fix them, crediting you for it and publishing improved versions. Updates will be published at the projects home page: [http://www.di.fc.ul.pt/~hmiranda/keymgr] This is it. If you like and use the code or if you have any suggestions for improvements, feel free to let us know at geral@admin.di.fc.ul.pt and hmiranda@di.fc.ul.pt