diff --git a/doc/ClientInfoFormat.adoc b/doc/Client_Info_Format.adoc similarity index 87% rename from doc/ClientInfoFormat.adoc rename to doc/Client_Info_Format.adoc index 3f3e448..443a8bd 100644 --- a/doc/ClientInfoFormat.adoc +++ b/doc/Client_Info_Format.adoc @@ -1,5 +1,4 @@ -Format of Client Info Data --------------------------- +== Format of Client Info Data This file holds data used in the YubiKey OTP validation phase. @@ -11,32 +10,25 @@ Any empty line, or a line beginning with a # is ignored. The meaning are as follows: -* id: - +id:: the client identity, decimal integer -* active - +active:: the client state, 1 if active, 0 if not -* created - +created:: unix timestamp of when the client was created, decimal integer -* secret - +secret:: printable ascii string with shared HMAC secret for client id -* email - +email:: the email address used by the client, printable ascii string -* notes - +notes:: not used, printable ascii string -* otp - +otp:: the YubiKey OTP used to create the client, modhex string An examples of a valid data line: diff --git a/doc/GeneratingClients.adoc b/doc/Generating_Clients.adoc similarity index 53% rename from doc/GeneratingClients.adoc rename to doc/Generating_Clients.adoc index 6327876..e53101e 100644 --- a/doc/GeneratingClients.adoc +++ b/doc/Generating_Clients.adoc @@ -1,4 +1,4 @@ -= Generating Clients = +== Generating Clients For a client to be able to authenticate a YubiKey OTP with the Validation service, a client ID and matching secret is needed (the secret is only @@ -6,54 +6,57 @@ required for authenticated verification). To create a new client in the database with a new generated secret, the ykval-gen-clients command can be used. This document describes step by step instructions on generating and using clients. For more information regarding the various fields of the -client database, see [[ClientInfoFormat|Client Info Format]]. +client database, see link:Client_Info_Format.adoc[Client Info Format]. -== Client generation == +=== Client generation Use the command below to generate 5 clients. Note the usage of the --urandom flag, which speeds up generation, but is less secure! The command is run as root (using sudo), since it needs to be able to read the database configuration stored in /etc/yubico/val/config-db.php. -.... - user@val:~$ sudo ykval-gen-clients --urandom 5 +[source, sh] +---- +user@val:~$ sudo ykval-gen-clients --urandom 5 - 1,l+/c/XfDPDHsaNKrpjwL+bf/Hgs= - 2,LPGHqukoIAUGgDuOs7O0e1f8xD0= - 3,K+gWRE0euOjVOiLD4Nm0wyHrHY8= - 4,+8LF+ADANTAHnwB82xkBb+mNEFs= - 5,URc6oabcuRV8OWW1Hs1cYym3ba4= - user@val:~$ -.... +1,l+/c/XfDPDHsaNKrpjwL+bf/Hgs= +2,LPGHqukoIAUGgDuOs7O0e1f8xD0= +3,K+gWRE0euOjVOiLD4Nm0wyHrHY8= +4,+8LF+ADANTAHnwB82xkBb+mNEFs= +5,URc6oabcuRV8OWW1Hs1cYym3ba4= +user@val:~$ +---- -== Testing the clients == +=== Testing the clients The above clients can now be used with the validation server. If you have a YubiKey validation client, you can easily test this now. For example, using the ykclient command (available in the ykclient-dev package, which is in Debian as well as Ubuntu): -.... - user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey LPGHqukoIAUGgDuOs7O0e1f8xD0= 2 cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv - Input: - validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s - client id: 2 - token: cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv - api key: LPGHqukoIAUGgDuOs7O0e1f8xD0= - Verification output (1): Yubikey OTP was bad (BAD_OTP) - user@val:~$ -.... +[source, sh] +---- +user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey LPGHqukoIAUGgDuOs7O0e1f8xD0= 2 cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv +Input: + validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s + client id: 2 + token: cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv + api key: LPGHqukoIAUGgDuOs7O0e1f8xD0= +Verification output (1): Yubikey OTP was bad (BAD_OTP) +user@val:~$ +---- Note that even though the response was BAD_OTP (since the key used is in fact a bad OTP), the verification worked as expected. Compare it to the next example: -.... - user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey not_a_real_secret 3 cccccccccccdutfiljtbignggckhgdtfigbdricugdrvInput: - validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s - client id: 3 - token: cccccccccccdutfiljtbignggckhgdtfigbdricugdrv - api key: not_a_real_secret - Verification output (106): Server response signature was invalid (BAD_SERVER_SIGNATURE) - user@val:~$ -.... +[source, sh] +---- +user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey not_a_real_secret 3 cccccccccccdutfiljtbignggckhgdtfigbdricugdrvInput: + validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s + client id: 3 + token: cccccccccccdutfiljtbignggckhgdtfigbdricugdrv + api key: not_a_real_secret +Verification output (106): Server response signature was invalid (BAD_SERVER_SIGNATURE) +user@val:~$ +---- In the above example, the server actually noticed that the client secret was incorrect, and responded as it should. The response is signed with the correct diff --git a/doc/GettingStartedWritingClients.adoc b/doc/Getting_Started_Writing_Clients.adoc similarity index 89% rename from doc/GettingStartedWritingClients.adoc rename to doc/Getting_Started_Writing_Clients.adoc index 8670861..eb99b94 100644 --- a/doc/GettingStartedWritingClients.adoc +++ b/doc/Getting_Started_Writing_Clients.adoc @@ -1,18 +1,18 @@ -Getting Started Writing Clients -=============================== +== Getting Started Writing Clients -== Introduction +=== Introduction While the canonical description of the validation protocol is -documented in link:ValidationProtocolV20.adoc[ValidationProtocolV20], it may be difficult to grasp the -high level of how a client typically works. The intention with this -page is to illustrate one simple case. Note that this does not cover -the replicated protocol. +documented in link:Validation_Protocol_V2.0.adoc[Validation Protocol V2.0], +it may be difficult to grasp the high level of how a client typically +works. The intention with this page is to illustrate one simple case. + +NOTE: This does not cover the replicated protocol. If you want to make your own client implementation, here is the quickest way to get started: -== API key +=== API key API key is used to optionally sign the OTP validation request and to verify the OTP validation response. We recommend all production @@ -29,7 +29,7 @@ To get an API key, first use our online API key generator. It will assign you an ID and create a shared key. You can use the shared key to authenticate that the API responses do come from Yubico. -== Capture an OTP +=== Capture an OTP Capture an OTP output from your YubiKey. You can do that by opening a text editor and simply pressing the button on the YubiKey. The OTP is a @@ -37,7 +37,7 @@ simple string of characters, like this: vvvvvvcurikvhjcvnlnbecbkubjvuittbifhndhn -== Validate OTP format +=== Validate OTP format Prudent clients should validate the data entered by the user so that it is what the software expects. YubiKey OTPs consists of 32-48 @@ -49,7 +49,7 @@ other Dvorak layouts as well. For this reason, our recommendation is that clients only check that the input consists of 32-48 printable characters. -== Send OTP to our server +=== Send OTP to our server Send the authentication request to our servers following the protocol specified below. Your request should include the verifier ID (a number @@ -72,7 +72,7 @@ The servers that Yubico provides are: These servers are hosted in different places and by different organizations. -== Parse response +=== Parse response You will recieve a response back from the server, a string of text that resembles the following: @@ -88,13 +88,13 @@ You can check the authenticity of this response by checking that the OTP and nonce was the same as the one you requested validation for and verify the HMAC-SHA-1 signature. -== Make a decision +=== Make a decision Use the `status=` codes to make a decision whether to authenticate your user or not. All the status codes and their meanings are described by the protocol specification, see below. -== Binding an OTP to an Identity +=== Binding an OTP to an Identity Since a valid OTP on its own is not terribly useful, you need to connect it to a user in some way. This is normally not something the @@ -121,7 +121,7 @@ different identities with the only differ being case of the prefix. Typically you would store the association between the user and the YubiKey prefix in a database. -== The End +=== The End There are some more subtle matters that can be important, so please read the entire protocol specification for all the details. Further, diff --git a/doc/ImportExportData.adoc b/doc/ImportExportData.adoc deleted file mode 100644 index f0dd420..0000000 --- a/doc/ImportExportData.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= Importing and Exporting Data = - -The yubikey-val database holds client data as well as yubikey counter data -which you can import and export using the provided tools. As it is important -to protect the data, we will show you how to encrypt and decrypt these files -using GnuPG. You will therefor require a private key for both importing as -well as exporting (these can be the same keys, or differnent ones, depending -on if you are importing on the same system as you have exported from). - -== Client Info Data == - -The client data holds information about the clients that are able to use the -validation service, such as their ID and secret key. This data is stored in -the *clients* table of the database. - -The infomation here covers exporting existing clients to a file, and importing -the clients from that file into another database. For generating clients, see -link:GeneratingClients.html[GeneratingClients] - -To export client data, you can use the following command (Replace C5B8D4EA with -the key of the recipient of the data): - -.... - user@val:~$ sudo ykval-export-clients | gpg -a --encrypt -r C5B8D4EA -s > yk-client-info.asc - - You need a passphrase to unlock the secret key for - user: "YK-KSM import key" - 2048-bit RSA key, ID C5B8D4EA, created 2013-01-28 - user@val:~$ -.... - -To import the client data exported above, you can use: -.... - user@val:~$ gpg < yk-client-info.asc | sudo ykval-import-clients - - You need a passphrase to unlock the secret key for - user: "YK-KSM import key" - 2048-bit RSA key, ID 9372DC00, created 2013-01-28 (main key ID C5B8D4EA) - - gpg: encrypted with 2048-bit RSA key, ID 9372DC00, created 2013-01-28 - "YK-KSM import key" - gpg: Signature made Tue 29 Jan 2013 04:18:21 PM CET using RSA key ID C5B8D4EA - gpg: Good signature from "YK-KSM import key" - Successfully imported clients to database - user@val:~$ -.... - -== Yubikey Counter Data == - -The Yubikey counter data holds information about the state of the known -Yubikeys, such as their various counter values. This data is stored in the -*yubikeys* table of the database. - -To export Yubikey counter data, you can use the following command (Replace -C5B8D4EA with the key of the recipient of the data): - -.... - user@val:~$ sudo ykval-export | gpg -a --encrypt -r C5B8D4EA -s > yk-counter-data.asc - - You need a passphrase to unlock the secret key for - user: "YK-KSM import key" - 2048-bit RSA key, ID C5B8D4EA, created 2013-01-28 - user@val:~$ -.... - -To import the counter data exported above, you can use: -.... - user@val:~$ gpg < yk-counter-data.asc | sudo ykval-import - - You need a passphrase to unlock the secret key for - user: "YK-KSM import key" - 2048-bit RSA key, ID 9372DC00, created 2013-01-28 (main key ID C5B8D4EA) - - gpg: encrypted with 2048-bit RSA key, ID 9372DC00, created 2013-01-28 - "YK-KSM import key" - gpg: Signature made Tue 29 Jan 2013 04:18:21 PM CET using RSA key ID C5B8D4EA - gpg: Good signature from "YK-KSM import key" - Successfully imported yubikeys to database - user@val:~$ -.... - diff --git a/doc/Import_Export_Data.adoc b/doc/Import_Export_Data.adoc new file mode 100644 index 0000000..70d3cac --- /dev/null +++ b/doc/Import_Export_Data.adoc @@ -0,0 +1,81 @@ +== Importing and Exporting Data + +The yubikey-val database holds client data as well as yubikey counter data +which you can import and export using the provided tools. As it is important +to protect the data, we will show you how to encrypt and decrypt these files +using GnuPG. You will therefor require a private key for both importing as +well as exporting (these can be the same keys, or differnent ones, depending +on if you are importing on the same system as you have exported from). + +=== Client Info Data + +The client data holds information about the clients that are able to use the +validation service, such as their ID and secret key. This data is stored in +the *clients* table of the database. + +The infomation here covers exporting existing clients to a file, and importing +the clients from that file into another database. For generating clients, see +link:Generating_Clients.html[Generating Clients] + +To export client data, you can use the following command (Replace C5B8D4EA with +the key of the recipient of the data): + +.... +user@val:~$ sudo ykval-export-clients | gpg -a --encrypt -r C5B8D4EA -s > yk-client-info.asc + +You need a passphrase to unlock the secret key for +user: "YK-KSM import key" +2048-bit RSA key, ID C5B8D4EA, created 2013-01-28 +user@val:~$ +.... + +To import the client data exported above, you can use: +.... +user@val:~$ gpg < yk-client-info.asc | sudo ykval-import-clients + +You need a passphrase to unlock the secret key for +user: "YK-KSM import key" +2048-bit RSA key, ID 9372DC00, created 2013-01-28 (main key ID C5B8D4EA) + +gpg: encrypted with 2048-bit RSA key, ID 9372DC00, created 2013-01-28 + "YK-KSM import key" +gpg: Signature made Tue 29 Jan 2013 04:18:21 PM CET using RSA key ID C5B8D4EA +gpg: Good signature from "YK-KSM import key" +Successfully imported clients to database +user@val:~$ +.... + +=== Yubikey Counter Data + +The Yubikey counter data holds information about the state of the known +Yubikeys, such as their various counter values. This data is stored in the +*yubikeys* table of the database. + +To export Yubikey counter data, you can use the following command (Replace +C5B8D4EA with the key of the recipient of the data): + +.... +user@val:~$ sudo ykval-export | gpg -a --encrypt -r C5B8D4EA -s > yk-counter-data.asc + +You need a passphrase to unlock the secret key for +user: "YK-KSM import key" +2048-bit RSA key, ID C5B8D4EA, created 2013-01-28 +user@val:~$ +.... + +To import the counter data exported above, you can use: +.... +user@val:~$ gpg < yk-counter-data.asc | sudo ykval-import + +You need a passphrase to unlock the secret key for +user: "YK-KSM import key" +2048-bit RSA key, ID 9372DC00, created 2013-01-28 (main key ID C5B8D4EA) + +gpg: encrypted with 2048-bit RSA key, ID 9372DC00, created 2013-01-28 + "YK-KSM import key" +gpg: Signature made Tue 29 Jan 2013 04:18:21 PM CET using RSA key ID C5B8D4EA +gpg: Good signature from "YK-KSM import key" +Successfully imported yubikeys to database +user@val:~$ +.... + diff --git a/doc/Installation.adoc b/doc/Installation.adoc index 81a826d..297045f 100644 --- a/doc/Installation.adoc +++ b/doc/Installation.adoc @@ -1,4 +1,4 @@ -== Introduction == +== Introduction This document describes how to get one instance of the Yubikey Validation Server (YK-VAL) up and running. @@ -13,13 +13,13 @@ The validation server needs to talk to a Yubikey Key Storage Module (YK-KSM) to work. Thus, you either need to arrange for access to a remote YK-KSM and get the URL to it, or install your own YK-KSM. -Currently there are two recommended implementations of a YK-KSM. If you have a YubiHSM hardware dongle and want improve security, we recommend using Python-PyHSM: +Currently there are two recommended implementations of a YK-KSM. If +you have a YubiHSM hardware dongle and want improve security, we +recommend using +https://developers.yubico.com/python-pyhsm/[Python-PyHSM]. -https://github.com/Yubico/python-pyhsm - -Otherwise we recommend the "soft" YK-KSM: - -https://github.com/Yubico/yubikey-ksm/ +Otherwise we recommend the "soft" +https://developers.yubico.com/yubikey-ksm/[YK-KSM] The YK-KSM can be on the same machine as the validation server, but for improved security we recommend to use different machines for the @@ -27,9 +27,7 @@ validation server and the KSM. The OTP validation service is delivered through web service API. There's no web-based HTML form interface involved. The protocol is -defined at: - -http://www.yubico.com/developers/api/ +defined at: http://www.yubico.com/developers/api/ For redundancy it is possible to set up multiple instances of the YubiKey Validation Server. The intent is that clients should be able @@ -44,7 +42,7 @@ reach one particular server from one of the servers. For simplicity, we strongly recommend you to list non-local servers in each sync pool though. -== Installation == +== Installation This following steps applies to any GNU/Linux-like system, although it was written for Debian GNU/Linux. If you do not know which OS to use, @@ -53,113 +51,138 @@ well-known distribution that comes with 5 years of security support. Install the OS following its manual and enable automatic security upgrades if prompted. -=== Step 1: YK-VAL Installation === +=== Step 1: YK-VAL Installation First you should download and install the latest YK-VAL release: -.... - user@val:~$ sudo apt-get install git make - ... - user@val:~$ git clone git://github.com/Yubico/yubikey-val.git - ... - user@val:~$ cd yubikey-val - user@val:~/yubikey-val$ sudo make install -.... +[source, sh] +---- +user@val:~$ sudo apt-get install git make +... +user@val:~$ git clone git://developers.yubico.com/yubikey-val.git +... +user@val:~$ cd yubikey-val +user@val:~/yubikey-val$ sudo make install +---- The rest of this documentation will assume you have YK-VAL available in the default installation targets. You can override the paths, see the Makefile. -=== Step 2: Install web server and PHP === +=== Step 2: Install web server and PHP You also need to install a web server with PHP5, php5-curl and php-pear. - user@val:~$ sudo apt-get install apache2 php5 php5-curl php-pear +[source, sh] +user@val:~$ sudo apt-get install apache2 php5 php5-curl php-pear Any web server with PHP support should work. -=== Step 3: Database installation === +=== Step 3: Database installation Any SQL database with PHP support should work. We give examples for MySQL and PostgreSQL here. Note that you need to chose between either PostgreSQL or MySQL here. -==== Step 3A: MySQL Installation ==== +==== Step 3A: MySQL Installation Install the required packages: - - user@val:~$ sudo apt-get install mysql-server php5-mysql + +[source, sh] +user@val:~$ sudo apt-get install mysql-server php5-mysql The installation asks you for a MySQL "root" password, and I recommend to specify one. 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@val:~$ cat > .my.cnf - [client] - user = root - password = YOURPASSWORD - user@val:~$ chmod go-r .my.cnf - user@val:~$ +[source, sh] +---- +user@val:~$ cat > .my.cnf +[client] +user = root +password = YOURPASSWORD +user@val:~$ chmod go-r .my.cnf +user@val:~$ +---- Note the 'chmod' to protect your password from non-root users. The database needs to be initialized as follows: - user@val:~$ echo 'create database ykval' | mysql - user@val:~$ mysql ykval < /usr/share/doc/yubikey-val/ykval-db.sql - user@val:~$ +[source, sh] +---- +user@val:~$ echo 'create database ykval' | mysql +user@val:~$ mysql ykval < /usr/share/doc/yubikey-val/ykval-db.sql +user@val:~$ +---- You also need to create a database user for the verifier interface, normally called 'ykval_verifier': - user@val:~$ mysql --silent ykval - mysql> CREATE USER 'ykval_verifier'@'localhost'; \ - GRANT SELECT,INSERT,UPDATE(modified, yk_counter, yk_low, yk_high, yk_use, nonce) ON ykval.yubikeys TO 'ykval_verifier'@'localhost'; \ - GRANT SELECT(id, secret, active) ON ykval.clients TO 'ykval_verifier'@'localhost'; \ - GRANT SELECT,INSERT,UPDATE,DELETE ON ykval.queue TO 'ykval_verifier'@'localhost'; \ - SET PASSWORD FOR 'ykval_verifier'@'localhost' = PASSWORD('yourpassword'); \ - FLUSH PRIVILEGES; - mysql> \q - user@val:~$ +[source, sh] +---- +user@val:~$ mysql --silent ykval +mysql> CREATE USER 'ykval_verifier'@'localhost'; \ +GRANT SELECT,INSERT,UPDATE(modified, yk_counter, yk_low, yk_high, yk_use, nonce) ON ykval.yubikeys TO 'ykval_verifier'@'localhost'; \ +GRANT SELECT(id, secret, active) ON ykval.clients TO 'ykval_verifier'@'localhost'; \ +GRANT SELECT,INSERT,UPDATE,DELETE ON ykval.queue TO 'ykval_verifier'@'localhost'; \ +SET PASSWORD FOR 'ykval_verifier'@'localhost' = PASSWORD('yourpassword'); \ +FLUSH PRIVILEGES; +mysql> \q +user@val:~$ +---- -==== Step 3B: PostgreSQL Installation ==== +==== Step 3B: PostgreSQL Installation Install the required packages: - user@val:~$ sudo apt-get install postgresql php5-pgsql - ... - user@val:~$ +[source, sh] +---- +user@val:~$ sudo apt-get install postgresql php5-pgsql +... +user@val:~$ +---- The database needs to be initialized as follows: - user@val:~$ sudo su postgres - postgres@val:~$ createdb ykval - postgres@val:~$ psql ykval < /usr/share/doc/yubikey-val/ykval-db.sql - postgres@val:~$ +[source, sh] +---- +user@val:~$ sudo su postgres +postgres@val:~$ createdb ykval +postgres@val:~$ psql ykval < /usr/share/doc/yubikey-val/ykval-db.sql +postgres@val:~$ +---- You also need to create a database user for the verifier interface, normally called 'ykval_verifier': - postgres@val:~$ psql ykval -q - ykval=# CREATE USER ykval_verifier PASSWORD 'yourpassword'; - ykval=# GRANT SELECT,INSERT,UPDATE ON yubikeys TO ykval_verifier; - ykval=# GRANT SELECT ON clients TO ykval_verifier; - ykval=# GRANT SELECT, INSERT, UPDATE, DELETE ON queue TO ykval_verifier; - ykval=# \q - postgres@val:~$ +[source, sh] +---- +postgres@val:~$ psql ykval -q +ykval=# CREATE USER ykval_verifier PASSWORD 'yourpassword'; +ykval=# GRANT SELECT,INSERT,UPDATE ON yubikeys TO ykval_verifier; +ykval=# GRANT SELECT ON clients TO ykval_verifier; +ykval=# GRANT SELECT, INSERT, UPDATE, DELETE ON queue TO ykval_verifier; +ykval=# \q +postgres@val:~$ +---- Don't forget to switch back to your normal user - postgres@val:~$ exit - user@val:~$ +[source, sh] +---- +postgres@val:~$ exit +user@val:~$ +---- During installation and debugging it may be useful to watch the database log entries: - user@val:~$ sudo tail -F /var/log/postgresql/postgresql-*-main.log & +[source, sh] +user@val:~$ sudo tail -F /var/log/postgresql/postgresql-*-main.log & -=== Step 4: Setup Verify OTP Interface === +=== Step 4: Setup Verify OTP Interface The interface to verify OTPs is implemented using a PHP script. You can place the script under any URL, but we recommend serving it as @@ -167,35 +190,44 @@ can place the script under any URL, but we recommend serving it as the symlinks is to invoke 'make symlink' in your YK-VAL source tree. Like this: - user@val:~/yubikey-val$ sudo make symlink - install -d /var/www/wsapi/2.0 - ln -sf /usr/share/yubikey-val/ykval-verify.php /var/www/wsapi/2.0/verify.php - ln -sf /usr/share/yubikey-val/ykval-sync.php /var/www/wsapi/2.0/sync.php - user@val:~/yubikey-val$ +[source, sh] +---- +user@val:~/yubikey-val$ sudo make symlink +install -d /var/www/wsapi/2.0 +ln -sf /usr/share/yubikey-val/ykval-verify.php /var/www/wsapi/2.0/verify.php +ln -sf /usr/share/yubikey-val/ykval-sync.php /var/www/wsapi/2.0/sync.php +user@val:~/yubikey-val$ +---- If you want to do it manually, you can invoke the above commands manually. -=== Step 5: Include path configuration === +=== Step 5: Include path configuration Set the include path for the queue daemon by creating a file /etc/default/ykval-queue with the following content: - user@val:~$ sudo sh -c 'cat > /etc/default/ykval-queue' - DAEMON_ARGS="/etc/yubico/val:/usr/share/yubikey-val" - user@val:~$ +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/default/ykval-queue' +DAEMON_ARGS="/etc/yubico/val:/usr/share/yubikey-val" +user@val:~$ +---- You also need to set the include path for the PHP scripts running via Apache, using a .htaccess file: - user@val:~$ sudo sh -c 'cat > /var/www/wsapi/2.0/.htaccess' - RewriteEngine on - RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L] - +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /var/www/wsapi/2.0/.htaccess' +RewriteEngine on +RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L] + php_value include_path ".:/etc/yubico/val:/usr/share/yubikey-val" - - user@val:~$ sudo ln -s 2.0/.htaccess /var/www/wsapi/.htaccess - user@val:~$ + +user@val:~$ sudo ln -s 2.0/.htaccess /var/www/wsapi/.htaccess +user@val:~$ +---- The .htaccess file also sets up rewriting from the non-.PHP suffix URL name to the right script. @@ -203,76 +235,85 @@ name to the right script. The paths are the default, if you installed the YK-VAL in some other place you need to modify the paths. -=== Step 6: YK-VAL Configuration === +=== Step 6: YK-VAL Configuration You also need to create a ykval-config.php script. An example file is included in YK-VAL package as ykval-config.php A template is typically installed in /etc/yubico/val/ykval-config.php-template. - user@val:~$ sudo cp /etc/yubico/val/ykval-config.php-template /etc/yubico/val/ykval-config.php - user@val:~$ sudo emacs -nw /etc/yubico/val/ykval-config.php +[source, sh] +---- +user@val:~$ sudo cp /etc/yubico/val/ykval-config.php-template /etc/yubico/val/ykval-config.php +user@val:~$ sudo emacs -nw /etc/yubico/val/ykval-config.php +---- Be careful about the user permissions and ownership so that unrelated users on the system cannot read the database password. -You will typically need to modify the DSN (__YKVAL_DB_DSN__), database -passwords (__YKVAL_DB_PW__), the sync pool lists (__YKVAL_SYNC_POOL__ -and __YKVAL_ALLOWED_SYNC_POOL__), and the YK-KSM URLs inside the +You will typically need to modify the DSN ('__YKVAL_DB_DSN__'), database +passwords (__YKVAL_DB_PW__), the sync pool lists ('__YKVAL_SYNC_POOL__' +and '__YKVAL_ALLOWED_SYNC_POOL__'), and the YK-KSM URLs inside the otp2ksmurls function. An example DSN for a MySQL setup: - $baseParams['__YKVAL_DB_DSN__'] = "mysql:dbname=ykval;host=127.0.0.1"; +[source, php] +$baseParams['__YKVAL_DB_DSN__'] = "mysql:dbname=ykval;host=127.0.0.1"; An example DSN for a PostgreSQL setup: - $baseParams['__YKVAL_DB_DSN__'] = "pgsql:dbname=ykval;host=127.0.0.1"; +[source, php] +$baseParams['__YKVAL_DB_DSN__'] = "pgsql:dbname=ykval;host=127.0.0.1"; We recommend to add the hosts in YKVAL_SYNC_POOL as entries in '/etc/hosts' to avoid network delays caused by DNS-lookups. For example: - user@val:~$ sudo sh -c 'cat >> /etc/hosts' - 1.2.3.4 api1.example.com - 2.3.4.5 api2.example.com - user@val:~$ - +[source, sh] +---- +user@val:~$ sudo sh -c 'cat >> /etc/hosts' +1.2.3.4 api1.example.com +2.3.4.5 api2.example.com +user@val:~$ +---- To improve database performance you can use persistent database connection so that each request doesn't require a new connection to be setup. To enable this modify '__YKVAL_DB_OPTIONS__' as follows: - $baseParams['__YKVAL_DB_OPTIONS__'] = array(PDO::ATTR_PERSISTENT => true); +[source, php] +$baseParams['__YKVAL_DB_OPTIONS__'] = array(PDO::ATTR_PERSISTENT => true); -=== Step 7: Apache configuration === +=== Step 7: Apache configuration Create an apache web configuration file for the normal HTTP interface like this: -.... - user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval' - - ServerName api.example.com - ServerAdmin support@example.com +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval' + + ServerName api.example.com + ServerAdmin support@example.com - DocumentRoot /var/www/ - - Options FollowSymLinks - AllowOverride None - - - Options FollowSymLinks - AllowOverride All - Order allow,deny - allow from all - + DocumentRoot /var/www/ + + Options FollowSymLinks + AllowOverride None + + + Options FollowSymLinks + AllowOverride All + Order allow,deny + allow from all + - ErrorLog /var/log/apache2/ykval-error.log - LogLevel warn + ErrorLog /var/log/apache2/ykval-error.log + LogLevel warn - CustomLog /var/log/apache2/ykval-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" - ServerSignature On + CustomLog /var/log/apache2/ykval-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" + ServerSignature On - - user@val:~$ -.... + +user@val:~$ +---- HTTPS is strictly speaking not required, but we strongly recommend it. @@ -285,15 +326,18 @@ tools like GnuTLS "certtool". A small howto for !GoDaddy is available from http://permalink.gmane.org/gmane.comp.encryption.gpg.gnutls.devel/4062. -==== Step 7A: HTTPS via mod_gnutls ==== +==== Step 7A: HTTPS via mod_gnutls First install and enable the mod_gnutls module: - user@val:~$ sudo apt-get install libapache2-mod-gnutls - user@val:~$ sudo a2enmod gnutls - Enabling module gnutls. - Run '/etc/init.d/apache2 restart' to activate new configuration! - user@val:~$ +[source, sh] +---- +user@val:~$ sudo apt-get install libapache2-mod-gnutls +user@val:~$ sudo a2enmod gnutls +Enabling module gnutls. +Run '/etc/init.d/apache2 restart' to activate new configuration! +user@val:~$ +---- You will need to place the private key in /etc/ssl/private/api.example.com-key.pem and the certificate chain in @@ -301,116 +345,127 @@ You will need to place the private key in Create Apache web configuration files: -.... - user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl' - Listen 443 - - ServerName api.example.com - ServerAdmin support@example.com +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl' +Listen 443 + + ServerName api.example.com + ServerAdmin support@example.com - GnuTLSEnable on - GnuTLSCertificateFile /etc/ssl/private/api.example.com-chain.pem - GnuTLSKeyFile /etc/ssl/private/api.example.com-key.pem - GnuTLSPriorities NORMAL + GnuTLSEnable on + GnuTLSCertificateFile /etc/ssl/private/api.example.com-chain.pem + GnuTLSKeyFile /etc/ssl/private/api.example.com-key.pem + GnuTLSPriorities NORMAL - DocumentRoot /var/www/ - - Options FollowSymLinks - AllowOverride None - - - Options FollowSymLinks - AllowOverride All - Order allow,deny - allow from all - + DocumentRoot /var/www/ + + Options FollowSymLinks + AllowOverride None + + + Options FollowSymLinks + AllowOverride All + Order allow,deny + allow from all + - ErrorLog /var/log/apache2/ykval-ssl-error.log - LogLevel warn + ErrorLog /var/log/apache2/ykval-ssl-error.log + LogLevel warn - CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" - ServerSignature On + CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" + ServerSignature On - - user@val:~$ -.... + +user@val:~$ +---- -==== Step 7B: HTTPS via mod_ssl ==== +==== Step 7B: HTTPS via mod_ssl The mod_ssl module is typically installed by default, but you need to enable it. - user@val:~$ sudo a2enmod ssl - Enabling module ssl. - Run '/etc/init.d/apache2 restart' to activate new configuration! - user@val:~$ +[source, sh] +---- +user@val:~$ sudo a2enmod ssl +Enabling module ssl. +Run '/etc/init.d/apache2 restart' to activate new configuration! +user@val:~$ +---- You will need to place the private key in /etc/ssl/private/api.example.com-key.pem and the certificate chain in /etc/ssl/private/api.example.com-chain.pem. -.... - user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl' - - ServerName api.example.com - ServerAdmin support@example.com +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl' + + ServerName api.example.com + ServerAdmin support@example.com - SSLEngine on - SSLCertificateFile /etc/ssl/private/api.example.com-chain.pem - SSLCertificateChainFile /etc/ssl/private/api.example.com-chain.pem - SSLCertificateKeyFile /etc/ssl/private/api.example.com-key.pem + SSLEngine on + SSLCertificateFile /etc/ssl/private/api.example.com-chain.pem + SSLCertificateChainFile /etc/ssl/private/api.example.com-chain.pem + SSLCertificateKeyFile /etc/ssl/private/api.example.com-key.pem - DocumentRoot /var/www/ - - Options FollowSymLinks - AllowOverride None - - - Options FollowSymLinks - AllowOverride All - Order allow,deny - allow from all - + DocumentRoot /var/www/ + + Options FollowSymLinks + AllowOverride None + + + Options FollowSymLinks + AllowOverride All + Order allow,deny + allow from all + - ErrorLog /var/log/apache2/ykval-ssl-error.log - LogLevel warn + ErrorLog /var/log/apache2/ykval-ssl-error.log + LogLevel warn - CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" - ServerSignature On + CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" + ServerSignature On - - user@val:~$ -.... + +user@val:~$ +---- -==== Common Apache Configuration ==== +==== Common Apache Configuration This step is the same for both mod_gnutls and mod_ssl. - user@val:~$ sudo a2enmod rewrite - Enabling module rewrite. - Run '/etc/init.d/apache2 restart' to activate new configuration! - user@val:~$ sudo a2dissite default - Site default disabled. - Run '/etc/init.d/apache2 reload' to activate new configuration! - user@val:~$ sudo a2ensite ykval ykval-ssl - Enabling site ykval. - Enabling site ykval-ssl. - Run '/etc/init.d/apache2 reload' to activate new configuration! - user@val:~$ sudo /etc/init.d/apache2 restart - user@val:~$ +[source, sh] +---- +user@val:~$ sudo a2enmod rewrite +Enabling module rewrite. +Run '/etc/init.d/apache2 restart' to activate new configuration! +user@val:~$ sudo a2dissite default +Site default disabled. +Run '/etc/init.d/apache2 reload' to activate new configuration! +user@val:~$ sudo a2ensite ykval ykval-ssl +Enabling site ykval. +Enabling site ykval-ssl. +Run '/etc/init.d/apache2 reload' to activate new configuration! +user@val:~$ sudo /etc/init.d/apache2 restart +user@val:~$ +---- -=== Step 8: Logging === +=== Step 8: Logging The PHP interface uses syslog for logging of incoming requests. The facility is LOG_LOCAL0. To 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/ykval.conf with this content: - user@val:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykval.conf' - local0.* -/var/log/ykval.log - user@val:~$ sudo /etc/init.d/rsyslog restart - ... - user@val:~$ +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykval.conf' +local0.* -/var/log/ykval.log +user@val:~$ sudo /etc/init.d/rsyslog restart +... +user@val:~$ +---- The '-' before the filename avoids syncing the file after each write, which is recommended for performance. @@ -419,25 +474,28 @@ 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/ykval like this: - user@val:~$ sudo sh -c 'cat > /etc/logrotate.d/ykval' - /var/log/ykval.log { - weekly +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/logrotate.d/ykval' +/var/log/ykval.log { + weekly dateext - compress - missingok - rotate 9999 - notifempty - postrotate - invoke-rc.d rsyslog reload > /dev/null + compress + missingok + rotate 9999 + notifempty + postrotate + invoke-rc.d rsyslog reload > /dev/null endscript - } - user@val:~$ +} +user@val:~$ +---- You may want to modify the default /etc/logrotate.d/apache2, useful things to add are 'dateext' and 'compress' and change 'rotate' to something large if you want to retain logs. -=== Step 8.1: Fix default log (optional) === +=== Step 8.1: Fix default log (optional) Unfortunately, most default syslog configuration, including the syslog.conf configuration file on Debian, will also log all entries to @@ -448,88 +506,95 @@ rules. To avoid YK-VAL 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): -.... - *.=debug;\ - auth,authpriv.none;\ - news.none;mail.none -/var/log/debug - *.*;auth,authpriv.none -/var/log/syslog - *.=info;*.=notice;*.=warn;\ - auth,authpriv.none;\ - cron,daemon.none;\ - mail,news.none -/var/log/messages -.... +[source, conf] +---- +*.=debug;\ + auth,authpriv.none;\ + news.none;mail.none -/var/log/debug +*.*;auth,authpriv.none -/var/log/syslog +*.=info;*.=notice;*.=warn;\ + auth,authpriv.none;\ + cron,daemon.none;\ + mail,news.none -/var/log/messages +---- Change them into: -.... - *.=debug;\ - auth,authpriv.none;\ - news.none;mail.none;local0.none -/var/log/debug - *.*;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 -.... +[source, conf] +---- +*.=debug;\ + auth,authpriv.none;\ + news.none;mail.none;local0.none -/var/log/debug +*.*;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 +---- Idempotent commands to speed this up: - user@host:~$ sudo perl -pi -e 's/;auth,authpriv.none/;auth,local0.none,authpriv.none/' /etc/rsyslog.conf - user@host:~$ sudo perl -pi -e 's/news.none;mail.none/news.none;local0.none;mail.none/' /etc/rsyslog.conf - user@host:~$ sudo perl -pi -e 's/cron,daemon.none/cron,daemon.none;local0.none/' /etc/rsyslog.conf - user@host:~$ sudo /etc/init.d/rsyslog restart +[source, sh] +---- +user@host:~$ sudo perl -pi -e 's/;auth,authpriv.none/;auth,local0.none,authpriv.none/' /etc/rsyslog.conf +user@host:~$ sudo perl -pi -e 's/news.none;mail.none/news.none;local0.none;mail.none/' /etc/rsyslog.conf +user@host:~$ sudo perl -pi -e 's/cron,daemon.none/cron,daemon.none;local0.none/' /etc/rsyslog.conf +user@host:~$ sudo /etc/init.d/rsyslog restart +---- -=== Step 9: Start Sync Daemon === +=== Step 9: Start Sync Daemon When using yubikey-val in a sync pool, you need to have the ykval-queue daemon running to ensure that data is synchronized between the servers in the pool. The easiest way of running this is to simply invoke ykval-queue in a shell: - user@val:~$ sudo ykval-queue +[source, sh] +user@val:~$ sudo ykval-queue However, the recommended approach is to automate running this process in the background, by use of an init script or similar. Instructions on doing so vary depending on your operating system. -=== Step 10: Sync data from an existing server (optional) === +=== Step 10: Sync data from an existing server (optional) If you're adding a new server to an existing pool, you can synchronize all YubiKey counter data from one of the existing servers. To do so, the server you want to sync from needs to be configured to allow it. Do this by editing /etc/yubico/val/ykval-config.php on the existing server, adding the new -servers IP address to the __YKRESYNC_IPS__ setting. You'll most likely want -to add the IP to the __YKVAL_ALLOWED_SYNC_POOL__ setting as well. You also +servers IP address to the '__YKRESYNC_IPS__' setting. You'll most likely want +to add the IP to the '__YKVAL_ALLOWED_SYNC_POOL__' setting as well. You also need to edit this file on the new server, adding the existing server(s) IP -address(es) to __YKVAL_ALLOWED_SYNC_POOL__. +address(es) to '__YKVAL_ALLOWED_SYNC_POOL__'. Once these permissions have been configured, you can initiate the full sync by running the following command from the new server: - user@val:~$ ykval-synchronize http:///wsapi/2.0/resync all +[source, sh] +user@val:~$ ykval-synchronize http:///wsapi/2.0/resync all -=== Step 11: Test it === +=== Step 11: Test it -You can test the service by requesting a URL. Using wget, for -example: +You can test the service by requesting a URL. Using wget, for example: -.... - user@val:~$ wget -q -O - 'http://localhost/wsapi/2.0/verify?id=1&nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak&otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh' - h=/QVWkl5VlcX+Or1A2b3vOeoLEwI= - t=2010-05-17T14:48:15Z0355 - otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh - nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak - status=NO_SUCH_CLIENT +[source, sh] +---- +user@val:~$ wget -q -O - 'http://localhost/wsapi/2.0/verify?id=1&nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak&otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh' +h=/QVWkl5VlcX+Or1A2b3vOeoLEwI= +t=2010-05-17T14:48:15Z0355 +otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh +nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak +status=NO_SUCH_CLIENT - user@val:~$ -.... +user@val:~$ +---- Naturally, you will need to import client keys into the database for the verify function to work properly. -=== The End === +=== The End You now have a YK-VAL up and running. See -https://github.com/Yubico/yubikey-ksm/wiki/ServerHardening on how to +https://developers.yubico.com/yubikey-ksm/Server_Hardening.html on how to improve security of your system. diff --git a/doc/MakeRelease.adoc b/doc/Make_Release.adoc similarity index 86% rename from doc/MakeRelease.adoc rename to doc/Make_Release.adoc index 45e71e8..1040ac7 100644 --- a/doc/MakeRelease.adoc +++ b/doc/Make_Release.adoc @@ -1,12 +1,11 @@ -Maintainer instructions for making releases -=========================================== +== Maintainer instructions for making releases -== Introduction +=== Introduction 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: @@ -16,7 +15,7 @@ which can be installed (under Ubuntu) by running: sudo apt-get install make git gnupg git2cl -== Details +=== Details * Make sure the doc/ sub-directory uses the latest revision. Confirm with: cd doc && git checkout master && git pull && git diff diff --git a/doc/MuninProbes.adoc b/doc/MuninProbes.adoc deleted file mode 100644 index 2d1552c..0000000 --- a/doc/MuninProbes.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= YK-VAL Munin Plugin = - -Munin is a powerful system monitoring solution. See -http://munin-monitoring.org/ for more information. This document -documents how to install and enable the YK-VAL Munin plugins on a -Munin node. You need to install and configure Munin before following -these steps. - -The following Munin plugins are shipped as part of YK-VAL. They make -it easy for you to monitor your YK-VAL installation. - -* ykval_ksmlatency: Monitor the latency to each KSM. A useful side -effect is that it tests whether the KSM is operational for the -particular validation server. - -* ykval_vallatency: Monitor the latency to the other VAL servers, for -both IPv4 and IPv6. - -* ykval_queuelength: Monitor the size of the YK-VAL queue. - -The plugins are installed by 'make install' but needs to be configured -before they can be used. First create a Munin configuration file to -make sure the plugins can access the YK-VAL ykval-config.php -configuration file: - - user@val:~$ sudo sh -c 'cat > /etc/munin/plugin-conf.d/ykval' - [ykval_ksmlatency] - group www-data - [ykval_vallatency] - group www-data - [ykval_queuelength] - group www-data - user@val:~$ - -Then check that they are working properly: - - user@val:~$ sudo /usr/sbin/munin-run --servicedir /usr/share/munin/plugins ykval_queuelength autoconf - yes - user@val:~$ sudo /usr/sbin/munin-run --servicedir /usr/share/munin/plugins ykval_queuelength config - graph_title YK-VAL queue size - graph_vlabel sync requests in queue - graph_category ykval - queuelength.label sync requests - queuelength.draw AREA - user@val:~$ sudo /usr/sbin/munin-run --servicedir /usr/share/munin/plugins ykval_queuelength - queuelength.value 0 - user@val:~$ - -Enable the plugin as follows: - - user@val:~$ sudo munin-node-configure --shell | sudo sh - user@val:~$ sudo /etc/init.d/munin-node restart - Stopping Munin-Node: done. - Starting Munin-Node: done. - user@val:~$ - -After some time, you should see new graphs on your Munin master. diff --git a/doc/Munin_Probes.adoc b/doc/Munin_Probes.adoc new file mode 100644 index 0000000..1bad5ed --- /dev/null +++ b/doc/Munin_Probes.adoc @@ -0,0 +1,68 @@ +== YK-VAL Munin Plugin + +Munin is a powerful system monitoring solution. See +http://munin-monitoring.org/ for more information. This document +documents how to install and enable the YK-VAL Munin plugins on a +Munin node. You need to install and configure Munin before following +these steps. + +The following Munin plugins are shipped as part of YK-VAL. They make +it easy for you to monitor your YK-VAL installation. + +ykval_ksmlatency:: + Monitor the latency to each KSM. A useful side effect is that it tests + whether the KSM is operational for the particular validation server. + +ykval_vallatency:: + Monitor the latency to the other VAL servers, for + both IPv4 and IPv6. + +ykval_queuelength:: + Monitor the size of the YK-VAL queue. + +The plugins are installed by 'make install' but needs to be configured +before they can be used. First create a Munin configuration file to +make sure the plugins can access the YK-VAL ykval-config.php +configuration file: + +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/munin/plugin-conf.d/ykval' +[ykval_ksmlatency] +group www-data +[ykval_vallatency] +group www-data +[ykval_queuelength] +group www-data +user@val:~$ +---- + +Then check that they are working properly: + +[source, sh] +---- +user@val:~$ sudo /usr/sbin/munin-run --servicedir /usr/share/munin/plugins ykval_queuelength autoconf +yes +user@val:~$ sudo /usr/sbin/munin-run --servicedir /usr/share/munin/plugins ykval_queuelength config +graph_title YK-VAL queue size +graph_vlabel sync requests in queue +graph_category ykval +queuelength.label sync requests +queuelength.draw AREA +user@val:~$ sudo /usr/sbin/munin-run --servicedir /usr/share/munin/plugins ykval_queuelength +queuelength.value 0 +user@val:~$ +---- + +Enable the plugin as follows: + +[source, sh] +---- +user@val:~$ sudo munin-node-configure --shell | sudo sh +user@val:~$ sudo /etc/init.d/munin-node restart +Stopping Munin-Node: done. +Starting Munin-Node: done. +user@val:~$ +---- + +After some time, you should see new graphs on your Munin master. diff --git a/doc/RevocationService.adoc b/doc/Revocation_Service.adoc similarity index 54% rename from doc/RevocationService.adoc rename to doc/Revocation_Service.adoc index ada940f..8c68c63 100644 --- a/doc/RevocationService.adoc +++ b/doc/Revocation_Service.adoc @@ -9,40 +9,55 @@ not be secure unless you take additional pre-cautions. == Installation - user@val:~/yubikey-val$ sudo make revoke - user@val:~/yubikey-val$ +[source, sh] +---- +user@val:~/yubikey-val$ sudo make revoke +user@val:~/yubikey-val$ +---- == Configuration Add the following to your /etc/yubico/val/ykval-config.php: - # For the revoke service. - $baseParams['__YKREV_IPS__'] = array('10.0.0.1', '2000:1:2:3::4'); +[source, php] +---- +# For the revoke service. +$baseParams['__YKREV_IPS__'] = array('10.0.0.1', '2000:1:2:3::4'); +---- Obviously you need to modify the IP address. You also need to grant additional rights to the database, for MySQL: - user@val:~$ mysql --silent ykval - mysql> GRANT UPDATE(active) ON ykval.yubikeys to 'ykval_verifier'@'localhost'; \ - FLUSH PRIVILEGES; - mysql> \q - user@val:~$ +[source, sh] +---- +user@val:~$ mysql --silent ykval +mysql> GRANT UPDATE(active) ON ykval.yubikeys to 'ykval_verifier'@'localhost'; \ +FLUSH PRIVILEGES; +mysql> \q +user@val:~$ +---- For PostgreSQL this should already be working, through this command: - postgres@val:~$ psql ykval -q - ykval=# GRANT UPDATE ON yubikeys TO ykval_verifier; - ykval=# \q - postgres@val:~$ +[source, sh] +---- +postgres@val:~$ psql ykval -q +ykval=# GRANT UPDATE ON yubikeys TO ykval_verifier; +ykval=# \q +postgres@val:~$ +---- == Testing Test the installation like this: - - user@revoke:~$ wget -q -O - 'http://api.example.com/wsapi/revoke?yk=dteffujehknh&do=enable' - OK Processed dteffujehknh with enable - user@revoke:~$ + +[source, sh] +---- +user@revoke:~$ wget -q -O - 'http://api.example.com/wsapi/revoke?yk=dteffujehknh&do=enable' +OK Processed dteffujehknh with enable +user@revoke:~$ +---- Use 'disable' instead of 'enable' to test disabling of the YubiKey. diff --git a/doc/ServerReplicationProtocol.adoc b/doc/Server_Replication_Protocol.adoc similarity index 94% rename from doc/ServerReplicationProtocol.adoc rename to doc/Server_Replication_Protocol.adoc index 48ac4fb..3d6b841 100644 --- a/doc/ServerReplicationProtocol.adoc +++ b/doc/Server_Replication_Protocol.adoc @@ -1,4 +1,4 @@ -= Server Replication Protocol = +== Server Replication Protocol This document describes the server to server protocol. Its purpose is to synchronize the last used session and use counter between multiple @@ -16,7 +16,7 @@ protocol. The protocol described here is the server to server protocol. See ValidationServerAlgorithm for a description of the implementation algorithm that uses this protocol. -== Sync request specification == +=== Sync request specification A sync request is issued with a HTTP get call, like this: @@ -66,5 +66,5 @@ The values returned are: Output values for modified, yk_counter, yk_use, yk_high and yk_low are always positive except for -1 which indicates that the server did not -have any earlier information about the !YubiKey. In this case, nonce +have any earlier information about the YubiKey. In this case, nonce is a newly allocated random nonce. diff --git a/doc/SyncMonitor.adoc b/doc/Sync_Monitor.adoc similarity index 74% rename from doc/SyncMonitor.adoc rename to doc/Sync_Monitor.adoc index cd595e0..180c9f7 100644 --- a/doc/SyncMonitor.adoc +++ b/doc/Sync_Monitor.adoc @@ -1,4 +1,4 @@ -= YK-VAL Synchronization Monitor = +== YK-VAL Synchronization Monitor If you deploy multiple YK-VAL instances, it is important to monitor them to make sure the data they have is synchronized. While there are @@ -14,12 +14,15 @@ 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 monitor system such as Nagios. - user@val:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykval-checksum-clients' - #!/bin/sh - FILE=/var/www/checksum-clients.txt - (date --utc +%s; ykval-checksum-clients) > $FILE.tmp - mv $FILE.tmp $FILE - user@val:~$ sudo chmod +x /etc/cron.hourly/run-ykval-checksum-clients +[source, sh] +---- +user@val:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykval-checksum-clients' +#!/bin/sh +FILE=/var/www/checksum-clients.txt +(date --utc +%s; ykval-checksum-clients) > $FILE.tmp +mv $FILE.tmp $FILE +user@val:~$ sudo chmod +x /etc/cron.hourly/run-ykval-checksum-clients +---- If you notice mismatches, you may want to run ykval-checksum-clients with the '-v' parameter on the different hosts and then use 'diff -ur' diff --git a/doc/Troubleshooting.adoc b/doc/Troubleshooting.adoc index b979dd5..492469f 100644 --- a/doc/Troubleshooting.adoc +++ b/doc/Troubleshooting.adoc @@ -1,4 +1,4 @@ -= Troubleshooting = +== Troubleshooting First check if the web server is working. @@ -18,4 +18,5 @@ problem between PHP, curl and libpq. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411982 for more information. The workaround is simple: - user@val:~$ sudo mv /etc/php5/conf.d/curl.ini /etc/php5/conf.d/z_curl.ini +[source, sh] +user@val:~$ sudo mv /etc/php5/conf.d/curl.ini /etc/php5/conf.d/z_curl.ini diff --git a/doc/ValidationProtocolV20.adoc b/doc/Validation_Protocol_V2.0.adoc similarity index 96% rename from doc/ValidationProtocolV20.adoc rename to doc/Validation_Protocol_V2.0.adoc index 3fc4d1c..68bac4f 100644 --- a/doc/ValidationProtocolV20.adoc +++ b/doc/Validation_Protocol_V2.0.adoc @@ -1,7 +1,6 @@ -Validation Protocol Version 2.0 -=============================== +== Validation Protocol Version 2.0 -== Introduction +=== Introduction All requests are HTTP GET requests. As such, all parameters must be properly URL encoded. In particular, some base64 characters (such as @@ -12,7 +11,7 @@ response has not been tampered with, clients either verify the HMAC signature or use HTTPS connections (and verify the server certificate). -== Generating signatures +=== Generating signatures The protocol uses HMAC-SHA-1 signatures. The HMAC key to use is the client API key. @@ -29,7 +28,7 @@ signature do: * Base 64 encode the resulting value according to RFC 4648, for example, `t2ZMtKeValdA+H0jVpj3LIichn4=`. * Append the value under key 'h' to the message. -== Verifying signatures +=== Verifying signatures To verify a signature on a response message, follow the same procedure that was used to sign the response message and compare the signature @@ -47,7 +46,7 @@ make sure to remove h before verifying: Don't forget to sort the key/value pairs. -== Verification +=== Verification There is one call to verify YubiKey OTPs: verify. @@ -58,7 +57,7 @@ send the OTP. To avoid cut'n'paste attacks, the client MUST verify that the "otp" in the response is the same as the "otp" supplied in the request. -== Request +=== Request Construct an HTTP GET call to @@ -116,7 +115,7 @@ counters: http://api.yubico.com/wsapi/2.0/verify?id=87&otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad×tamp=1 -== Response +=== Response The verification response tells you whether the OTP is valid. The response has the following values: @@ -199,7 +198,7 @@ These are the possible "status" values in a verify response: | Server has seen the OTP/Nonce combination before |=== -== Changes since version 1.1 +=== Changes since version 1.1 The verify URL has changed. In the request, the new required field "nonce" were added, and the new optional fields "sl" and "timeout" are diff --git a/doc/ValidationServerAlgorithm.adoc b/doc/Validation_Server_Algorithm.adoc similarity index 92% rename from doc/ValidationServerAlgorithm.adoc rename to doc/Validation_Server_Algorithm.adoc index b9fd4ff..ea21306 100644 --- a/doc/ValidationServerAlgorithm.adoc +++ b/doc/Validation_Server_Algorithm.adoc @@ -1,13 +1,14 @@ -= Validation Server Algorithm = +== Validation Server Algorithm This document describes how a validation server should be implemented, and the required steps it needs to perform in order to be secure. -The client-to-server protocol is described in ValidationProtocolV20 -and the server-to-server protocol is described in -ServerReplicationProtocol. +The client-to-server protocol is described in +link:Validation_Protocol_V2.0.adoc[Validation Protocol V2.0] and the +server-to-server protocol is described in +lnk:Server_Replication_Protocol.adoc[Server Replication Protocol]. -== Normal validation with Sync == +=== Normal validation with Sync Val X receives an OTP verify request and needs to update the other validation servers on the last seen counter values. The procedure is @@ -35,20 +36,20 @@ Any remaining sync requests in the sync queue are from now on handled by a background daemon which re-sends them at regular intervals (described below). -=== Verification algorithm === +==== Verification algorithm .... - Input: - otp - the otp - nonce - the nonce from the request - yk:counter - the session counter - yk:use - the session use counter - yk:high - the high timestamp - yk:low - the low timestamp - modified - when the counters were last modified +Input: + otp - the otp + nonce - the nonce from the request + yk:counter - the session counter + yk:use - the session use counter + yk:high - the high timestamp + yk:low - the low timestamp + modified - when the counters were last modified - Output: - Error code. +Output: + Error code. .... Val X requires that SL % of the sent sync requests gives a response @@ -62,7 +63,7 @@ OTP is invalid, in order to consider the OTP to be valid. . (optional: if phishing test fails, return DELAYED_OTP) . return OK -=== Warning algorithm === +==== Warning algorithm Warn if any of these are true: @@ -80,7 +81,7 @@ Warn if any of these are true: * If received sync request have identical counters but different nonce (indicating that remote server received a request to validate an already validated OTP) -=== Update validation server that has been offline === +==== Update validation server that has been offline Val X has been out of function and its internal database needs to be updated. @@ -95,7 +96,7 @@ Responses which would have caused the sender of the sync request to consider the OTP as invalid will give raise to a warning on the sender validation server. -== Sync queue daemon == +=== Sync queue daemon There is one queue daemon that is responsible for sending all the queued requests. @@ -114,7 +115,7 @@ The sync queue will loop the following algorithm. ... The sync daemon updates the internal database to use the highest counter values: {{{UPDATE yubikeys SET counter = X, sessionUse = Y, high = P, low = Q, nonce = N, accessed = D WHERE publicName = ID AND ((counter < X) OR (counter = X AND sessionUse < Y))}}} ... The corresponding entry in the sync queue is removed. -== Logging matrix +=== Logging matrix Available parameters in comparisons are the following. @@ -127,7 +128,7 @@ Available parameters in comparisons are the following. |================ Parameters could be counters, modified, nonce. -== Non-queued Sync response logging == +=== Non-queued Sync response logging We compare reponse parameters against validation parameters since we are interested in if the server is in sync at the moment when the @@ -144,7 +145,7 @@ validation request arrives. | response.counter = otp.counters and response.nonce != otp.nonce | Warning | OTP marked as invalid | OTP is replayed. Sync response counters equal to OTP counters and nonce differs. |============= -== Sync request logging == +=== Sync request logging Both an original sync and a queued sync looks the same so we can not determine if the sync is original or queued. Therefore the logging is @@ -159,7 +160,7 @@ the same in both cases. | request.counters = local.counters and request.nonce != local.nonce | Warning | Remote server has received a request to validate an already validated OTP | |=================== -== Queued sync response logging == +=== Queued sync response logging What do we want to warn for here. Out of sync at time of OTP validation request or out of sync compared to current local counters? diff --git a/doc/YubiKeyInfoFormat.adoc b/doc/YubiKeyInfoFormat.adoc deleted file mode 100644 index 7784806..0000000 --- a/doc/YubiKeyInfoFormat.adoc +++ /dev/null @@ -1,42 +0,0 @@ -Format of YubiKey Info Data -=========================== - -This file holds data used in the YubiKey OTP validation phase. - -Each of the lines in the file follows the following format: - - active,created,modified,yk_publicname,yk_counter,yk_use,yk_low,yk_high,nonce,notes - -Any empty line, or a line beginning with a # is ignored. - -The meaning are as follows: - -.... - active - the YubiKey state, 1 if active, 0 if not - created - unix timestamp of when the YubiKey entry was created, decimal integer - modified - unix timestamp of when the YubiKey entry was last modified, decimal integer - yk_publicname - the public id of the YubiKey, modhex string - yk_counter - the YubiKey session counter, decimal integer - yk_use - the YubiKey use counter, decimal integer - yk_low - the low part of the YubiKey timestamp counter, decimal integer - yk_high - the high part of the YubiKey timestamp counter, decimal integer - nonce - the nonce used for the last validation request, ascii printable string - notes - not used, printable ascii string -.... - -An example of a valid data line: - - 1,1359470658,1359470658,cccccccccccb,2,1,32729,4,aoincuhfuahs - -For an example of importing and exporting YubiKey Info data, please see -link:ImportExportData.html[ImportExportData] diff --git a/doc/YubiKey_Info_Format.adoc b/doc/YubiKey_Info_Format.adoc new file mode 100644 index 0000000..f840d1a --- /dev/null +++ b/doc/YubiKey_Info_Format.adoc @@ -0,0 +1,48 @@ +== Format of YubiKey Info Data + +This file holds data used in the YubiKey OTP validation phase. + +Each of the lines in the file follows the following format: + + active,created,modified,yk_publicname,yk_counter,yk_use,yk_low,yk_high,nonce,notes + +Any empty line, or a line beginning with a # is ignored. + +The meaning are as follows: + +active:: + the YubiKey state, 1 if active, 0 if not + +created:: + unix timestamp of when the YubiKey entry was created, decimal integer + +modified:: + unix timestamp of when the YubiKey entry was last modified, decimal integer + +yk_publicname:: + the public id of the YubiKey, modhex string + +yk_counter:: + the YubiKey session counter, decimal integer + +yk_use:: + the YubiKey use counter, decimal integer + +yk_low:: + the low part of the YubiKey timestamp counter, decimal integer + +yk_high:: + the high part of the YubiKey timestamp counter, decimal integer + +nonce:: + the nonce used for the last validation request, ascii printable string + +notes:: + not used, printable ascii string + +An example of a valid data line: + + 1,1359470658,1359470658,cccccccccccb,2,1,32729,4,aoincuhfuahs + +For an example of importing and exporting YubiKey Info data, please see +link:Import_Export_Data.adoc[Import Export Data] diff --git a/doc/legacy/ValidationProtocolV10.adoc b/doc/legacy/Validation_Protocol_V1.0.adoc similarity index 100% rename from doc/legacy/ValidationProtocolV10.adoc rename to doc/legacy/Validation_Protocol_V1.0.adoc diff --git a/doc/legacy/ValidationProtocolV11.adoc b/doc/legacy/Validation_Protocol_V1.1.adoc similarity index 100% rename from doc/legacy/ValidationProtocolV11.adoc rename to doc/legacy/Validation_Protocol_V1.1.adoc