diff --git a/doc/DecryptionProtocol.txt b/doc/DecryptionProtocol.txt index a7f650a..32d962a 100644 --- a/doc/DecryptionProtocol.txt +++ b/doc/DecryptionProtocol.txt @@ -1,4 +1,5 @@ -== Yubikey KSM Decryption Protocol == +Yubikey KSM Decryption Protocol +------------------------------- The protocol for asking the Yubikey Key Storage Module to decrypt an OTP is to request a HTTP resource as follows: diff --git a/doc/DesignGoals.txt b/doc/DesignGoals.txt index 062398d..4f9f4f7 100644 --- a/doc/DesignGoals.txt +++ b/doc/DesignGoals.txt @@ -1,9 +1,11 @@ -== YK-KSM Design Goals == +YK-KSM Design Goals +------------------- The YK-KSM component was designed for these objectives: * Have AES key storage be separate from the validation server -* Allow distribution of AES keys to multiple servers for load-balancing and high-availability +* Allow distribution of AES keys to multiple servers for + load-balancing and high-availability * The code must be short and easy to audit diff --git a/doc/GenerateKSMKey.txt b/doc/GenerateKSMKey.txt index d0976a2..f378634 100644 --- a/doc/GenerateKSMKey.txt +++ b/doc/GenerateKSMKey.txt @@ -1,4 +1,5 @@ -== Generate KSM Key == +Generate KSM Key +---------------- Import of key material to an YK-KSM is typically always done via the OpenPGP encrypted/signed KeyProvisioningFormat format. This setup @@ -11,7 +12,6 @@ key id of '8B88A11B'. After this step you may want to generate AES keys for your YubiKeys, see [[GenerateKeys]], and then import them to your KSM, see [[ImportKeysToKSM]]. - user@crater:~$ gpg --gen-key gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc. @@ -67,4 +67,4 @@ see [[GenerateKeys]], and then import them to your KSM, see uid YK-KSM crater Import Key sub 2048g/140A17F1 2009-12-14 - user@crater:~$ \ No newline at end of file + user@crater:~$ diff --git a/doc/GenerateKeys.txt b/doc/GenerateKeys.txt index 1a42388..90dc4de 100644 --- a/doc/GenerateKeys.txt +++ b/doc/GenerateKeys.txt @@ -1,4 +1,5 @@ -== Generate Keys == +Generate Keys +------------- To generate some AES keys for your !YubiKeys served via your YK-KSM, you use the 'ykksm-gen-keys' tool. The tool is useful for generating @@ -28,7 +29,7 @@ into a separate machine with a separate OpenPGP key. To display the test keys above, you can decrypt them using GnuPG: - user@ksm:~$ gpg < keys.txt + user@ksm:~$ gpg < keys.txt You need a passphrase to unlock the secret key for user: "YK-KSM crater Import Key" @@ -45,7 +46,7 @@ To display the test keys above, you can decrypt them using GnuPG: 5,cccccccccccg,c55773192393,7387b5f6bede83f64a9cd75b2023826a,d70c937bbbff,2009-12-14T16:40:57, gpg: Signature made Mon 14 Dec 2009 04:40:57 PM CET using DSA key ID 8B88A11B gpg: Good signature from "YK-KSM crater Import Key" - user@ksm:~$ + user@ksm:~$ The format is documented in the KeyProvisioningFormat wiki page. @@ -53,7 +54,7 @@ To generate many small files each containing just one key, you can use a small wrapper like this: - #!/bin/sh + #!/bin/sh set -e @@ -75,4 +76,4 @@ a small wrapper like this: while test $cur -le $stop; do ykksm-gen-keys $urandom $cur | gpg -a --sign --encrypt -r $key > $cur.asc cur=`expr $cur + 1` - done + done diff --git a/doc/ImportKeysToKSM.txt b/doc/ImportKeysToKSM.txt index b24085b..1caea82 100644 --- a/doc/ImportKeysToKSM.txt +++ b/doc/ImportKeysToKSM.txt @@ -1,4 +1,5 @@ -== Import Keys To Yubikey KSM == +Import Keys To Yubikey KSM +-------------------------- To import keys into the YK-KSM database from text files in the encrypted/signed KeyProvisioningFormat format, you can use the tool @@ -13,8 +14,6 @@ The tool requires that your system has a GnuPG private key, read For example, to import the file generated by the [[GenerateKeys]] document: - - user@ksm:~$ ykksm-import --verbose --database 'DBI:Pg:dbname=ykksm;host=127.0.0.1' --db-user ykksmimporter --db-passwd otherpassword < ~/keys.txt You need a passphrase to unlock the secret key for @@ -58,7 +57,6 @@ document: serialnr 5 publicName cccccccccccg internalName c55773192393 aesKey 7387b5f6bede83f64a9cd75b2023826a lockCode d70c937bbbff created 2009-12-14T16:40:57 accessed eol user@ksm:~$ - When importing large data sets it is recommended to avoid the --verbose flag to reduce noise. diff --git a/doc/Installation.txt b/doc/Installation.txt index 88f9493..6be8440 100644 --- a/doc/Installation.txt +++ b/doc/Installation.txt @@ -1,4 +1,5 @@ -== Installation and configuration of Yubikey KSM == +Installation and Configuration of Yubikey KSM +--------------------------------------------- The Yubikey KSM module is responsible for storing AES keys and providing two interfaces: @@ -20,11 +21,12 @@ will here explain how to set it up using MySQL or PostgreSQL. Note that you only need to install either MySQL or PostgreSQL (or any other supported database), not both! -=== Step 1: YK-KSM Installation === +Step 1: YK-KSM Installation +--------------------------- First you should download and install the latest YK-KSM release: - user@ksm:~$ sudo apt-get install wget make help2man + user@ksm:~$ sudo apt-get install wget make help2man ... user@ksm:~$ wget http://yubico.github.com/yubikey-ksm/releases/yubikey-ksm-1.8.tgz ... @@ -32,23 +34,24 @@ First you should download and install the latest YK-KSM release: user@ksm:~$ cd yubikey-ksm-1.8 user@ksm:~/yubikey-ksm-1.8$ sudo make install ... - user@ksm:~/yubikey-ksm-1.8$ + user@ksm:~/yubikey-ksm-1.8$ Alternatively, you may also check out YK-KSM from its source code repository. For example: - user@ksm:~$ sudo apt-get install git make help2man + user@ksm:~$ sudo apt-get install git make help2man ... user@ksm:~$ git clone git://github.com/Yubico/yubikey-ksm.git ... user@ksm:~$ cd yubikey-ksm user@ksm:~/yubikey-ksm$ sudo make install ... - user@ksm:~/yubikey-ksm$ + user@ksm:~/yubikey-ksm$ The rest of this documentation will assume you have installed the YK-KSM with 'make install'. -=== Step 2: Install web server and PHP === +Step 2: Install web server and PHP +---------------------------------- You will need to install a web server with PHP5 and the PHP mcrypt interface: @@ -57,13 +60,14 @@ interface: Any web server with PHP support should work. -=== Step 3A: MySQL Installation === +Step 3A: MySQL Installation +--------------------------- Install the required packages: - user@ksm:~$ sudo apt-get install mysql-server php5-mysql libdbd-mysql-perl + user@ksm:~$ sudo apt-get install mysql-server php5-mysql libdbd-mysql-perl ... - user@ksm:~$ + user@ksm:~$ The installation asks you for a MySQL "root" password, and I recommend to specify one. @@ -72,22 +76,22 @@ To avoid having to specify a password when using the 'mysql' tool interactively, you can store the password in ~/.my.cnf, see /usr/share/doc/mysql-server-5.0/README.Debian.gz. For example: - user@ksm:~$ cat > .my.cnf + user@ksm:~$ cat > .my.cnf [client] user = root password = YOURPASSWORD - user@ksm:~$ + user@ksm:~$ First create the database and the tables as follows: - user@ksm:~$ echo 'create database ykksm' | mysql + user@ksm:~$ echo 'create database ykksm' | mysql user@ksm:~$ mysql ykksm < /usr/share/doc/yubikey-ksm/ykksm-db.sql - user@ksm:~$ + user@ksm:~$ You should also create database users for the decrypt and import interfaces, normally called 'ykksmreader' and 'ykksmimporter': - user@ksm:~$ mysql --silent ykksm + user@ksm:~$ mysql --silent ykksm mysql> CREATE USER 'ykksmreader'; mysql> GRANT SELECT ON ykksm.yubikeys TO 'ykksmreader'@'localhost'; mysql> SET PASSWORD FOR 'ykksmreader'@'localhost' = PASSWORD('yourpassword'); @@ -96,31 +100,27 @@ interfaces, normally called 'ykksmreader' and 'ykksmimporter': mysql> SET PASSWORD FOR 'ykksmimporter'@'localhost' = PASSWORD('otherpassword'); mysql> FLUSH PRIVILEGES; mysql> \q - user@ksm:~$ + user@ksm:~$ -== Step 3B: PostgreSQL Installation == +Step 3B: PostgreSQL Installation +-------------------------------- Install some packages: - user@ksm:~$ sudo apt-get install postgresql php5-pgsql libdbd-pg-perl ... user@ksm:~$ - The database needs to be initialized as follows: - user@ksm:~$ sudo su postgres postgres@ksm:~$ createdb ykksm postgres@ksm:~$ psql ykksm < /usr/share/doc/yubikey-ksm/ykksm-db.sql postgres@ksm:~$ - You also need to create a user for the decrypt interface, normally called 'ykksmreader': - postgres@ksm:~$ psql ykksm -q ykksm=# CREATE USER ykksmreader PASSWORD 'yourpassword'; ykksm=# GRANT SELECT ON yubikeys TO ykksmreader; @@ -128,31 +128,28 @@ called 'ykksmreader': ykksm=# GRANT INSERT ON yubikeys TO ykksmimporter; ykksm=# \q postgres@ksm:~$ - During installation and debugging it may be useful to watch the database log entries: - user@ksm:~$ sudo tail -F /var/log/postgresql/postgresql-*-main.log & - -== Step 4: Include path configuration == +Step 4: Include path configuration +---------------------------------- Set the include path by creating a file /etc/php5/conf.d/ykksm.ini with the following content: - user@ksm:~$ sudo sh -c 'cat > /etc/php5/conf.d/ykksm.ini' include_path = "/etc/yubico/ksm:/usr/share/yubikey-ksm" user@ksm:~$ sudo /etc/init.d/apache2 restart user@ksm:~$ - The paths are the default, if you installed the YK-KSM in some other place you need to modify the paths. -== Step 5: Logging == +Step 5: Logging +--------------- The PHP interface uses syslog for logging of incoming requests. The facility is set in ykksm-config.php but defaults the LOG_LOCAL0. To @@ -160,13 +157,11 @@ place these messages in a separate file, you can add the following to /etc/syslog.conf, or if you use rsyslog, create a file /etc/rsyslog.d/ykksm.conf with this content: - user@ksm:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykksm.conf' local0.* -/var/log/ykksm.log user@ksm:~$ sudo /etc/init.d/rsyslog restart ... user@ksm:~$ - The '-' before the filename avoids syncing the file after each write, which is recommended for performance. @@ -175,7 +170,6 @@ The log file can grow large quickly, so it is a good idea to setup rotation of log files. Here is an example that rotates the log file weekly. Create a file /etc/logrotate.d/ykksm like this: - user@ksm:~$ sudo sh -c 'cat > /etc/logrotate.d/ykksm' /var/log/ykksm.log { weekly @@ -187,9 +181,9 @@ weekly. Create a file /etc/logrotate.d/ykksm like this: endscript } user@ksm:~$ - -=== Step 5.1: Fix default log (optional) === +Step 5.1: Fix default log (optional) +------------------------------------ Unfortunately, most default syslog configuration, including the syslog.conf configuration file on Debian, will also log all entries to @@ -200,49 +194,44 @@ rules. To avoid YK-KSM log entries in these other files, you must modify the default rules. For example, edit the following lines of /etc/rsyslog.conf (or /etc/syslog.conf if you don't use rsyslog): - *.*;auth,authpriv.none -/var/log/syslog *.=info;*.=notice;*.=warn;\ auth,authpriv.none;\ cron,daemon.none;\ mail,news.none -/var/log/messages - Change them into: - *.*;auth,authpriv.none,local0.none -/var/log/syslog *.=info;*.=notice;*.=warn;\ auth,authpriv.none;\ cron,daemon.none;\ local0.none;\ mail,news.none -/var/log/messages - -== Step 6: Decrypt OTP Interface == +Step 6: Decrypt OTP Interface +----------------------------- The interface to decrypt OTPs is implemented using a PHP script. You can place the script under any URL, but we recommend serving it as http://ykksm.example.org/wsapi/decrypt. The simplest way is to use the 'symlink' rule in our makefile: - user@ksm:~$ sudo make -f /usr/share/doc/yubikey-ksm/ykksm.mk symlink install -d /var/www/wsapi ln -sf /usr/share/yubikey-ksm/.htaccess /var/www/wsapi/.htaccess ln -sf /usr/share/yubikey-ksm/ykksm-decrypt.php /var/www/wsapi/decrypt.php user@ksm:~$ - You may also run the commands manually. -== Step 7: YK-KSM Configuration == +Step 7: YK-KSM Configuration +---------------------------- You need to edit the ykksm-config.php script. An example file is included in YK-KSM as 'ykksm-config.php'. It is normally installed as /etc/yubico/ksm/ykksm-config.php: - user@ksm:~$ sudo cat /etc/yubico/ksm/ykksm-config.php user@ksm:~$ - Be careful about the user permissions and ownership so that unrelated users on the system cannot read the database password. @@ -266,17 +254,16 @@ An example DSN for a PostgreSQL setup: $db_dsn = "pgsql:dbname=ykksm;host=127.0.0.1"; -=== The End === +The End +------- You now have a YK-KSM up and running. You can test the service by requesting a URL. Using wget, for example: - user@ksm:~$ sudo apt-get install wget user@ksm:~$ wget -q -O - 'http://localhost/wsapi/decrypt?otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh' ERR Unknown yubikey user@ksm:~$ - You will need to import keys into the database for the decrypt function to do anything useful. See [[ServerHardening]] on how to diff --git a/doc/KeyProvisioningFormat.txt b/doc/KeyProvisioningFormat.txt index 3b79518..dd6f83b 100644 --- a/doc/KeyProvisioningFormat.txt +++ b/doc/KeyProvisioningFormat.txt @@ -89,7 +89,8 @@ be encrypted to a particular OpenPGP key id): -----END PGP MESSAGE----- .... -=== Naming Scheme === +Naming Scheme +------------- The files should use the standard GnuPG output extension '.asc'. diff --git a/doc/MakeRelease.txt b/doc/MakeRelease.txt index 9840387..febf859 100644 --- a/doc/MakeRelease.txt +++ b/doc/MakeRelease.txt @@ -1,11 +1,11 @@ -==Maintainer instructions for making releases== - -===Introduction=== +Maintainer instructions for making releases +------------------------------------------- The point of this document is to describe all steps required to make a proper release of the yubikey-personalization project. -===Dependencies=== +Dependencies +------------ Making a release requires the following packages: @@ -15,7 +15,8 @@ which can be installed (under Ubuntu) by running: sudo apt-get install make git gnupg help2man git2cl -===Details=== +Details +------- * Make sure the version number in Makefile has been incremented. diff --git a/doc/ServerHardening.txt b/doc/ServerHardening.txt index eb437f3..dd2d630 100644 --- a/doc/ServerHardening.txt +++ b/doc/ServerHardening.txt @@ -1,54 +1,52 @@ -== Server Hardening == +Server Hardening +---------------- While the defaults should be secure, there are some simple administrative actions that will increase your overall security. None of these steps are required, but we encourage you to read this document to see if the enhancements are relevant for your environment. -=== Tighten PHP configuration === +Tighten PHP configuration +------------------------- Tighten the security of the PHP installation by creating a file /etc/php5/conf.d/harden.ini with the following content: - user@host:~$ sudo sh -c 'cat > /etc/php5/conf.d/harden.ini' display_errors = Off log_errors = On user@host:~$ - -=== Tighten Apache configuration === +Tighten Apache configuration +---------------------------- Tighten the security of the Apache installation by making sure directory listings are disabled globally. Edit /etc/apache2/conf.d/security and make sure the following is uncommented: - AllowOverride None Order Deny,Allow Deny from all - -=== Time synchronization === +Time Synchronization +-------------------- For logging and (on the validation server) time-stamping it is important to have synchronized clocks. Install ntp. - user@host:~$ sudo apt-get install ntp ... - -=== Firewall === +Firewall +-------- There is no reason why the KSM needs to listen to incoming requests from the entire Internet, and restricting access to the intended YK-VAL servers are recommended. - user@ksm:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables' #!/bin/sh # IPv4 firewall: @@ -74,7 +72,6 @@ YK-VAL servers are recommended. ip6tables -A INPUT -p tcp -i eth0 -s 2000:2:3::4 --dport 443 -j ACCEPT user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables user@ksm:~$ - Replace 1.2.3.4 (for IPv4) and 2000:1:2::3 (for IPv6) with the address of the host you want to be able to login from via SSH, and replace @@ -85,7 +82,6 @@ validation server and SSH host. For a validation server, you may want to allow HTTP(S) requests from anyone, but not anything else. - user@val:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables' #!/bin/sh # IPv4 firewall @@ -111,7 +107,6 @@ anyone, but not anything else. ip6tables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables user@ksm:~$ - Again, replace 1.2.3.4 (for IPv4) and 2000:1:2::3 (for IPv6) with the address of the host you want to be able to login from via SSH. @@ -119,7 +114,6 @@ address of the host you want to be able to login from via SSH. If you want to allow SSH and HTTP(S) from everywhere, but nothing else, try this: - user@val:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables' #!/bin/sh # IPv4 firewall @@ -145,9 +139,9 @@ else, try this: ip6tables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables user@val:~$ - -=== Database encryption === +Database Encryption +------------------- The database contains sensitive information. If someone is able to access your machine physically, they may shut it off and steal it with @@ -180,7 +174,6 @@ attempt to mount your encrypted partition automatically. Setup: - user@ksm:~$ sudo apt-get install loop-aes-utils loop-aes-modules-2.6-amd64 ... user@ksm:~$ sudo rmmod loop && sudo modprobe loop @@ -212,11 +205,9 @@ Setup: umount /ksm losetup -d /dev/loop0 user@ksm:~$ sudo chmod +x /usr/local/sbin/ykksm-{start,stop} - Slightly adapted for MySQL: - user@ksm:~$ sudo apt-get install loop-aes-utils loop-aes-modules-2.6-686 ... user@ksm:~$ sudo rmmod loop && sudo modprobe loop @@ -247,7 +238,6 @@ Slightly adapted for MySQL: umount /ksm losetup -d /dev/loop0 user@ksm:~$ sudo chmod +x /usr/local/sbin/ykksm-{start,stop} - Then in the future, to start the YK-KSM, you will need to login to the machine and issue the command 'sudo ykksm-start' and enter the disk @@ -255,7 +245,8 @@ encryption password. Again, make sure that you don't use any unencrypted swap. -=== Intrusion detection === +Intrusion Detection +------------------- To make some attacks discussed in the previous section harder, make sure that your system has a hardware intrusion detection system and diff --git a/doc/SyncMonitor.txt b/doc/SyncMonitor.txt index 99aa929..ffdf23c 100644 --- a/doc/SyncMonitor.txt +++ b/doc/SyncMonitor.txt @@ -1,4 +1,5 @@ -== YK-KSM Synchronization Monitor == +YK-KSM Synchronization Monitor +------------------------------ If you deploy multiple redundant YK-KSM instances, it is important to monitor them to make sure the data they have is synchronized. While @@ -13,18 +14,14 @@ and AES key. Sample output looks like this, first there is a Unix time (for freshness) and then is the truncated hash value. - - 1284488221 - 50f5649b80 - + 1284488221 + 50f5649b80 The script requires the Perl SHA-1 package. Install it like this: - - user@ksm:~$ sudo apt-get install libdigest-sha1-perl - ... - user@ksm:~$ - + user@ksm:~$ sudo apt-get install libdigest-sha1-perl + ... + user@ksm:~$ The typical way to use this is either manually or to run it in a cron job and output the hash to a file that can be downloaded by a remote @@ -33,14 +30,12 @@ that downloads this file from all of your KSMs, and the Nagios check verify that all values are 1) fresh (Unix time is not too old) and 2) that the truncated hash value is identical on all KSMs. - - user@ksm:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykksm-checksum' - #!/bin/sh - FILE=/var/www/checksum.txt - (date --utc +%s; ykksm-checksum --db-user ykksmreader --db-passwd `grep password /etc/yubico/ksm/ykksm-config.php|cut -d\ -f3|cut -d\" -f2`) > $FILE.tmp - mv $FILE.tmp $FILE - user@ksm:~$ sudo chmod +x /etc/cron.hourly/run-ykksm-checksum - + user@ksm:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykksm-checksum' + #!/bin/sh + FILE=/var/www/checksum.txt + (date --utc +%s; ykksm-checksum --db-user ykksmreader --db-passwd `grep passwo rd /etc/yubico/ksm/ykksm-config.php|cut -d\ -f3|cut -d\" -f2`) > $FILE.tmp + mv $FILE.tmp $FILE + user@ksm:~$ sudo chmod +x /etc/cron.hourly/run-ykksm-checksum If you notice mismatches, you may want to run ykksm-checksum with the '-v' parameter on the different hosts and then use 'diff -ur' or