From 2123686e53a99cd32af754d861d71ff61c026732 Mon Sep 17 00:00:00 2001 From: Michael Krelin Date: Sat, 17 May 2008 22:09:49 +0000 Subject: slight doxygenization of OAuth part Signed-off-by: Michael Krelin --- diff --git a/include/opkele/oauth/consumer.h b/include/opkele/oauth/consumer.h index eb4f753..3ad18a2 100644 --- a/include/opkele/oauth/consumer.h +++ b/include/opkele/oauth/consumer.h @@ -7,87 +7,251 @@ #include namespace opkele { + /** + * @brief OAuth support namespace + */ namespace oauth { using std::string; + /** + * oauth parameter passing method + */ enum oauth_method_t { - oauth_auth_header, oauth_post_body, oauth_url_query, + /** + * via WWW-Authenticate header + */ + oauth_auth_header, + /** + * via POST body + */ + oauth_post_body, + /** + * via GET query string + */ + oauth_url_query, + /** + * default method + */ oauth_method_default = oauth_auth_header }; + /** + * Service endpoint description + */ struct service_endpoint_t { + /** + * endpoint URI + */ string url; + /** + * signature method + */ string signature_method; + /** + * OAuth parameter passing method + */ oauth_method_t oauth_method; service_endpoint_t() : oauth_method(oauth_method_default) { } + /** + * @param u endpoint URI + * @param sm signature method + * @param om OAuth parameter passing method + */ service_endpoint_t(const string& u,const string& sm,oauth_method_t om=oauth_method_default) : url(u), signature_method(sm), oauth_method(om) { } }; + /** + * Base class for OAuth provider endpoints description + */ class basic_provider_endpoints { public: virtual ~basic_provider_endpoints() { } - + + /** + * Retrieve endpoint for obtaining an unauthorized request token + * @return service endpoint description + */ virtual const service_endpoint_t& get_request_token_endpoint() const = 0; + /** + * Retrieve endpoint for user authorization + * @return service endpoint description + */ virtual const service_endpoint_t& get_authorize_user_endpoint() const = 0; + /** + * Retrieve endpoint for obtaining an access token from the + * authorized request token + * @return service endpoint description + */ virtual const service_endpoint_t& get_access_token_endpoint() const = 0; + /** + * Make up an endpoint description give an URI + * @param sep reference to the service endpoint description object to fill in + * @param url endpoint URL + * @return reference to sep + */ virtual service_endpoint_t& get_url_endpoint(service_endpoint_t& sep, const string& url) const = 0; }; + /** + * HTTP request information + */ struct http_request_t { + /** + * WWW-Authenticate header + */ string authorize_header; + /** + * HTTP method + */ string method; + /** + * Target URL + */ string url; + /** + * POST body + */ string body; + /** + * curl-ready headers + */ util::curl_slist_t _curl_headers_list; + /** + * @param m HTTP method + * @param u target URL + */ http_request_t(const string& m,const string& u) : method(m), url(u) { } + /** + * Set relevant curl handle options + */ void setup_curl(CURL *curl); }; + /** + * OAuth consumer base class + */ class basic_consumer { public: + /** + * Consumer token + */ token_t consumer_token; + /** + * @param ct consumer token + */ basic_consumer(const token_t& ct) : consumer_token(ct) { } virtual ~basic_consumer() { } + /** + * Retrieve reference to the provider endpoints description object + * @return reference to the provider endpoints description object + */ virtual const basic_provider_endpoints& get_endpoints() const = 0; + /** + * Allocate nonce + * @param ts request timestamp + * @return nonce string + */ virtual const string allocate_nonce(time_t ts) = 0; + /** + * Obtain an unauthorized request token + * @return request token + */ token_t get_request_token(); + /** + * Retrieve the user authorization URL + * @param rt unauthorized request token + * @param callback callback URL to be passed to oauth provider + * to redirect user to upon authorization + * @return user authorization URL + */ const string get_authorize_url(const token_t& rt,const string& callback=""); + /** + * Trade an authorized request token for an access token + * @param rt authorized request token + * @return access token + */ token_t get_access_token(const token_t& rt); + /** + * Prepare http request parameters + * @param req request description to fill in + * @param qf query string parameters + * @param pf post body parameters + * @param om OAuth method + * @param sm signature method + * @param t pointer to the token to use to sign request, if any. + * @param realm authorization realm + * @return reference to req + */ http_request_t& prepare_request( http_request_t& req, const basic_fields& qf,const basic_fields& pf, oauth_method_t om,const string& sm, const token_t *t=0,const string& realm=""); + /** + * Prepare http request parameters + * @param req request description to fill in + * @param qf query string parameters + * @param pf post body parameters + * @param sep service endpoint description + * @param t pointer to the token to use to sign request, if any. + * @param realm authorization realm + * @return reference to req + */ http_request_t& prepare_request( http_request_t& req, const basic_fields& qf,const basic_fields& pf, const service_endpoint_t& sep, const token_t *t=0,const string& realm=""); + /** + * Prepare http request parameters + * @param req request description to fill in + * @param qf query string parameters + * @param pf post body parameters + * @param t pointer to the token to use to sign request, if any. + * @param realm authorization realm + * @return reference to req + */ http_request_t& prepare_request( http_request_t& req, const basic_fields& qf,const basic_fields& pf, const token_t *t=0,const string& realm=""); + /** + * Calculate request signature + * @param method http method + * @param url the url being invoked + * @param fields all request fields (query string, auth header, + * post body) + * @param rt pointer to the request token to be used for + * signing, if any. + */ const string signature( const string& method, const string& url, const basic_fields& fields, const token_t* rt=0); + /** + * Acquire token from an OAuth provider + * @param sep service endpoint description + * @param rt pointer to the request token to use for signing, + * if any + * @return the acquired token + */ token_t acquire_token( const service_endpoint_t& sep, const token_t* rt=0); @@ -100,6 +264,14 @@ namespace opkele { service_endpoint_t sep_access_token; service_endpoint_t sep_generic; + /** + * @param rt request token endpoint URL + * @param au user authorization endpoint URL + * @param at access token endpoint URL + * @param sm signature method + * @param ams authentication method for service endpoints + * @param amr authentication method for resource access + */ simple_provider_endpoints( const string& rt,const string& au,const string& at, const string& sm, @@ -121,6 +293,12 @@ namespace opkele { public: simple_provider_endpoints peps; + /** + * @param eps provider endpoints + * @param ct consumer token + * @see simple_provider_endpoints + * @see token_t + */ simple_consumer(const simple_provider_endpoints& eps, const token_t& ct) : basic_consumer(ct), peps(eps) { } -- cgit v0.9.0.2