1
0
mirror of https://github.com/Yubico/yubikey-val.git synced 2025-02-01 01:52:18 +01:00

Improved asciidoc formatting

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

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

View File

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

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
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,

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

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

View File

@ -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]
<IfModule mod_php5.c>
[source, sh]
----
user@val:~$ sudo sh -c 'cat > /var/www/wsapi/2.0/.htaccess'
RewriteEngine on
RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L]
<IfModule mod_php5.c>
php_value include_path ".:/etc/yubico/val:/usr/share/yubikey-val"
</IfModule>
user@val:~$ sudo ln -s 2.0/.htaccess /var/www/wsapi/.htaccess
user@val:~$
</IfModule>
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'
<VirtualHost *:80>
ServerName api.example.com
ServerAdmin support@example.com
[source, sh]
----
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval'
<VirtualHost *:80>
ServerName api.example.com
ServerAdmin support@example.com
DocumentRoot /var/www/
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Order allow,deny
allow from all
</Directory>
DocumentRoot /var/www/
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Order allow,deny
allow from all
</Directory>
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
</VirtualHost>
user@val:~$
....
</VirtualHost>
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
<VirtualHost *: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
<VirtualHost *: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/
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Order allow,deny
allow from all
</Directory>
DocumentRoot /var/www/
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Order allow,deny
allow from all
</Directory>
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
</VirtualHost>
user@val:~$
....
</VirtualHost>
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'
<VirtualHost *:443>
ServerName api.example.com
ServerAdmin support@example.com
[source, sh]
----
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl'
<VirtualHost *:443>
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/
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Order allow,deny
allow from all
</Directory>
DocumentRoot /var/www/
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Order allow,deny
allow from all
</Directory>
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
</VirtualHost>
user@val:~$
....
</VirtualHost>
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://<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
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.

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

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.

View File

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

View File

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

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
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'

View File

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

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
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&timestamp=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

View File

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

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]

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]