== 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 link:Client_Info_Format.adoc[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.

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

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

[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 
secret, which the client then interprets as invalid (since it thinks the 
correct key is the dummy key we just gave it).