oltu-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simone Tripodi <simone.trip...@gmail.com>
Subject Re: APIs
Date Tue, 15 Jun 2010 15:14:48 GMT
Hi Simo,
absolutely right, let's find a better way to describe how I started
designing the signature APIs...

First of all: use cases show us that there are symmetric algorithms
(PLAINTEXT, HMAC_SHA) and asymmetric algorithms (RSA_SHA1), so the
design should be able to be adaptable for both cases. I thought that a
symmetric algorithm is a special case of an asymmetric algorithm, so
let's consider having a SigningKey and a VerifyingKey interfaces, in
the case of a symmetric algorithm, the key implementation have to
implement both interfaces.

So, let's define the SignatureMethodAlgorithm - I hope the name is
semful!!! That's the interface definition

public interface SignatureMethodAlgorithm<S extends SigningKey, V
extends VerifyingKey>

where defined the the method to calculate the signature (throws
SignatureException if any error occurs):

    String calculate(S signingKey,
            String secretCredential,
            Service service,
            RequestMessage message,
            Parameter... parameters) throws SignatureException;

and the one to verify the signature:

boolean verify(String signature,
            V verifyingKey,
            String secretCredential,
            Service service,
            RequestMessage message,
            Parameter... parameters) throws SignatureException;

An abstract implementation, AbstractSignatureMethodAlgorithm, contains
common signature calculation stuff, like the base string creation.
Any SignatureMethodAlgorithm implementation is annotated by a
@SignatureMethod annotation to mark the oauth algorithm identifier,
ie:

@SignatureMethod("HMAC-SHA1")
public final class HmacSha1MethodAlgorithm extends
AbstractMethodAlgorithm<HmacSha1Key, HmacSha1Key> {
...
}

Let's now make clear what hell Service, RequestMessage and Parameter are :)


Service is the pair (URL, HttpMethod) that describes the service has
to be invoked. HttpMethod is an enumeration of all admitted http
method:
    HEAD,
    POST,
    PUT,
    GET,
    DELETE,
    OPTIONS,
    TRACE,
    CONNECT


RequestMessage is a POJO that contains the OAuth parameters like
version, nonce, timestamp, ... it is extended by the
TokenRequestMessage that differs from the previous one because
contains the token field.
Every RequestMessage field is annotated by @OAuthParameter annotation,
to mark if the field:
- is optional (false by default)
- has to be included in the parameter list to calculate the signature
(true by default)
- moreover contains the oauth parameter name

a sample can be found on the signature field:

@OAuthParameter(
            name = "oauth_signature",
            includeInSignature = false
    )
    private String signature;

That's all in therms of design, there are few little tricks on the
implementation side (java introspection rocks) but IMHO is small and
intuitive.
What do you think about it? Thoughts? Any feedback is more than welcome!!!!
All the best, have a nice reading :P
Simo

http://people.apache.org/~simonetripodi/



On Tue, Jun 15, 2010 at 4:17 PM, Simone Gianni <simoneg@apache.org> wrote:
> Hi Simo,
> obviously current SVN *is* the starting point.
>
> Let's see how to continue on that line, if there are other proposals, if
> some of our other existing code bases approach in a different way, or if
> someone foresees some other kind of problems in integrating the current API
> with their app.
>
> Simone
>
> 2010/6/15 Simone Tripodi <simone.tripodi@gmail.com>
>
>> Hi Simo,
>> currently in the current svn Amber repo there is the signature (with
>> implementation) and part of consumer APIs I wrote time ago for the
>> Lab.
>> They are still valid IMHO and part of my proposal, parts of code could
>> be extracted from there.
>>
>> Feel free to ask questions if some parts are not clear.
>> All the best,
>> Simo
>>
>> http://people.apache.org/~simonetripodi/<http://people.apache.org/%7Esimonetripodi/>
>>
>>
>>
>> On Tue, Jun 15, 2010 at 2:21 PM, Simone Gianni <simoneg@apache.org> wrote:
>> > Hi all,
>> > so, one part of our roadmap are APIs.
>> >
>> > Each of us has his own idea of how an API should be, in general, and many
>> of
>> > us already have an idea (or even code) on how an OAuth API should be :)
>> >
>> > There is no "absolute way" to determine if an API is better or worse than
>> > another. It mostly depends on use cases.
>> >
>> > Amber will (as many other systems) interact with :
>> > - external applications/frameworks, using Amber to integrate oauth
>> > - internal extensions, providing for example different token storages or
>> > interation different backends
>> > - modules of Amber itself
>> >
>> > I think it would be better to focus on the first API now : which use
>> cases
>> > do we plan? How do you imagine the code of a web framework using Amber
>> look
>> > like?
>> >
>> > If there are very different cases there is space for more than one API,
>> for
>> > example a low level one and high level Fa├žade. Since our goal is to unify
>> > different (often existing) pieces and ease the path of adoption on
>> projects
>> > that were planning to integrate OAuth, we'll need a bit of flexibility.
>> >
>> > Cast your code sample ideas :) People in projects that already use their
>> own
>> > implementation of OAuth can easily post real code.
>> >
>> > Simone
>> >
>>
>

Mime
View raw message