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
parent
0b53b4d27e
commit
823f4d6159
@ -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:
|
||||
@ -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,15 +6,16 @@ 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.
|
||||
|
||||
....
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo ykval-gen-clients --urandom 5
|
||||
|
||||
1,l+/c/XfDPDHsaNKrpjwL+bf/Hgs=
|
||||
@ -23,15 +24,16 @@ configuration stored in /etc/yubico/val/config-db.php.
|
||||
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):
|
||||
|
||||
....
|
||||
[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
|
||||
@ -40,12 +42,13 @@ in Debian as well as Ubuntu):
|
||||
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:
|
||||
|
||||
....
|
||||
[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
|
||||
@ -53,7 +56,7 @@ a bad OTP), the verification worked as expected. Compare it to the next example:
|
||||
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
|
||||
@ -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,
|
||||
@ -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
81
doc/Import_Export_Data.adoc
Normal 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:~$
|
||||
....
|
||||
|
||||
@ -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,41 +51,44 @@ 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:
|
||||
|
||||
....
|
||||
[source, sh]
|
||||
----
|
||||
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
|
||||
....
|
||||
----
|
||||
|
||||
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.
|
||||
|
||||
[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:
|
||||
|
||||
[source, sh]
|
||||
user@val:~$ sudo apt-get install mysql-server php5-mysql
|
||||
|
||||
The installation asks you for a MySQL "root" password, and I recommend
|
||||
@ -95,24 +96,32 @@ 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:
|
||||
|
||||
[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:
|
||||
|
||||
[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':
|
||||
|
||||
[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'; \
|
||||
@ -122,25 +131,34 @@ normally called 'ykval_verifier':
|
||||
FLUSH PRIVILEGES;
|
||||
mysql> \q
|
||||
user@val:~$
|
||||
----
|
||||
|
||||
==== Step 3B: PostgreSQL Installation ====
|
||||
==== Step 3B: PostgreSQL Installation
|
||||
|
||||
Install the required packages:
|
||||
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo apt-get install postgresql php5-pgsql
|
||||
...
|
||||
user@val:~$
|
||||
----
|
||||
|
||||
The database needs to be initialized as follows:
|
||||
|
||||
[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':
|
||||
|
||||
[source, sh]
|
||||
----
|
||||
postgres@val:~$ psql ykval -q
|
||||
ykval=# CREATE USER ykval_verifier PASSWORD 'yourpassword';
|
||||
ykval=# GRANT SELECT,INSERT,UPDATE ON yubikeys TO ykval_verifier;
|
||||
@ -148,18 +166,23 @@ normally called '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
|
||||
|
||||
[source, sh]
|
||||
----
|
||||
postgres@val:~$ exit
|
||||
user@val:~$
|
||||
----
|
||||
|
||||
During installation and debugging it may be useful to watch the
|
||||
database log entries:
|
||||
|
||||
[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,27 +190,35 @@ 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:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo sh -c 'cat > /var/www/wsapi/2.0/.htaccess'
|
||||
RewriteEngine on
|
||||
RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L]
|
||||
@ -196,6 +227,7 @@ Apache, using a .htaccess file:
|
||||
</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,50 +235,59 @@ 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.
|
||||
|
||||
[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:
|
||||
|
||||
[source, php]
|
||||
$baseParams['__YKVAL_DB_DSN__'] = "mysql:dbname=ykval;host=127.0.0.1";
|
||||
|
||||
An example DSN for a PostgreSQL setup:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
....
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval'
|
||||
<VirtualHost *:80>
|
||||
ServerName api.example.com
|
||||
@ -272,7 +313,7 @@ like this:
|
||||
|
||||
</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:
|
||||
|
||||
[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,7 +345,8 @@ You will need to place the private key in
|
||||
|
||||
Create Apache web configuration files:
|
||||
|
||||
....
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl'
|
||||
Listen 443
|
||||
<VirtualHost *:443>
|
||||
@ -333,23 +378,27 @@ Create Apache web configuration files:
|
||||
|
||||
</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.
|
||||
|
||||
[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.
|
||||
|
||||
....
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo sh -c 'cat > /etc/apache2/sites-available/ykval-ssl'
|
||||
<VirtualHost *:443>
|
||||
ServerName api.example.com
|
||||
@ -380,12 +429,14 @@ You will need to place the private key in
|
||||
|
||||
</VirtualHost>
|
||||
user@val:~$
|
||||
....
|
||||
----
|
||||
|
||||
==== Common Apache Configuration ====
|
||||
==== Common Apache Configuration
|
||||
|
||||
This step is the same for both mod_gnutls and mod_ssl.
|
||||
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo a2enmod rewrite
|
||||
Enabling module rewrite.
|
||||
Run '/etc/init.d/apache2 restart' to activate new configuration!
|
||||
@ -398,19 +449,23 @@ This step is the same for both mod_gnutls and mod_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:
|
||||
|
||||
[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,6 +474,8 @@ 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:
|
||||
|
||||
[source, sh]
|
||||
----
|
||||
user@val:~$ sudo sh -c 'cat > /etc/logrotate.d/ykval'
|
||||
/var/log/ykval.log {
|
||||
weekly
|
||||
@ -432,12 +489,13 @@ weekly. Create a file /etc/logrotate.d/ykval like this:
|
||||
endscript
|
||||
}
|
||||
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,7 +506,8 @@ 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):
|
||||
|
||||
....
|
||||
[source, conf]
|
||||
----
|
||||
*.=debug;\
|
||||
auth,authpriv.none;\
|
||||
news.none;mail.none -/var/log/debug
|
||||
@ -457,11 +516,12 @@ modify the default rules. For example, edit the following lines of
|
||||
auth,authpriv.none;\
|
||||
cron,daemon.none;\
|
||||
mail,news.none -/var/log/messages
|
||||
....
|
||||
----
|
||||
|
||||
Change them into:
|
||||
|
||||
....
|
||||
[source, conf]
|
||||
----
|
||||
*.=debug;\
|
||||
auth,authpriv.none;\
|
||||
news.none;mail.none;local0.none -/var/log/debug
|
||||
@ -471,50 +531,55 @@ Change them into:
|
||||
cron,daemon.none;\
|
||||
local0.none;\
|
||||
mail,news.none -/var/log/messages
|
||||
....
|
||||
----
|
||||
|
||||
Idempotent commands to speed this up:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
....
|
||||
[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
|
||||
@ -523,13 +588,13 @@ example:
|
||||
status=NO_SUCH_CLIENT
|
||||
|
||||
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.
|
||||
|
||||
@ -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
|
||||
@ -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
68
doc/Munin_Probes.adoc
Normal 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.
|
||||
@ -9,40 +9,55 @@ not be secure unless you take additional pre-cautions.
|
||||
|
||||
== Installation
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
[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:
|
||||
|
||||
[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.
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
|
||||
[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'
|
||||
@ -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:
|
||||
|
||||
[source, sh]
|
||||
user@val:~$ sudo mv /etc/php5/conf.d/curl.ini /etc/php5/conf.d/z_curl.ini
|
||||
|
||||
@ -1,7 +1,6 @@
|
||||
Validation Protocol Version 2.0
|
||||
===============================
|
||||
== Validation Protocol Version 2.0
|
||||
|
||||
== Introduction
|
||||
=== Introduction
|
||||
|
||||
All requests are HTTP GET requests. As such, all parameters must be
|
||||
properly URL encoded. In particular, some base64 characters (such as
|
||||
@ -12,7 +11,7 @@ response has not been tampered with, clients either verify the HMAC
|
||||
signature or use HTTPS connections (and verify the server
|
||||
certificate).
|
||||
|
||||
== Generating signatures
|
||||
=== Generating signatures
|
||||
|
||||
The protocol uses HMAC-SHA-1 signatures. The HMAC key to use is the
|
||||
client API key.
|
||||
@ -29,7 +28,7 @@ signature do:
|
||||
* Base 64 encode the resulting value according to RFC 4648, for example, `t2ZMtKeValdA+H0jVpj3LIichn4=`.
|
||||
* Append the value under key 'h' to the message.
|
||||
|
||||
== Verifying signatures
|
||||
=== Verifying signatures
|
||||
|
||||
To verify a signature on a response message, follow the same procedure
|
||||
that was used to sign the response message and compare the signature
|
||||
@ -47,7 +46,7 @@ make sure to remove h before verifying:
|
||||
|
||||
Don't forget to sort the key/value pairs.
|
||||
|
||||
== Verification
|
||||
=== Verification
|
||||
|
||||
There is one call to verify YubiKey OTPs: verify.
|
||||
|
||||
@ -58,7 +57,7 @@ send the OTP.
|
||||
To avoid cut'n'paste attacks, the client MUST verify that the "otp" in
|
||||
the response is the same as the "otp" supplied in the request.
|
||||
|
||||
== Request
|
||||
=== Request
|
||||
|
||||
Construct an HTTP GET call to
|
||||
|
||||
@ -116,7 +115,7 @@ counters:
|
||||
http://api.yubico.com/wsapi/2.0/verify?id=87&otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad×tamp=1
|
||||
|
||||
|
||||
== Response
|
||||
=== Response
|
||||
|
||||
The verification response tells you whether the OTP is valid. The
|
||||
response has the following values:
|
||||
@ -199,7 +198,7 @@ These are the possible "status" values in a verify response:
|
||||
| Server has seen the OTP/Nonce combination before
|
||||
|===
|
||||
|
||||
== Changes since version 1.1
|
||||
=== Changes since version 1.1
|
||||
|
||||
The verify URL has changed. In the request, the new required field
|
||||
"nonce" were added, and the new optional fields "sl" and "timeout" are
|
||||
@ -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,7 +36,7 @@ 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:
|
||||
@ -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?
|
||||
@ -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
48
doc/YubiKey_Info_Format.adoc
Normal 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]
|
||||
Loading…
x
Reference in New Issue
Block a user