rooty/yubikey-val
1
0
Fork 0
mirror of https://github.com/Yubico/yubikey-val.git synced 2025-03-04 03:29:18 +01:00
Code Issues Projects Releases Wiki Activity

Stricter Asciidoc, that now works on opensource.yubico.com as well

Browse Source
This commit is contained in:
Henrik Stråth 2014-08-12 13:45:01 +02:00
parent 28be2d11e1
commit 97432950b1
1 changed files with 14 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/ValidationProtocolV20.adoc
View File

@ -1,7 +1,7 @@
Validation Protocol Version 2.0 Validation Protocol Version 2.0
=============================== ===============================
## Introduction == Introduction
All requests are HTTP GET requests. As such, all parameters must be All requests are HTTP GET requests. As such, all parameters must be
properly URL encoded. In particular, some base64 characters (such as properly URL encoded. In particular, some base64 characters (such as
@ -12,7 +12,7 @@ response has not been tampered with, clients either verify the HMAC
signature or use HTTPS connections (and verify the server signature or use HTTPS connections (and verify the server
certificate). certificate).
## Generating signatures == Generating signatures
The protocol uses HMAC-SHA-1 signatures. The HMAC key to use is the The protocol uses HMAC-SHA-1 signatures. The HMAC key to use is the
client API key. client API key.
@ -29,7 +29,7 @@ signature do:
* Base 64 encode the resulting value according to RFC 4648, for example, `t2ZMtKeValdA+H0jVpj3LIichn4=`. * Base 64 encode the resulting value according to RFC 4648, for example, `t2ZMtKeValdA+H0jVpj3LIichn4=`.
* Append the value under key 'h' to the message. * 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 To verify a signature on a response message, follow the same procedure
that was used to sign the response message and compare the signature that was used to sign the response message and compare the signature
@ -38,19 +38,16 @@ values are equal, the signature is correct. Make sure you remove the
signature itself from the values you generate the signature over for signature itself from the values you generate the signature over for
verification. If the incoming message is verification. If the incoming message is
```
b=1&a=2&c=3&h=V5FkMYr9GCG9tQA9ihuuybWl99U= b=1&a=2&c=3&h=V5FkMYr9GCG9tQA9ihuuybWl99U=
```
make sure to remove h before verifying: make sure to remove h before verifying:
```
b=1&a=2&c=3 b=1&a=2&c=3
```
Don't forget to sort the key/value pairs. Don't forget to sort the key/value pairs.
## Verification == Verification
There is one call to verify YubiKey OTPs: verify. There is one call to verify YubiKey OTPs: verify.
@ -61,7 +58,7 @@ send the OTP.
To avoid cut'n'paste attacks, the client MUST verify that the "otp" in 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. the response is the same as the "otp" supplied in the request.
## Request == Request
Construct an HTTP GET call to Construct an HTTP GET call to
@ -112,18 +109,15 @@ with the following parameters (note that this request need not be signed):
An example request: An example request:
```
http://api.yubico.com/wsapi/2.0/verify?otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&id=87&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad http://api.yubico.com/wsapi/2.0/verify?otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&id=87&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad
```
And if you require additional information on timestamp and session And if you require additional information on timestamp and session
counters: counters:
```
http://api.yubico.com/wsapi/2.0/verify?id=87&otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad&timestamp=1 http://api.yubico.com/wsapi/2.0/verify?id=87&otp=vvvvvvcucrlcietctckflvnncdgckubflugerlnr&timeout=8&sl=50&nonce=askjdnkajsndjkasndkjsnad&timestamp=1
```
## Response
== Response
The verification response tells you whether the OTP is valid. The The verification response tells you whether the OTP is valid. The
response has the following values: response has the following values:
@ -204,9 +198,9 @@ These are the possible "status" values in a verify response:
| REPLAYED_REQUEST | REPLAYED_REQUEST
| Server has seen the OTP/Nonce combination before | 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 The verify URL has changed. In the request, the new required field
"nonce" were added, and the new optional fields "sl" and "timeout" are "nonce" were added, and the new optional fields "sl" and "timeout" are