Semantics of the web service API
Tollef Fog Heen
Hi,
If I do a request to
http://api.yubico.com/wsapi/verify?id=blah&otp=1234, I get back a
response along the lines of:
h=36P6nT8FUUucv6srQA60WZF3dMI=
t=2009-10-10T20:49:07Z0577
status=MISSING_PARAMETER
This is wrong on a couple of points:
- there is no info parameter, which I understand there should be when
status=MISSING_PARAMETER. This is a minor implementation detail.
- shouldn't it give me NO_SUCH_CLIENT as the status?
- more importantly, which key has been used for signing the request?
I assume yubico don't give out non-numeric IDs (at least mine was a
number), so it will be unable to actually look up any ID when I pass
id=blah. What are the correct semantics here? Not sign the request,
sign it with a random key, just close the connection or something
else?
I don't know whether yubico are using the Java or the PHP server, and
I'm obviously interested in finding out the semantics because of my own
server implementation.
--
Tollef Fog Heen
UNIX is user friendly, it's just picky about who its friends are
Simon Josefsson
> Hi,
>
> If I do a request to
> http://api.yubico.com/wsapi/verify?id=blah&otp=1234, I get back a
> response along the lines of:
>
> h=36P6nT8FUUucv6srQA60WZF3dMI=
> t=2009-10-10T20:49:07Z0577
> status=MISSING_PARAMETER
>
> This is wrong on a couple of points:
Yes, following the Garbage-In-Garbage-Out principle.
> - there is no info parameter, which I understand there should be when
> status=MISSING_PARAMETER. This is a minor implementation detail.
I've fixed the documentation here.
> - shouldn't it give me NO_SUCH_CLIENT as the status?
Possibly, although the client doesn't follow the protocol so requiring
some specific semantics on the server doesn't appear to serve much
point.
> - more importantly, which key has been used for signing the request?
> I assume yubico don't give out non-numeric IDs (at least mine was a
> number), so it will be unable to actually look up any ID when I pass
> id=blah. What are the correct semantics here? Not sign the request,
> sign it with a random key, just close the connection or something
> else?
I think the PHP server will just use the empty string as the key in this
situation.
> I don't know whether yubico are using the Java or the PHP server, and
> I'm obviously interested in finding out the semantics because of my own
> server implementation.
We are using the current PHP server.
I'd say that for clients that doesn't follow the protocol, you can do
anything you like. Closing the connection would be fine.
/Simon
Tollef Fog Heen
| Tollef Fog Heen <tfh...@err.no> writes:
|
| > Hi,
| >
| > If I do a request to
| > http://api.yubico.com/wsapi/verify?id=blah&otp=1234, I get back a
| > response along the lines of:
| >
| > h=36P6nT8FUUucv6srQA60WZF3dMI=
| > t=2009-10-10T20:49:07Z0577
| > status=MISSING_PARAMETER
| >
| > This is wrong on a couple of points:
|
| Yes, following the Garbage-In-Garbage-Out principle.
|
| > - there is no info parameter, which I understand there should be when
| > status=MISSING_PARAMETER. This is a minor implementation detail.
|
| I've fixed the documentation here.
Some comments on the updated docs:
Could we please have a version number and changelog in the web API docs?
I think that having the signature be optional when you don't have a
shared key (such as in the NO_SUCH_CLIENT case) would be ok.
Could the timestamp=1 in the request rather be timestamp=(true|false),
defaulting to true? (It doesn't say what the default is.) Not a big
deal, but more clear what the value means. Ideally, I'd like it to be
called something else, as it is confusing whether it's the t field or
the token states you want to get back.
It would also be useful if the timestamp, sessioncounter and sessionuse
fields in the response were optional (and marked as such). I don't
really see a point in giving those out in the common case (but I see the
point for your timedelta service).
The format of the time stamp does not appear to be defined anywhere?
| > - shouldn't it give me NO_SUCH_CLIENT as the status?
|
| Possibly, although the client doesn't follow the protocol so requiring
| some specific semantics on the server doesn't appear to serve much
| point.
The ID is defined as a string, not an integer, so I think the PHP server
is wrong here. It does correctly give me NO_SUCH_CLIENT for
id=100000000.
Tollef Fog Heen
| ]] Simon Josefsson
|
| | I've fixed the documentation here.
|
| Some comments on the updated docs:
Another thing:
Could we have the request include an optional timestamp? The server
could then verify that the time stamp is not too old, and so make the
attack window for stolen OTPs _much_ smaller. Typically, you'd allow up
to five minutes' skew. As the request will be coming from a service
running on a server most likely under your control, making sure clocks
are reasonably synchronised is quite simple.
Simon Josefsson
> ]] Tollef Fog Heen
>
> | ]] Simon Josefsson
> |
> | | I've fixed the documentation here.
> |
> | Some comments on the updated docs:
>
> Another thing:
>
> Could we have the request include an optional timestamp? The server
> could then verify that the time stamp is not too old, and so make the
> attack window for stolen OTPs _much_ smaller. Typically, you'd allow up
> to five minutes' skew. As the request will be coming from a service
> running on a server most likely under your control, making sure clocks
> are reasonably synchronised is quite simple.
Yes -- I think there is a number of API extensions that makes sense.
There is a concern about adding to many features though, and the
complexity around that. I have been inspired by OpenStreetMap's
versioned APIs where they have a web service interface like this:
http://api.example.org/0.3/whatever?
http://api.example.org/0.4/whatever?foo&bar
http://api.example.org/0.5/whatever?baz
The intention is that the "0.3" URL will behave the same forever. This
allows applications to upgrade when they are ready, with no flag days.
It also allows easier code maintaining -- the version "0.3" code is
never really touched once deployed (except possibly for security
problems). The latest "0.5" tree could be experimental and change while
in development, and updates could be easily applied without worrying
about compatibility with other services.
We are definitely stuck with the current URL for a "1.0" service, but
maybe we can use a versioned scheme in the future.
This would leave us with:
http://api.yubico.com/wsapi/verify <- current approach, v1.0
http://api.yubico.com/wsapi/1.1/verify <- development tree
The v1.1 branch could be the current in-development tree, which would be
open to feature additions until we declare it stable.
Thoughts?
/Simon
Simon Josefsson
> ]] Tollef Fog Heen
>
> | ]] Simon Josefsson
> |
> | | I've fixed the documentation here.
> |
> | Some comments on the updated docs:
>
> Another thing:
>
> Could we have the request include an optional timestamp? The server
> could then verify that the time stamp is not too old, and so make the
> attack window for stolen OTPs _much_ smaller. Typically, you'd allow up
> to five minutes' skew. As the request will be coming from a service
> running on a server most likely under your control, making sure clocks
> are reasonably synchronised is quite simple.
It occurred to me that I didn't comment on your actual suggestion...
I'm not sure I understand what advantage this brings, can you explain
the attack? As far as I can tell, anyone able to steal an OTP can
create their own request to the validation server (which could have the
correct time). Or just use the OTP against some other, real, service
that used YubiKeys.
Or did you mean that the server would correlate the timestamp with the
time lapsed in the yubikey somehow? I'm not sure I see how that would
work either.
I haven't had any coffee yet, though, so I may be completely off...
/Simon
Olov Danielson
| defaulting to true? (It doesn't say what the default is.) Not a big
| deal, but more clear what the value means. Ideally, I'd like it to be
| called something else, as it is confusing whether it's the t field or
| the token states you want to get back.
in the YubiKey manual? For example parameter timer=true
in request make a request for timer and session fields.
Missing timer parameter or timer!=true does not give a
response including timer and session parameters.
Is true better than 1?
|This would leave us with:
|
|http://api.yubico.com/wsapi/verify <- current approach, v1.0
|http://api.yubico.com/wsapi/1.1/verify <- development tree
|
|The v1.1 branch could be the current in-development tree, which would be
|open to feature additions until we declare it stable.
|
|Thoughts?
working solutions unless necessary.
Regards,
/Olov