mirror of
https://github.com/Yubico/yubikey-val.git
synced 2024-11-29 09:24:12 +01:00
131 lines
4.9 KiB
Plaintext
131 lines
4.9 KiB
Plaintext
== Getting Started Writing Clients
|
|
|
|
=== Introduction
|
|
|
|
While the canonical description of the validation protocol is
|
|
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 is used to optionally sign the OTP validation request and to
|
|
verify the OTP validation response. We recommend all production
|
|
deployments use either API key or HTTPS.
|
|
|
|
If you use HTTPS to access Yubico's validation web service and you
|
|
validate the Yubico server SSL certificate, you don't need to use the
|
|
shared key to further authenticate response signatures from Yubico.
|
|
|
|
If you for some reason do not want to rely on HTTPS. You may also sign
|
|
requests using this API key.
|
|
|
|
To get an API key, first use
|
|
https://upgrade.yubico.com/getapikey/[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 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
|
|
simple string of characters, like this:
|
|
|
|
vvvvvvcurikvhjcvnlnbecbkubjvuittbifhndhn
|
|
|
|
=== 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
|
|
characters in the ModHex alphabet `cbdefghijklnrtuv`. Unfortunately,
|
|
this has turned out to be over-aggresive because if the keyboard layout is
|
|
Dvorak-based, it will look differently. For example, the modhex
|
|
alphabet in the US Dvorak layout is `jxe.uidchtnbpygk`. There are
|
|
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 the authentication request to our servers following the protocol
|
|
specified below. Your request should include the verifier ID (a number
|
|
that identifies the signature key), the OTP you captured in the
|
|
previous instruction, and a random looking string of characters to
|
|
make the request unique. The request is part of the HTTP GET URL,
|
|
encoded using normal parameter/value pairs. For example (broken into
|
|
two lines for legibility):
|
|
|
|
http://api2.yubico.com/wsapi/2.0/verify?id=1&otp=cccccccbcjdifc\
|
|
trndncchkftchjlnbhvhtugdljibej&nonce=aef3a7835277a28da831005c2ae3b919e2076a62
|
|
|
|
The servers that Yubico provides are:
|
|
|
|
api.yubico.com
|
|
api2.yubico.com
|
|
api3.yubico.com
|
|
api4.yubico.com
|
|
api5.yubico.com
|
|
|
|
These servers are hosted in different places and by different organizations.
|
|
|
|
=== Parse response
|
|
|
|
You will recieve a response back from the server, a string of text
|
|
that resembles the following:
|
|
|
|
h=vjhFxZrNHB5CjI6vhuSeF2n46a8=
|
|
t=2010-04-23T20:34:51Z0678
|
|
otp=cccccccbcjdifctrndncchkftchjlnbhvhtugdljibej
|
|
nonce=aef3a7835277a28da831005c2ae3b919e2076a62
|
|
sl=75
|
|
status=OK
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
client needs to do, it belongs elsewhere in the application, however
|
|
for completeness we mention how it is done here.
|
|
|
|
In some situations, the user is typing her username directly into your
|
|
application, which solves the issue.
|
|
|
|
More generally, the YubiKey OTP contains as the initial part an
|
|
identity of the YubiKey, and it can be used to identify the user. The
|
|
identity part is the same for every OTP, and it is the initial 2-16
|
|
modhex characters of the OTP. (The identity can be programmed to 0
|
|
characters, but then obviously this scheme does not apply.) Since the
|
|
rest of the OTP is always 32 characters, the method to extract the
|
|
identity is to remove 32 characters from the end and then use the
|
|
remaining string, which should be 2-16 characters, as the YubiKey
|
|
identity.
|
|
|
|
Note that the validation server is case insensitive, so you need to
|
|
lower-case the string in order to avoid caps lock resulting in
|
|
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
|
|
|
|
There are some more subtle matters that can be important, so please
|
|
read the entire protocol specification for all the details. Further,
|
|
for added reliability, you may send the request in parallel to more
|
|
than one server, which is not explained above.
|