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 Client Info Format.

Warning

There is no built-in method for synchronizing clients, if ykval-gen-clients is used in a multi-server environment the clients will only exist on one server.

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