/usr/share/doc/yubikey-val/GeneratingClients.adoc is in yubikey-val 2.27-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | = 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
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 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
1,l+/c/XfDPDHsaNKrpjwL+bf/Hgs=
2,LPGHqukoIAUGgDuOs7O0e1f8xD0=
3,K+gWRE0euOjVOiLD4Nm0wyHrHY8=
4,+8LF+ADANTAHnwB82xkBb+mNEFs=
5,URc6oabcuRV8OWW1Hs1cYym3ba4=
user@val:~$
....
== 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:~$
....
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:~$
....
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
secret, which the client then interprets as invalid (since it thinks the
correct key is the dummy key we just gave it).
|