mirror of
https://github.com/Yubico/yubikey-val.git
synced 2025-01-20 10:52:15 +01:00
Remove, see wiki pages instead.
This commit is contained in:
Simon Josefsson
parent
f835ab3d9b
commit
1c7b2430cd
2
Makefile
2
Makefile
@ -1,6 +1,6 @@
|
||||
VERSION = 2.5
|
||||
PACKAGE = yubikey-val
|
||||
CODE = COPYING Makefile NEWS ykval-api.html ykval-checksum-clients.php \
|
||||
CODE = COPYING Makefile NEWS ykval-checksum-clients.php \
|
||||
ykval-common.php ykval-config.php ykval-db.php ykval-db.sql \
|
||||
ykval-export.php ykval-import.php ykval-log.php ykval-ping.php \
|
||||
ykval-queue.php ykval-revoke.php ykval-synclib.php \
|
||||
|
||||
226
ykval-api.html
226
ykval-api.html
@ -1,226 +0,0 @@
|
||||
<h6>Protocol Specification</h6>
|
||||
|
||||
<p>All requests are HTTP GETs. As such, all parameters must be
|
||||
properly URL encoded. In particular, some base64 characters (such as
|
||||
"+") in the value fields needs to be escaped.</p>
|
||||
|
||||
<p>Each response sent by Yubico is signed. To make sure the response
|
||||
has not been tampered with, you should verify the signature.</p>
|
||||
|
||||
<p>To verify a <a name="signatures">signature</a> on a response message, follow
|
||||
the same procedure that was used to <a href="#generate_sig">sign the
|
||||
response message</a> and compare the signature in the response to the signature
|
||||
you generated. If the signature values are equal, the
|
||||
signature is correct.</p>
|
||||
|
||||
Make sure you remove the signature itself from the values you generate
|
||||
the signature over for verification. If the incoming message is
|
||||
<pre>
|
||||
b=1&a=2&c=3&h=V5FkMYr9GCG9tQA9ihuuybWl99U=
|
||||
</pre>
|
||||
|
||||
make sure to remove <code>h</code> before verifying:
|
||||
<pre>b=1&a=2&c=3 </pre>
|
||||
<br />
|
||||
<hr size="1" noshade color="#cccccc">
|
||||
<br />
|
||||
<h6 id="generate_sig">Generating signatures</h6>
|
||||
|
||||
The Yubico API uses HMAC-SHA1 signatures with 160 bit key lengths
|
||||
(as defined by <a href="http://www.ietf.org/rfc/rfc3174.txt">RFC
|
||||
3174</a>). The HMAC key to use is the <a href="#api_key">API key</a>.
|
||||
<br /><br />
|
||||
|
||||
<p>Generate the signature over the parameters in the message. Each
|
||||
message contains a set of key/value pairs, and the signature is always
|
||||
over the entire set (excluding the signature itself), sorted in
|
||||
alphabetical order of the keys.
|
||||
|
||||
To generate a message signature:
|
||||
<ol>
|
||||
<li>Alphabetically sort the set of key/value pairs by key order.</li>
|
||||
<li>Construct a single line with each ordered key/value pair concatenated
|
||||
using '&', and each key and value contatenated with '='. Do not add any
|
||||
linebreaks. Do not add whitespace. For
|
||||
example: <code>a=2&b=1&c=3</code>.</li>
|
||||
<li>Apply the signature algorithm to the line's octet string (UTF-8 byte
|
||||
values according to
|
||||
<a href="http://www.ietf.org/rfc/rfc3629.txt">RFC 3629</a>) using
|
||||
the
|
||||
<a href="#api_key">API key</a> as key.</li>
|
||||
|
||||
<li>Base 64 encode the resulting value according to
|
||||
<a href="http://www.ietf.org/rfc/rfc4648.html">RFC 4648</a>, for
|
||||
example, <code>t2ZMtKeValdA+H0jVpj3LIichn4=</code>.</li>
|
||||
<li>Append the value under key <code>h</code> to the message.
|
||||
</ol>
|
||||
<br /><br />
|
||||
<hr size="1" noshade color="#cccccc">
|
||||
<br />
|
||||
|
||||
<h6>Verification</h6>
|
||||
|
||||
There is one call to verify YubiKey OTPs: <code>verify</code>.
|
||||
<br /><br />
|
||||
|
||||
|
||||
<b>verify</b>
|
||||
The <code>verify</code> call lets you check whether an OTP is valid. Since the
|
||||
OTP itself contains identification information, all you have to do
|
||||
is to send the OTP.
|
||||
<br /><br />
|
||||
<hr size="1" noshade color="#cccccc">
|
||||
<br />
|
||||
|
||||
<h6>Request</h6>
|
||||
Construct an HTTP GET call to
|
||||
<pre>http://api.yubico.com/wsapi/verify</pre>
|
||||
with the following parameters (note that this request need not be signed):
|
||||
<br></br>
|
||||
<table border="1">
|
||||
<th>parameter</th><th>type</th><th>required</th><th>purpose</th>
|
||||
<tr>
|
||||
<td><code>id</code></td>
|
||||
<td>string</td>
|
||||
|
||||
<td>Yes</td>
|
||||
<td>Specifies the requestor so that the end-point can retrieve
|
||||
correct shared secret for signing the response.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>otp</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
|
||||
<td>The OTP from the YubiKey.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>timestamp</td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td>Timestamp=1 requests timestamp and session counter information the response</td>
|
||||
|
||||
<tr>
|
||||
<td><code>h</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
|
||||
<td>The optional HMAC-SHA1 signature for the request.</td>
|
||||
</tr>
|
||||
</table>
|
||||
<br></br>
|
||||
An example request (broken into two lines for legibility):
|
||||
<pre>
|
||||
http://api.yubico.com/wsapi/verify?otp=vvvvvvcucrlcietctc\
|
||||
kflvnncdgckubflugerlnr&id=87 </pre>
|
||||
<br />
|
||||
And if you require additional information on timestamp and session counters:
|
||||
<pre>
|
||||
http://api.yubico.com/wsapi/verify?otp=vvvvvvcucrlcietctc\
|
||||
kflvnncdgckubflugerlnr&id=87×tamp=1 </pre>
|
||||
<br />
|
||||
|
||||
<hr size="1" noshade color="#cccccc">
|
||||
<br />
|
||||
|
||||
<h6>Response</h6>
|
||||
The verification response tells you whether the OTP is valid.
|
||||
|
||||
<br></br>
|
||||
The response has the following values:
|
||||
<br></br>
|
||||
|
||||
<table border=1 width="100%">
|
||||
<th>parameter</th><th>type</th><th>purpose</th>
|
||||
|
||||
<tr>
|
||||
<td><code>h</code></td>
|
||||
<td>string (base64)</td>
|
||||
|
||||
<td>Signature as <a href="#signatures">described above</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>t</code></td>
|
||||
<td>time stamp</td>
|
||||
<td>Timestamp in UTC.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>status</code></td>
|
||||
<td>string</td>
|
||||
<td>The status of the operation. The status are described
|
||||
in <a href="#verify_return_codes">return codes</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>timestamp</code></td>
|
||||
<td>string</td>
|
||||
<td>YubiKey internal timestamp value when key was pressed</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>sessioncounter</code></td>
|
||||
<td>string</td>
|
||||
<td>YubiKey internal usage counter when key was pressed</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>sessionuse</code></td>
|
||||
<td>string</td>
|
||||
<td>YubiKey internal session usage counter when key was pressed</td>
|
||||
</tr>
|
||||
</table>
|
||||
<br /><br />
|
||||
<hr size="1" noshade color="#cccccc">
|
||||
<br />
|
||||
|
||||
<h6 id="verify_return_codes">Return codes</h6>
|
||||
These are possible <code>status</code> values in a <code>verify</code>
|
||||
response:
|
||||
<table border=1 width="100%">
|
||||
<th>name</th><th>meaning</th>
|
||||
<tr>
|
||||
|
||||
<td><code>OK</code></td>
|
||||
<td>The OTP is valid.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>BAD_OTP</code></td>
|
||||
<td>The OTP is invalid format.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>REPLAYED_OTP</code></td>
|
||||
<td>The OTP has already been seen by the service.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>BAD_SIGNATURE</code></td>
|
||||
<td>The HMAC signature verification failed.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>MISSING_PARAMETER</code></td>
|
||||
<td>The request lacks a parameter.</td>
|
||||
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>NO_SUCH_CLIENT</code></td>
|
||||
<td>The request <code>id</code> does not exist.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>OPERATION_NOT_ALLOWED</code></td>
|
||||
<td>The request <code>id</code> is not allowed to verify OTPs.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>BACKEND_ERROR</code></td>
|
||||
<td>Unexpected error in our server. Please contact us if you see this
|
||||
error.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
Loading…
x
Reference in New Issue
Block a user