diff --git a/Makefile b/Makefile index a53861b..3247e5b 100644 --- a/Makefile +++ b/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 \ diff --git a/ykval-api.html b/ykval-api.html deleted file mode 100644 index a4638a0..0000000 --- a/ykval-api.html +++ /dev/null @@ -1,226 +0,0 @@ -
Protocol Specification
- -

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.

- -

Each response sent by Yubico is signed. To make sure the response -has not been tampered with, you should verify the signature.

- -

To verify a signature on a response message, follow -the same procedure that was used to sign the -response message and compare the signature in the response to the signature -you generated. If the signature values are equal, the -signature is correct.

- -Make sure you remove the signature itself from the values you generate -the signature over for verification. If the incoming message is -
-b=1&a=2&c=3&h=V5FkMYr9GCG9tQA9ihuuybWl99U=
-
- -make sure to remove h before verifying: -
b=1&a=2&c=3
-
-
-
-
Generating signatures
- -The Yubico API uses HMAC-SHA1 signatures with 160 bit key lengths -(as defined by RFC -3174). The HMAC key to use is the API key. -

- -

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

    -
  1. Alphabetically sort the set of key/value pairs by key order.
    2. -
  2. 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: a=2&b=1&c=3.
    3. -
  3. Apply the signature algorithm to the line's octet string (UTF-8 byte - values according to - RFC 3629) using - the - API key as key.
    4. - -
  4. Base 64 encode the resulting value according to - RFC 4648, for - example, t2ZMtKeValdA+H0jVpj3LIichn4=.
    5. -
  5. Append the value under key h to the message. -
-

-
-
- -
Verification
- -There is one call to verify YubiKey OTPs: verify. -

- - -verify -The verify 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. -

-
-
- -
Request
-Construct an HTTP GET call to -
http://api.yubico.com/wsapi/verify
-with the following parameters (note that this request need not be signed): -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
parametertyperequiredpurpose
idstringYesSpecifies the requestor so that the end-point can retrieve - correct shared secret for signing the response.
otpstringYesThe OTP from the YubiKey.
timestampstringNoTimestamp=1 requests timestamp and session counter information the response
hstringNoThe optional HMAC-SHA1 signature for the request.
-

-An example request (broken into two lines for legibility): -
-http://api.yubico.com/wsapi/verify?otp=vvvvvvcucrlcietctc\
-kflvnncdgckubflugerlnr&id=87
-
-And if you require additional information on timestamp and session counters: -
-http://api.yubico.com/wsapi/verify?otp=vvvvvvcucrlcietctc\
-kflvnncdgckubflugerlnr&id=87×tamp=1
-
- -
-
- -
Response
-The verification response tells you whether the OTP is valid. - -

-The response has the following values: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
parametertypepurpose
hstring (base64)Signature as described above.
ttime stampTimestamp in UTC.
statusstringThe status of the operation. The status are described - in return codes.
timestampstringYubiKey internal timestamp value when key was pressed
sessioncounterstringYubiKey internal usage counter when key was pressed
sessionusestringYubiKey internal session usage counter when key was pressed
-

-
-
- -
Return codes
-These are possible status values in a verify -response: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
namemeaning
OKThe OTP is valid.
BAD_OTPThe OTP is invalid format.
REPLAYED_OTPThe OTP has already been seen by the service.
BAD_SIGNATUREThe HMAC signature verification failed.
MISSING_PARAMETERThe request lacks a parameter.
NO_SUCH_CLIENTThe request id does not exist.
OPERATION_NOT_ALLOWEDThe request id is not allowed to verify OTPs.
BACKEND_ERRORUnexpected error in our server. Please contact us if you see this - error.