rooty/yubikey-val
1
0
Fork 0
mirror of https://github.com/Yubico/yubikey-val.git synced 2025-02-08 03:54:20 +01:00
Code Issues Projects Releases Wiki Activity

Improved asciidoc formatting

Browse Source
This commit is contained in:
Dain Nilsson 2014-10-29 15:08:12 +01:00
parent 0b53b4d27e
commit 823f4d6159
19 changed files with 664 additions and 569 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/ClientInfoFormat.adoc → doc/Client_Info_Format.adoc
View File

@ -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. 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: The meaning are as follows:
* id: id::
the client identity, decimal integer the client identity, decimal integer
* active active::
the client state, 1 if active, 0 if not the client state, 1 if active, 0 if not
* created created::
unix timestamp of when the client was created, decimal integer unix timestamp of when the client was created, decimal integer
* secret secret::
printable ascii string with shared HMAC secret for client id printable ascii string with shared HMAC secret for client id
* email email::
the email address used by the client, printable ascii string the email address used by the client, printable ascii string
* notes notes::
not used, printable ascii string not used, printable ascii string
* otp otp::
the YubiKey OTP used to create the client, modhex string the YubiKey OTP used to create the client, modhex string
An examples of a valid data line: An examples of a valid data line:

67
doc/GeneratingClients.adoc → doc/Generating_Clients.adoc
View File

@ -1,4 +1,4 @@
= Generating Clients = == Generating Clients
For a client to be able to authenticate a YubiKey OTP with the Validation 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 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 database with a new generated secret, the ykval-gen-clients command can be
used. This document describes step by step instructions on generating and used. This document describes step by step instructions on generating and
using clients. For more information regarding the various fields of the 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 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 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 as root (using sudo), since it needs to be able to read the database
configuration stored in /etc/yubico/val/config-db.php. configuration stored in /etc/yubico/val/config-db.php.
.... [source, sh]
user@val:~$ sudo ykval-gen-clients --urandom 5 ----
user@val:~$ sudo ykval-gen-clients --urandom 5
1,l+/c/XfDPDHsaNKrpjwL+bf/Hgs= 1,l+/c/XfDPDHsaNKrpjwL+bf/Hgs=
2,LPGHqukoIAUGgDuOs7O0e1f8xD0= 2,LPGHqukoIAUGgDuOs7O0e1f8xD0=
3,K+gWRE0euOjVOiLD4Nm0wyHrHY8= 3,K+gWRE0euOjVOiLD4Nm0wyHrHY8=
4,+8LF+ADANTAHnwB82xkBb+mNEFs= 4,+8LF+ADANTAHnwB82xkBb+mNEFs=
5,URc6oabcuRV8OWW1Hs1cYym3ba4= 5,URc6oabcuRV8OWW1Hs1cYym3ba4=
user@val:~$ user@val:~$
.... ----
== Testing the clients == === Testing the clients
The above clients can now be used with the validation server. If you have 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, a YubiKey validation client, you can easily test this now. For example,
using the ykclient command (available in the ykclient-dev package, which is using the ykclient command (available in the ykclient-dev package, which is
in Debian as well as Ubuntu): in Debian as well as Ubuntu):
.... [source, sh]
user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey LPGHqukoIAUGgDuOs7O0e1f8xD0= 2 cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv ----
Input: user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey LPGHqukoIAUGgDuOs7O0e1f8xD0= 2 cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv
validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s Input:
client id: 2 validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s
token: cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv client id: 2
api key: LPGHqukoIAUGgDuOs7O0e1f8xD0= token: cccccccccccdutfiljtbignbgckhgdtfigbdricugdrv
Verification output (1): Yubikey OTP was bad (BAD_OTP) api key: LPGHqukoIAUGgDuOs7O0e1f8xD0=
user@val:~$ 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 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: a bad OTP), the verification worked as expected. Compare it to the next example:
.... [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 user@val:~$ ykclient --url "http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s" --apikey not_a_real_secret 3 cccccccccccdutfiljtbignggckhgdtfigbdricugdrvInput:
client id: 3 validation URL: http://127.0.0.1/wsapi/2.0/verify?id=%d&otp=%s
token: cccccccccccdutfiljtbignggckhgdtfigbdricugdrv client id: 3
api key: not_a_real_secret token: cccccccccccdutfiljtbignggckhgdtfigbdricugdrv
Verification output (106): Server response signature was invalid (BAD_SERVER_SIGNATURE) api key: not_a_real_secret
user@val:~$ 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 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 incorrect, and responded as it should. The response is signed with the correct

30
doc/GettingStartedWritingClients.adoc → doc/Getting_Started_Writing_Clients.adoc
View File

@ -1,18 +1,18 @@
Getting Started Writing Clients == Getting Started Writing Clients
===============================
== Introduction === Introduction
While the canonical description of the validation protocol is While the canonical description of the validation protocol is
documented in link:ValidationProtocolV20.adoc[ValidationProtocolV20], it may be difficult to grasp the documented in link:Validation_Protocol_V2.0.adoc[Validation Protocol V2.0],
high level of how a client typically works. The intention with this it may be difficult to grasp the high level of how a client typically
page is to illustrate one simple case. Note that this does not cover works. The intention with this page is to illustrate one simple case.
the replicated protocol.
NOTE: This does not cover the replicated protocol.
If you want to make your own client implementation, here is the If you want to make your own client implementation, here is the
quickest way to get started: quickest way to get started:
== API key === API key
API key is used to optionally sign the OTP validation request and to API key is used to optionally sign the OTP validation request and to
verify the OTP validation response. We recommend all production 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 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. 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 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 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 vvvvvvcurikvhjcvnlnbecbkubjvuittbifhndhn
== Validate OTP format === Validate OTP format
Prudent clients should validate the data entered by the user so that Prudent clients should validate the data entered by the user so that
it is what the software expects. YubiKey OTPs consists of 32-48 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 that clients only check that the input consists of 32-48 printable
characters. characters.
== Send OTP to our server === Send OTP to our server
Send the authentication request to our servers following the protocol Send the authentication request to our servers following the protocol
specified below. Your request should include the verifier ID (a number 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. 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 You will recieve a response back from the server, a string of text
that resembles the following: 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 OTP and nonce was the same as the one you requested validation for and
verify the HMAC-SHA-1 signature. verify the HMAC-SHA-1 signature.
== Make a decision === Make a decision
Use the `status=` codes to make a decision whether to authenticate Use the `status=` codes to make a decision whether to authenticate
your user or not. All the status codes and their meanings are your user or not. All the status codes and their meanings are
described by the protocol specification, see below. 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 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 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 Typically you would store the association between the user and the
YubiKey prefix in a database. YubiKey prefix in a database.
== The End === The End
There are some more subtle matters that can be important, so please There are some more subtle matters that can be important, so please
read the entire protocol specification for all the details. Further, read the entire protocol specification for all the details. Further,

81
doc/ImportExportData.adoc
View File

@ -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:~$
....

81
doc/Import_Export_Data.adoc Normal file
View File

@ -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:~$
....

583
doc/Installation.adoc
View File

@ -1,4 +1,4 @@
== Introduction == == Introduction
This document describes how to get one instance of the Yubikey This document describes how to get one instance of the Yubikey
Validation Server (YK-VAL) up and running. 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 (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. 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"
https://developers.yubico.com/yubikey-ksm/[YK-KSM]
Otherwise we recommend the "soft" YK-KSM:
https://github.com/Yubico/yubikey-ksm/
The YK-KSM can be on the same machine as the validation server, but 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 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. The OTP validation service is delivered through web service API.
There's no web-based HTML form interface involved. The protocol is There's no web-based HTML form interface involved. The protocol is
defined at: defined at: http://www.yubico.com/developers/api/
http://www.yubico.com/developers/api/
For redundancy it is possible to set up multiple instances of the For redundancy it is possible to set up multiple instances of the
YubiKey Validation Server. The intent is that clients should be able 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 we strongly recommend you to list non-local servers in each sync pool
though. though.
== Installation == == Installation
This following steps applies to any GNU/Linux-like system, although it 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, 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 Install the OS following its manual and enable automatic security
upgrades if prompted. upgrades if prompted.
=== Step 1: YK-VAL Installation === === Step 1: YK-VAL Installation
First you should download and install the latest YK-VAL release: First you should download and install the latest YK-VAL release:
.... [source, sh]
user@val:~$ sudo apt-get install git make ----
... user@val:~$ sudo apt-get install git make
user@val:~$ git clone git://github.com/Yubico/yubikey-val.git ...
... user@val:~$ git clone git://developers.yubico.com/yubikey-val.git
user@val:~$ cd yubikey-val ...
user@val:~/yubikey-val$ sudo make install user@val:~$ cd yubikey-val
.... user@val:~/yubikey-val$ sudo make install
----
The rest of this documentation will assume you have YK-VAL available The rest of this documentation will assume you have YK-VAL available
in the default installation targets. You can override the paths, see in the default installation targets. You can override the paths, see
the Makefile. 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. 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. 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 Any SQL database with PHP support should work. We give examples for
MySQL and PostgreSQL here. Note that you need to chose between either MySQL and PostgreSQL here. Note that you need to chose between either
PostgreSQL or MySQL here. PostgreSQL or MySQL here.
==== Step 3A: MySQL Installation ==== ==== Step 3A: MySQL Installation
Install the required packages: 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 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 to specify one. To avoid having to specify a password when using the
'mysql' tool interactively, you can store the password in ~/.my.cnf, 'mysql' tool interactively, you can store the password in ~/.my.cnf,
see /usr/share/doc/mysql-server-5.0/README.Debian.gz. For example: see /usr/share/doc/mysql-server-5.0/README.Debian.gz. For example:
user@val:~$ cat > .my.cnf [source, sh]
[client] ----
user = root user@val:~$ cat > .my.cnf
password = YOURPASSWORD [client]
user@val:~$ chmod go-r .my.cnf user = root
user@val:~$ password = YOURPASSWORD
user@val:~$ chmod go-r .my.cnf
user@val:~$
----
Note the 'chmod' to protect your password from non-root users. Note the 'chmod' to protect your password from non-root users.
The database needs to be initialized as follows: The database needs to be initialized as follows:
user@val:~$ echo 'create database ykval' | mysql [source, sh]
user@val:~$ mysql ykval < /usr/share/doc/yubikey-val/ykval-db.sql ----
user@val:~$ 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, You also need to create a database user for the verifier interface,
normally called 'ykval_verifier': normally called 'ykval_verifier':
user@val:~$ mysql --silent ykval [source, sh]
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'; \ user@val:~$ mysql --silent ykval
GRANT SELECT(id, secret, active) ON ykval.clients TO 'ykval_verifier'@'localhost'; \ mysql> CREATE USER 'ykval_verifier'@'localhost'; \
GRANT SELECT,INSERT,UPDATE,DELETE ON ykval.queue TO 'ykval_verifier'@'localhost'; \ GRANT SELECT,INSERT,UPDATE(modified, yk_counter, yk_low, yk_high, yk_use, nonce) ON ykval.yubikeys TO 'ykval_verifier'@'localhost'; \
SET PASSWORD FOR 'ykval_verifier'@'localhost' = PASSWORD('yourpassword'); \ GRANT SELECT(id, secret, active) ON ykval.clients TO 'ykval_verifier'@'localhost'; \
FLUSH PRIVILEGES; GRANT SELECT,INSERT,UPDATE,DELETE ON ykval.queue TO 'ykval_verifier'@'localhost'; \
mysql> \q SET PASSWORD FOR 'ykval_verifier'@'localhost' = PASSWORD('yourpassword'); \
user@val:~$ FLUSH PRIVILEGES;
mysql> \q
user@val:~$
----
==== Step 3B: PostgreSQL Installation ==== ==== Step 3B: PostgreSQL Installation
Install the required packages: Install the required packages:
user@val:~$ sudo apt-get install postgresql php5-pgsql [source, sh]
... ----
user@val:~$ user@val:~$ sudo apt-get install postgresql php5-pgsql
...
user@val:~$
----
The database needs to be initialized as follows: The database needs to be initialized as follows:
user@val:~$ sudo su postgres [source, sh]
postgres@val:~$ createdb ykval ----
postgres@val:~$ psql ykval < /usr/share/doc/yubikey-val/ykval-db.sql user@val:~$ sudo su postgres
postgres@val:~$ 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, You also need to create a database user for the verifier interface,
normally called 'ykval_verifier': normally called 'ykval_verifier':
postgres@val:~$ psql ykval -q [source, sh]
ykval=# CREATE USER ykval_verifier PASSWORD 'yourpassword'; ----
ykval=# GRANT SELECT,INSERT,UPDATE ON yubikeys TO ykval_verifier; postgres@val:~$ psql ykval -q
ykval=# GRANT SELECT ON clients TO ykval_verifier; ykval=# CREATE USER ykval_verifier PASSWORD 'yourpassword';
ykval=# GRANT SELECT, INSERT, UPDATE, DELETE ON queue TO ykval_verifier; ykval=# GRANT SELECT,INSERT,UPDATE ON yubikeys TO ykval_verifier;
ykval=# \q ykval=# GRANT SELECT ON clients TO ykval_verifier;
postgres@val:~$ 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 Don't forget to switch back to your normal user
postgres@val:~$ exit [source, sh]
user@val:~$ ----
postgres@val:~$ exit
user@val:~$
----
During installation and debugging it may be useful to watch the During installation and debugging it may be useful to watch the
database log entries: 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 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 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. the symlinks is to invoke 'make symlink' in your YK-VAL source tree.
Like this: Like this:
user@val:~/yubikey-val$ sudo make symlink [source, sh]
install -d /var/www/wsapi/2.0 ----
ln -sf /usr/share/yubikey-val/ykval-verify.php /var/www/wsapi/2.0/verify.php user@val:~/yubikey-val$ sudo make symlink
ln -sf /usr/share/yubikey-val/ykval-sync.php /var/www/wsapi/2.0/sync.php install -d /var/www/wsapi/2.0
user@val:~/yubikey-val$ 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 If you want to do it manually, you can invoke the above commands
manually. manually.
=== Step 5: Include path configuration === === Step 5: Include path configuration
Set the include path for the queue daemon by creating a file Set the include path for the queue daemon by creating a file
/etc/default/ykval-queue with the following content: /etc/default/ykval-queue with the following content:
user@val:~$ sudo sh -c 'cat > /etc/default/ykval-queue' [source, sh]
DAEMON_ARGS="/etc/yubico/val:/usr/share/yubikey-val" ----
user@val:~$ 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 You also need to set the include path for the PHP scripts running via
Apache, using a .htaccess file: Apache, using a .htaccess file:
user@val:~$ sudo sh -c 'cat > /var/www/wsapi/2.0/.htaccess' [source, sh]
RewriteEngine on ----
RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L] user@val:~$ sudo sh -c 'cat > /var/www/wsapi/2.0/.htaccess'
<IfModule mod_php5.c> RewriteEngine on
RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L]
<IfModule mod_php5.c>
php_value include_path ".:/etc/yubico/val:/usr/share/yubikey-val" php_value include_path ".:/etc/yubico/val:/usr/share/yubikey-val"
</IfModule> </IfModule>
user@val:~$ sudo ln -s 2.0/.htaccess /var/www/wsapi/.htaccess user@val:~$ sudo ln -s 2.0/.htaccess /var/www/wsapi/.htaccess
user@val:~$ user@val:~$
----
The .htaccess file also sets up rewriting from the non-.PHP suffix URL The .htaccess file also sets up rewriting from the non-.PHP suffix URL
name to the right script. 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 The paths are the default, if you installed the YK-VAL in some other
place you need to modify the paths. 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 You also need to create a ykval-config.php script. An example file is
included in YK-VAL package as ykval-config.php included in YK-VAL package as ykval-config.php
A template is typically installed in /etc/yubico/val/ykval-config.php-template. 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 [source, sh]
user@val:~$ sudo emacs -nw /etc/yubico/val/ykval-config.php ----
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 Be careful about the user permissions and ownership so that unrelated
users on the system cannot read the database password. users on the system cannot read the database password.
You will typically need to modify the DSN (__YKVAL_DB_DSN__), database You will typically need to modify the DSN ('__YKVAL_DB_DSN__'), database
passwords (__YKVAL_DB_PW__), the sync pool lists (__YKVAL_SYNC_POOL__ passwords (__YKVAL_DB_PW__), the sync pool lists ('__YKVAL_SYNC_POOL__'
and __YKVAL_ALLOWED_SYNC_POOL__), and the YK-KSM URLs inside the and '__YKVAL_ALLOWED_SYNC_POOL__'), and the YK-KSM URLs inside the
otp2ksmurls function. otp2ksmurls function.
An example DSN for a MySQL setup: 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: 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: 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' [source, sh]
1.2.3.4 api1.example.com ----
2.3.4.5 api2.example.com user@val:~$ sudo sh -c 'cat >> /etc/hosts'
user@val:~$ 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: 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 Create an apache web configuration file for the normal HTTP interface
like this: like this:
.... [source, sh]
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval' ----
<VirtualHost *:80> user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval'
ServerName api.example.com <VirtualHost *:80>
ServerAdmin support@example.com ServerName api.example.com
ServerAdmin support@example.com
DocumentRoot /var/www/ DocumentRoot /var/www/
<Directory /> <Directory />
Options FollowSymLinks Options FollowSymLinks
AllowOverride None AllowOverride None
</Directory> </Directory>
<Directory /var/www/> <Directory /var/www/>
Options FollowSymLinks Options FollowSymLinks
AllowOverride All AllowOverride All
Order allow,deny Order allow,deny
allow from all allow from all
</Directory> </Directory>
ErrorLog /var/log/apache2/ykval-error.log ErrorLog /var/log/apache2/ykval-error.log
LogLevel warn LogLevel warn
CustomLog /var/log/apache2/ykval-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" CustomLog /var/log/apache2/ykval-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\""
ServerSignature On ServerSignature On
</VirtualHost> </VirtualHost>
user@val:~$ user@val:~$
.... ----
HTTPS is strictly speaking not required, but we strongly recommend it. 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 from
http://permalink.gmane.org/gmane.comp.encryption.gpg.gnutls.devel/4062. 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: First install and enable the mod_gnutls module:
user@val:~$ sudo apt-get install libapache2-mod-gnutls [source, sh]
user@val:~$ sudo a2enmod gnutls ----
Enabling module gnutls. user@val:~$ sudo apt-get install libapache2-mod-gnutls
Run '/etc/init.d/apache2 restart' to activate new configuration! user@val:~$ sudo a2enmod gnutls
user@val:~$ Enabling module gnutls.
Run '/etc/init.d/apache2 restart' to activate new configuration!
user@val:~$
----
You will need to place the private key in 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-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: Create Apache web configuration files:
.... [source, sh]
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl' ----
Listen 443 user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl'
<VirtualHost *:443> Listen 443
ServerName api.example.com <VirtualHost *:443>
ServerAdmin support@example.com ServerName api.example.com
ServerAdmin support@example.com
GnuTLSEnable on GnuTLSEnable on
GnuTLSCertificateFile /etc/ssl/private/api.example.com-chain.pem GnuTLSCertificateFile /etc/ssl/private/api.example.com-chain.pem
GnuTLSKeyFile /etc/ssl/private/api.example.com-key.pem GnuTLSKeyFile /etc/ssl/private/api.example.com-key.pem
GnuTLSPriorities NORMAL GnuTLSPriorities NORMAL
DocumentRoot /var/www/ DocumentRoot /var/www/
<Directory /> <Directory />
Options FollowSymLinks Options FollowSymLinks
AllowOverride None AllowOverride None
</Directory> </Directory>
<Directory /var/www/> <Directory /var/www/>
Options FollowSymLinks Options FollowSymLinks
AllowOverride All AllowOverride All
Order allow,deny Order allow,deny
allow from all allow from all
</Directory> </Directory>
ErrorLog /var/log/apache2/ykval-ssl-error.log ErrorLog /var/log/apache2/ykval-ssl-error.log
LogLevel warn LogLevel warn
CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\""
ServerSignature On ServerSignature On
</VirtualHost> </VirtualHost>
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 The mod_ssl module is typically installed by default, but you need to
enable it. enable it.
user@val:~$ sudo a2enmod ssl [source, sh]
Enabling module ssl. ----
Run '/etc/init.d/apache2 restart' to activate new configuration! user@val:~$ sudo a2enmod ssl
user@val:~$ Enabling module ssl.
Run '/etc/init.d/apache2 restart' to activate new configuration!
user@val:~$
----
You will need to place the private key in 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-key.pem and the certificate chain in
/etc/ssl/private/api.example.com-chain.pem. /etc/ssl/private/api.example.com-chain.pem.
.... [source, sh]
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl' ----
<VirtualHost *:443> user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl'
ServerName api.example.com <VirtualHost *:443>
ServerAdmin support@example.com ServerName api.example.com
ServerAdmin support@example.com
SSLEngine on SSLEngine on
SSLCertificateFile /etc/ssl/private/api.example.com-chain.pem SSLCertificateFile /etc/ssl/private/api.example.com-chain.pem
SSLCertificateChainFile /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 SSLCertificateKeyFile /etc/ssl/private/api.example.com-key.pem
DocumentRoot /var/www/ DocumentRoot /var/www/
<Directory /> <Directory />
Options FollowSymLinks Options FollowSymLinks
AllowOverride None AllowOverride None
</Directory> </Directory>
<Directory /var/www/> <Directory /var/www/>
Options FollowSymLinks Options FollowSymLinks
AllowOverride All AllowOverride All
Order allow,deny Order allow,deny
allow from all allow from all
</Directory> </Directory>
ErrorLog /var/log/apache2/ykval-ssl-error.log ErrorLog /var/log/apache2/ykval-ssl-error.log
LogLevel warn LogLevel warn
CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" CustomLog /var/log/apache2/ykval-ssl-access.log "%h %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\""
ServerSignature On ServerSignature On
</VirtualHost> </VirtualHost>
user@val:~$ user@val:~$
.... ----
==== Common Apache Configuration ==== ==== Common Apache Configuration
This step is the same for both mod_gnutls and mod_ssl. This step is the same for both mod_gnutls and mod_ssl.
user@val:~$ sudo a2enmod rewrite [source, sh]
Enabling module rewrite. ----
Run '/etc/init.d/apache2 restart' to activate new configuration! user@val:~$ sudo a2enmod rewrite
user@val:~$ sudo a2dissite default Enabling module rewrite.
Site default disabled. Run '/etc/init.d/apache2 restart' to activate new configuration!
Run '/etc/init.d/apache2 reload' to activate new configuration! user@val:~$ sudo a2dissite default
user@val:~$ sudo a2ensite ykval ykval-ssl Site default disabled.
Enabling site ykval. Run '/etc/init.d/apache2 reload' to activate new configuration!
Enabling site ykval-ssl. user@val:~$ sudo a2ensite ykval ykval-ssl
Run '/etc/init.d/apache2 reload' to activate new configuration! Enabling site ykval.
user@val:~$ sudo /etc/init.d/apache2 restart Enabling site ykval-ssl.
user@val:~$ 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 The PHP interface uses syslog for logging of incoming requests. The
facility is LOG_LOCAL0. To place these messages in a separate file, 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, 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: create a file /etc/rsyslog.d/ykval.conf with this content:
user@val:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykval.conf' [source, sh]
local0.* -/var/log/ykval.log ----
user@val:~$ sudo /etc/init.d/rsyslog restart user@val:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykval.conf'
... local0.* -/var/log/ykval.log
user@val:~$ user@val:~$ sudo /etc/init.d/rsyslog restart
...
user@val:~$
----
The '-' before the filename avoids syncing the file after each write, The '-' before the filename avoids syncing the file after each write,
which is recommended for performance. 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 rotation of log files. Here is an example that rotates the log file
weekly. Create a file /etc/logrotate.d/ykval like this: weekly. Create a file /etc/logrotate.d/ykval like this:
user@val:~$ sudo sh -c 'cat > /etc/logrotate.d/ykval' [source, sh]
/var/log/ykval.log { ----
weekly user@val:~$ sudo sh -c 'cat > /etc/logrotate.d/ykval'
/var/log/ykval.log {
weekly
dateext dateext
compress compress
missingok missingok
rotate 9999 rotate 9999
notifempty notifempty
postrotate postrotate
invoke-rc.d rsyslog reload > /dev/null invoke-rc.d rsyslog reload > /dev/null
endscript endscript
} }
user@val:~$ user@val:~$
----
You may want to modify the default /etc/logrotate.d/apache2, useful You may want to modify the default /etc/logrotate.d/apache2, useful
things to add are 'dateext' and 'compress' and change 'rotate' to things to add are 'dateext' and 'compress' and change 'rotate' to
something large if you want to retain logs. 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 Unfortunately, most default syslog configuration, including the
syslog.conf configuration file on Debian, will also log all entries to 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 modify the default rules. For example, edit the following lines of
/etc/rsyslog.conf (or /etc/syslog.conf if you don't use rsyslog): /etc/rsyslog.conf (or /etc/syslog.conf if you don't use rsyslog):
.... [source, conf]
*.=debug;\ ----
auth,authpriv.none;\ *.=debug;\
news.none;mail.none -/var/log/debug auth,authpriv.none;\
*.*;auth,authpriv.none -/var/log/syslog news.none;mail.none -/var/log/debug
*.=info;*.=notice;*.=warn;\ *.*;auth,authpriv.none -/var/log/syslog
auth,authpriv.none;\ *.=info;*.=notice;*.=warn;\
cron,daemon.none;\ auth,authpriv.none;\
mail,news.none -/var/log/messages cron,daemon.none;\
.... mail,news.none -/var/log/messages
----
Change them into: Change them into:
.... [source, conf]
*.=debug;\ ----
auth,authpriv.none;\ *.=debug;\
news.none;mail.none;local0.none -/var/log/debug auth,authpriv.none;\
*.*;auth,authpriv.none,local0.none -/var/log/syslog news.none;mail.none;local0.none -/var/log/debug
*.=info;*.=notice;*.=warn;\ *.*;auth,authpriv.none,local0.none -/var/log/syslog
auth,authpriv.none;\ *.=info;*.=notice;*.=warn;\
cron,daemon.none;\ auth,authpriv.none;\
local0.none;\ cron,daemon.none;\
mail,news.none -/var/log/messages local0.none;\
.... mail,news.none -/var/log/messages
----
Idempotent commands to speed this up: Idempotent commands to speed this up:
user@host:~$ sudo perl -pi -e 's/;auth,authpriv.none/;auth,local0.none,authpriv.none/' /etc/rsyslog.conf [source, sh]
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 perl -pi -e 's/;auth,authpriv.none/;auth,local0.none,authpriv.none/' /etc/rsyslog.conf
user@host:~$ sudo /etc/init.d/rsyslog restart 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 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 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 the pool. The easiest way of running this is to simply invoke ykval-queue
in a shell: 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 However, the recommended approach is to automate running this process in
the background, by use of an init script or similar. Instructions on doing the background, by use of an init script or similar. Instructions on doing
so vary depending on your operating system. 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 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 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 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 /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 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 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 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 Once these permissions have been configured, you can initiate the full sync
by running the following command from the new server: by running the following command from the new server:
user@val:~$ ykval-synchronize http://<IP or hostname of existing server>/wsapi/2.0/resync all [source, sh]
user@val:~$ ykval-synchronize http://<IP or hostname of existing server>/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 You can test the service by requesting a URL. Using wget, for example:
example:
.... [source, sh]
user@val:~$ wget -q -O - 'http://localhost/wsapi/2.0/verify?id=1&nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak&otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh' ----
h=/QVWkl5VlcX+Or1A2b3vOeoLEwI= user@val:~$ wget -q -O - 'http://localhost/wsapi/2.0/verify?id=1&nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak&otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh'
t=2010-05-17T14:48:15Z0355 h=/QVWkl5VlcX+Or1A2b3vOeoLEwI=
otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh t=2010-05-17T14:48:15Z0355
nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh
status=NO_SUCH_CLIENT nonce=asdmalksdmlkasmdlkasmdlakmsdaasklmdlak
status=NO_SUCH_CLIENT
user@val:~$ user@val:~$
.... ----
Naturally, you will need to import client keys into the database for Naturally, you will need to import client keys into the database for
the verify function to work properly. the verify function to work properly.
=== The End === === The End
You now have a YK-VAL up and running. See 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. improve security of your system.

9
doc/MakeRelease.adoc → doc/Make_Release.adoc
View File

@ -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 The point of this document is to describe all steps required to make a
proper release of the yubikey-personalization project. proper release of the yubikey-personalization project.
== Dependencies === Dependencies
Making a release requires the following packages: 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 sudo apt-get install make git gnupg git2cl
== Details === Details
* Make sure the doc/ sub-directory uses the latest revision. Confirm with: * Make sure the doc/ sub-directory uses the latest revision. Confirm with:
cd doc && git checkout master && git pull && git diff cd doc && git checkout master && git pull && git diff

57
doc/MuninProbes.adoc
View File

@ -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.

68
doc/Munin_Probes.adoc Normal file
View File

@ -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.

47
doc/RevocationService.adoc → doc/Revocation_Service.adoc
View File

@ -9,40 +9,55 @@ not be secure unless you take additional pre-cautions.
== Installation == Installation
user@val:~/yubikey-val$ sudo make revoke [source, sh]
user@val:~/yubikey-val$ ----
user@val:~/yubikey-val$ sudo make revoke
user@val:~/yubikey-val$
----
== Configuration == Configuration
Add the following to your /etc/yubico/val/ykval-config.php: Add the following to your /etc/yubico/val/ykval-config.php:
# For the revoke service. [source, php]
$baseParams['__YKREV_IPS__'] = array('10.0.0.1', '2000:1:2:3::4'); ----
# 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. Obviously you need to modify the IP address.
You also need to grant additional rights to the database, for MySQL: You also need to grant additional rights to the database, for MySQL:
user@val:~$ mysql --silent ykval [source, sh]
mysql> GRANT UPDATE(active) ON ykval.yubikeys to 'ykval_verifier'@'localhost'; \ ----
FLUSH PRIVILEGES; user@val:~$ mysql --silent ykval
mysql> \q mysql> GRANT UPDATE(active) ON ykval.yubikeys to 'ykval_verifier'@'localhost'; \
user@val:~$ FLUSH PRIVILEGES;
mysql> \q
user@val:~$
----
For PostgreSQL this should already be working, through this command: For PostgreSQL this should already be working, through this command:
postgres@val:~$ psql ykval -q [source, sh]
ykval=# GRANT UPDATE ON yubikeys TO ykval_verifier; ----
ykval=# \q postgres@val:~$ psql ykval -q
postgres@val:~$ ykval=# GRANT UPDATE ON yubikeys TO ykval_verifier;
ykval=# \q
postgres@val:~$
----
== Testing == Testing
Test the installation like this: Test the installation like this:
user@revoke:~$ wget -q -O - 'http://api.example.com/wsapi/revoke?yk=dteffujehknh&do=enable' [source, sh]
OK Processed dteffujehknh with enable ----
user@revoke:~$ 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. Use 'disable' instead of 'enable' to test disabling of the YubiKey.

6
doc/ServerReplicationProtocol.adoc → doc/Server_Replication_Protocol.adoc
View File

@ -1,4 +1,4 @@
= Server Replication Protocol = == Server Replication Protocol
This document describes the server to server protocol. Its purpose is This document describes the server to server protocol. Its purpose is
to synchronize the last used session and use counter between multiple 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 protocol. See ValidationServerAlgorithm for a description of the
implementation algorithm that uses this protocol. implementation algorithm that uses this protocol.
== Sync request specification == === Sync request specification
A sync request is issued with a HTTP get call, like this: 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 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 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. is a newly allocated random nonce.

17
doc/SyncMonitor.adoc → doc/Sync_Monitor.adoc
View File

@ -1,4 +1,4 @@
= YK-VAL Synchronization Monitor = == YK-VAL Synchronization Monitor
If you deploy multiple YK-VAL instances, it is important to 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 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 job and output the hash to a file that can be downloaded by a remote
monitor system such as Nagios. monitor system such as Nagios.
user@val:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykval-checksum-clients' [source, sh]
#!/bin/sh ----
FILE=/var/www/checksum-clients.txt user@val:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykval-checksum-clients'
(date --utc +%s; ykval-checksum-clients) > $FILE.tmp #!/bin/sh
mv $FILE.tmp $FILE FILE=/var/www/checksum-clients.txt
user@val:~$ sudo chmod +x /etc/cron.hourly/run-ykval-checksum-clients (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 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' with the '-v' parameter on the different hosts and then use 'diff -ur'

5
doc/Troubleshooting.adoc
View File

@ -1,4 +1,4 @@
= Troubleshooting = == Troubleshooting
First check if the web server is working. 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 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411982 for more
information. The workaround is simple: 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

17
doc/ValidationProtocolV20.adoc → doc/Validation_Protocol_V2.0.adoc
View File

@ -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 All requests are HTTP GET requests. As such, all parameters must be
properly URL encoded. In particular, some base64 characters (such as 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 signature or use HTTPS connections (and verify the server
certificate). certificate).
== Generating signatures === Generating signatures
The protocol uses HMAC-SHA-1 signatures. The HMAC key to use is the The protocol uses HMAC-SHA-1 signatures. The HMAC key to use is the
client API key. client API key.
@ -29,7 +28,7 @@ signature do:
* Base 64 encode the resulting value according to RFC 4648, for example, `t2ZMtKeValdA+H0jVpj3LIichn4=`. * Base 64 encode the resulting value according to RFC 4648, for example, `t2ZMtKeValdA+H0jVpj3LIichn4=`.
* Append the value under key 'h' to the message. * 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 To verify a signature on a response message, follow the same procedure
that was used to sign the response message and compare the signature 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. Don't forget to sort the key/value pairs.
== Verification === Verification
There is one call to verify YubiKey OTPs: verify. 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 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. the response is the same as the "otp" supplied in the request.
== Request === Request
Construct an HTTP GET call to 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&timestamp=1 http://api.yubico.com/wsapi/2.0/verify?id=87&otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad&timestamp=1
== Response === Response
The verification response tells you whether the OTP is valid. The The verification response tells you whether the OTP is valid. The
response has the following values: 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 | 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 The verify URL has changed. In the request, the new required field
"nonce" were added, and the new optional fields "sl" and "timeout" are "nonce" were added, and the new optional fields "sl" and "timeout" are

47
doc/ValidationServerAlgorithm.adoc → doc/Validation_Server_Algorithm.adoc
View File

@ -1,13 +1,14 @@
= Validation Server Algorithm = == Validation Server Algorithm
This document describes how a validation server should be implemented, This document describes how a validation server should be implemented,
and the required steps it needs to perform in order to be secure. and the required steps it needs to perform in order to be secure.
The client-to-server protocol is described in ValidationProtocolV20 The client-to-server protocol is described in
and the server-to-server protocol is described in link:Validation_Protocol_V2.0.adoc[Validation Protocol V2.0] and the
ServerReplicationProtocol. 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 Val X receives an OTP verify request and needs to update the other
validation servers on the last seen counter values. The procedure is 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 by a background daemon which re-sends them at regular intervals
(described below). (described below).
=== Verification algorithm === ==== Verification algorithm
.... ....
Input: Input:
otp - the otp otp - the otp
nonce - the nonce from the request nonce - the nonce from the request
yk:counter - the session counter yk:counter - the session counter
yk:use - the session use counter yk:use - the session use counter
yk:high - the high timestamp yk:high - the high timestamp
yk:low - the low timestamp yk:low - the low timestamp
modified - when the counters were last modified modified - when the counters were last modified
Output: Output:
Error code. Error code.
.... ....
Val X requires that SL % of the sent sync requests gives a response 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) . (optional: if phishing test fails, return DELAYED_OTP)
. return OK . return OK
=== Warning algorithm === ==== Warning algorithm
Warn if any of these are true: 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) * 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 Val X has been out of function and its internal database needs to be
updated. 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 consider the OTP as invalid will give raise to a warning on the sender
validation server. validation server.
== Sync queue daemon == === Sync queue daemon
There is one queue daemon that is responsible for sending all the There is one queue daemon that is responsible for sending all the
queued requests. 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 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. ... The corresponding entry in the sync queue is removed.
== Logging matrix === Logging matrix
Available parameters in comparisons are the following. Available parameters in comparisons are the following.
@ -127,7 +128,7 @@ Available parameters in comparisons are the following.
|================ |================
Parameters could be counters, modified, nonce. 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 We compare reponse parameters against validation parameters since we
are interested in if the server is in sync at the moment when the 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. | 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 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 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 | | 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 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? validation request or out of sync compared to current local counters?

42
doc/YubiKeyInfoFormat.adoc
View File

@ -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]

48
doc/YubiKey_Info_Format.adoc Normal file
View File

@ -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]

0
doc/legacy/ValidationProtocolV10.adoc → doc/legacy/Validation_Protocol_V1.0.adoc
View File

0
doc/legacy/ValidationProtocolV11.adoc → doc/legacy/Validation_Protocol_V1.1.adoc
View File