author | Michael Krelin <hacker@klever.net> | 2008-05-17 22:09:49 (UTC) |
---|---|---|
committer | Michael Krelin <hacker@klever.net> | 2008-05-17 22:09:49 (UTC) |
commit | 2123686e53a99cd32af754d861d71ff61c026732 (patch) (unidiff) | |
tree | e72eb070a30a2b4cb1966382047e2f5d8db4a71c /include/opkele | |
parent | 42a7c6597dab9147e47d25470b5218ae4c072eaf (diff) | |
download | libopkele-2123686e53a99cd32af754d861d71ff61c026732.zip libopkele-2123686e53a99cd32af754d861d71ff61c026732.tar.gz libopkele-2123686e53a99cd32af754d861d71ff61c026732.tar.bz2 |
slight doxygenization of OAuth part
Signed-off-by: Michael Krelin <hacker@klever.net>
-rw-r--r-- | include/opkele/oauth/consumer.h | 180 |
1 files changed, 179 insertions, 1 deletions
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 | |||
@@ -1,135 +1,313 @@ | |||
1 | #ifndef __OPKELE_OAUTH_CONSUMER_H | 1 | #ifndef __OPKELE_OAUTH_CONSUMER_H |
2 | #define __OPKELE_OAUTH_CONSUMER_H | 2 | #define __OPKELE_OAUTH_CONSUMER_H |
3 | 3 | ||
4 | #include <string> | 4 | #include <string> |
5 | #include <opkele/types.h> | 5 | #include <opkele/types.h> |
6 | #include <opkele/oauth.h> | 6 | #include <opkele/oauth.h> |
7 | #include <opkele/curl.h> | 7 | #include <opkele/curl.h> |
8 | 8 | ||
9 | namespace opkele { | 9 | namespace opkele { |
10 | /** | ||
11 | * @brief OAuth support namespace | ||
12 | */ | ||
10 | namespace oauth { | 13 | namespace oauth { |
11 | using std::string; | 14 | using std::string; |
12 | 15 | ||
16 | /** | ||
17 | * oauth parameter passing method | ||
18 | */ | ||
13 | enum oauth_method_t { | 19 | enum oauth_method_t { |
14 | oauth_auth_header, oauth_post_body, oauth_url_query, | 20 | /** |
21 | * via WWW-Authenticate header | ||
22 | */ | ||
23 | oauth_auth_header, | ||
24 | /** | ||
25 | * via POST body | ||
26 | */ | ||
27 | oauth_post_body, | ||
28 | /** | ||
29 | * via GET query string | ||
30 | */ | ||
31 | oauth_url_query, | ||
32 | /** | ||
33 | * default method | ||
34 | */ | ||
15 | oauth_method_default = oauth_auth_header | 35 | oauth_method_default = oauth_auth_header |
16 | }; | 36 | }; |
17 | 37 | ||
38 | /** | ||
39 | * Service endpoint description | ||
40 | */ | ||
18 | struct service_endpoint_t { | 41 | struct service_endpoint_t { |
42 | /** | ||
43 | * endpoint URI | ||
44 | */ | ||
19 | string url; | 45 | string url; |
46 | /** | ||
47 | * signature method | ||
48 | */ | ||
20 | string signature_method; | 49 | string signature_method; |
50 | /** | ||
51 | * OAuth parameter passing method | ||
52 | */ | ||
21 | oauth_method_t oauth_method; | 53 | oauth_method_t oauth_method; |
22 | 54 | ||
23 | service_endpoint_t() : oauth_method(oauth_method_default) { } | 55 | service_endpoint_t() : oauth_method(oauth_method_default) { } |
56 | /** | ||
57 | * @param u endpoint URI | ||
58 | * @param sm signature method | ||
59 | * @param om OAuth parameter passing method | ||
60 | */ | ||
24 | service_endpoint_t(const string& u,const string& sm,oauth_method_t om=oauth_method_default) | 61 | service_endpoint_t(const string& u,const string& sm,oauth_method_t om=oauth_method_default) |
25 | : url(u), signature_method(sm), oauth_method(om) { } | 62 | : url(u), signature_method(sm), oauth_method(om) { } |
26 | }; | 63 | }; |
27 | 64 | ||
65 | /** | ||
66 | * Base class for OAuth provider endpoints description | ||
67 | */ | ||
28 | class basic_provider_endpoints { | 68 | class basic_provider_endpoints { |
29 | public: | 69 | public: |
30 | 70 | ||
31 | virtual ~basic_provider_endpoints() { } | 71 | virtual ~basic_provider_endpoints() { } |
32 | 72 | ||
73 | /** | ||
74 | * Retrieve endpoint for obtaining an unauthorized request token | ||
75 | * @return service endpoint description | ||
76 | */ | ||
33 | virtual const service_endpoint_t& get_request_token_endpoint() const = 0; | 77 | virtual const service_endpoint_t& get_request_token_endpoint() const = 0; |
78 | /** | ||
79 | * Retrieve endpoint for user authorization | ||
80 | * @return service endpoint description | ||
81 | */ | ||
34 | virtual const service_endpoint_t& get_authorize_user_endpoint() const = 0; | 82 | virtual const service_endpoint_t& get_authorize_user_endpoint() const = 0; |
83 | /** | ||
84 | * Retrieve endpoint for obtaining an access token from the | ||
85 | * authorized request token | ||
86 | * @return service endpoint description | ||
87 | */ | ||
35 | virtual const service_endpoint_t& get_access_token_endpoint() const = 0; | 88 | virtual const service_endpoint_t& get_access_token_endpoint() const = 0; |
36 | 89 | ||
90 | /** | ||
91 | * Make up an endpoint description give an URI | ||
92 | * @param sep reference to the service endpoint description object to fill in | ||
93 | * @param url endpoint URL | ||
94 | * @return reference to sep | ||
95 | */ | ||
37 | virtual service_endpoint_t& get_url_endpoint(service_endpoint_t& sep, | 96 | virtual service_endpoint_t& get_url_endpoint(service_endpoint_t& sep, |
38 | const string& url) const = 0; | 97 | const string& url) const = 0; |
39 | }; | 98 | }; |
40 | 99 | ||
100 | /** | ||
101 | * HTTP request information | ||
102 | */ | ||
41 | struct http_request_t { | 103 | struct http_request_t { |
104 | /** | ||
105 | * WWW-Authenticate header | ||
106 | */ | ||
42 | string authorize_header; | 107 | string authorize_header; |
108 | /** | ||
109 | * HTTP method | ||
110 | */ | ||
43 | string method; | 111 | string method; |
112 | /** | ||
113 | * Target URL | ||
114 | */ | ||
44 | string url; | 115 | string url; |
116 | /** | ||
117 | * POST body | ||
118 | */ | ||
45 | string body; | 119 | string body; |
46 | 120 | ||
121 | /** | ||
122 | * curl-ready headers | ||
123 | */ | ||
47 | util::curl_slist_t _curl_headers_list; | 124 | util::curl_slist_t _curl_headers_list; |
48 | 125 | ||
126 | /** | ||
127 | * @param m HTTP method | ||
128 | * @param u target URL | ||
129 | */ | ||
49 | http_request_t(const string& m,const string& u) | 130 | http_request_t(const string& m,const string& u) |
50 | : method(m), url(u) { } | 131 | : method(m), url(u) { } |
51 | 132 | ||
133 | /** | ||
134 | * Set relevant curl handle options | ||
135 | */ | ||
52 | void setup_curl(CURL *curl); | 136 | void setup_curl(CURL *curl); |
53 | }; | 137 | }; |
54 | 138 | ||
139 | /** | ||
140 | * OAuth consumer base class | ||
141 | */ | ||
55 | class basic_consumer { | 142 | class basic_consumer { |
56 | public: | 143 | public: |
144 | /** | ||
145 | * Consumer token | ||
146 | */ | ||
57 | token_t consumer_token; | 147 | token_t consumer_token; |
58 | 148 | ||
149 | /** | ||
150 | * @param ct consumer token | ||
151 | */ | ||
59 | basic_consumer(const token_t& ct) | 152 | basic_consumer(const token_t& ct) |
60 | : consumer_token(ct) { } | 153 | : consumer_token(ct) { } |
61 | virtual ~basic_consumer() { } | 154 | virtual ~basic_consumer() { } |
62 | 155 | ||
156 | /** | ||
157 | * Retrieve reference to the provider endpoints description object | ||
158 | * @return reference to the provider endpoints description object | ||
159 | */ | ||
63 | virtual const basic_provider_endpoints& get_endpoints() const = 0; | 160 | virtual const basic_provider_endpoints& get_endpoints() const = 0; |
161 | /** | ||
162 | * Allocate nonce | ||
163 | * @param ts request timestamp | ||
164 | * @return nonce string | ||
165 | */ | ||
64 | virtual const string allocate_nonce(time_t ts) = 0; | 166 | virtual const string allocate_nonce(time_t ts) = 0; |
65 | 167 | ||
168 | /** | ||
169 | * Obtain an unauthorized request token | ||
170 | * @return request token | ||
171 | */ | ||
66 | token_t get_request_token(); | 172 | token_t get_request_token(); |
173 | /** | ||
174 | * Retrieve the user authorization URL | ||
175 | * @param rt unauthorized request token | ||
176 | * @param callback callback URL to be passed to oauth provider | ||
177 | * to redirect user to upon authorization | ||
178 | * @return user authorization URL | ||
179 | */ | ||
67 | const string get_authorize_url(const token_t& rt,const string& callback=""); | 180 | const string get_authorize_url(const token_t& rt,const string& callback=""); |
181 | /** | ||
182 | * Trade an authorized request token for an access token | ||
183 | * @param rt authorized request token | ||
184 | * @return access token | ||
185 | */ | ||
68 | token_t get_access_token(const token_t& rt); | 186 | token_t get_access_token(const token_t& rt); |
69 | 187 | ||
188 | /** | ||
189 | * Prepare http request parameters | ||
190 | * @param req request description to fill in | ||
191 | * @param qf query string parameters | ||
192 | * @param pf post body parameters | ||
193 | * @param om OAuth method | ||
194 | * @param sm signature method | ||
195 | * @param t pointer to the token to use to sign request, if any. | ||
196 | * @param realm authorization realm | ||
197 | * @return reference to req | ||
198 | */ | ||
70 | http_request_t& prepare_request( | 199 | http_request_t& prepare_request( |
71 | http_request_t& req, | 200 | http_request_t& req, |
72 | const basic_fields& qf,const basic_fields& pf, | 201 | const basic_fields& qf,const basic_fields& pf, |
73 | oauth_method_t om,const string& sm, | 202 | oauth_method_t om,const string& sm, |
74 | const token_t *t=0,const string& realm=""); | 203 | const token_t *t=0,const string& realm=""); |
204 | /** | ||
205 | * Prepare http request parameters | ||
206 | * @param req request description to fill in | ||
207 | * @param qf query string parameters | ||
208 | * @param pf post body parameters | ||
209 | * @param sep service endpoint description | ||
210 | * @param t pointer to the token to use to sign request, if any. | ||
211 | * @param realm authorization realm | ||
212 | * @return reference to req | ||
213 | */ | ||
75 | http_request_t& prepare_request( | 214 | http_request_t& prepare_request( |
76 | http_request_t& req, | 215 | http_request_t& req, |
77 | const basic_fields& qf,const basic_fields& pf, | 216 | const basic_fields& qf,const basic_fields& pf, |
78 | const service_endpoint_t& sep, | 217 | const service_endpoint_t& sep, |
79 | const token_t *t=0,const string& realm=""); | 218 | const token_t *t=0,const string& realm=""); |
219 | /** | ||
220 | * Prepare http request parameters | ||
221 | * @param req request description to fill in | ||
222 | * @param qf query string parameters | ||
223 | * @param pf post body parameters | ||
224 | * @param t pointer to the token to use to sign request, if any. | ||
225 | * @param realm authorization realm | ||
226 | * @return reference to req | ||
227 | */ | ||
80 | http_request_t& prepare_request( | 228 | http_request_t& prepare_request( |
81 | http_request_t& req, | 229 | http_request_t& req, |
82 | const basic_fields& qf,const basic_fields& pf, | 230 | const basic_fields& qf,const basic_fields& pf, |
83 | const token_t *t=0,const string& realm=""); | 231 | const token_t *t=0,const string& realm=""); |
84 | 232 | ||
233 | /** | ||
234 | * Calculate request signature | ||
235 | * @param method http method | ||
236 | * @param url the url being invoked | ||
237 | * @param fields all request fields (query string, auth header, | ||
238 | * post body) | ||
239 | * @param rt pointer to the request token to be used for | ||
240 | * signing, if any. | ||
241 | */ | ||
85 | const string signature( | 242 | const string signature( |
86 | const string& method, | 243 | const string& method, |
87 | const string& url, | 244 | const string& url, |
88 | const basic_fields& fields, | 245 | const basic_fields& fields, |
89 | const token_t* rt=0); | 246 | const token_t* rt=0); |
90 | 247 | ||
248 | /** | ||
249 | * Acquire token from an OAuth provider | ||
250 | * @param sep service endpoint description | ||
251 | * @param rt pointer to the request token to use for signing, | ||
252 | * if any | ||
253 | * @return the acquired token | ||
254 | */ | ||
91 | token_t acquire_token( | 255 | token_t acquire_token( |
92 | const service_endpoint_t& sep, | 256 | const service_endpoint_t& sep, |
93 | const token_t* rt=0); | 257 | const token_t* rt=0); |
94 | }; | 258 | }; |
95 | 259 | ||
96 | class simple_provider_endpoints : public basic_provider_endpoints { | 260 | class simple_provider_endpoints : public basic_provider_endpoints { |
97 | public: | 261 | public: |
98 | service_endpoint_t sep_request_token; | 262 | service_endpoint_t sep_request_token; |
99 | service_endpoint_t sep_authorize_user; | 263 | service_endpoint_t sep_authorize_user; |
100 | service_endpoint_t sep_access_token; | 264 | service_endpoint_t sep_access_token; |
101 | service_endpoint_t sep_generic; | 265 | service_endpoint_t sep_generic; |
102 | 266 | ||
267 | /** | ||
268 | * @param rt request token endpoint URL | ||
269 | * @param au user authorization endpoint URL | ||
270 | * @param at access token endpoint URL | ||
271 | * @param sm signature method | ||
272 | * @param ams authentication method for service endpoints | ||
273 | * @param amr authentication method for resource access | ||
274 | */ | ||
103 | simple_provider_endpoints( | 275 | simple_provider_endpoints( |
104 | const string& rt,const string& au,const string& at, | 276 | const string& rt,const string& au,const string& at, |
105 | const string& sm, | 277 | const string& sm, |
106 | oauth_method_t ams=oauth_post_body, | 278 | oauth_method_t ams=oauth_post_body, |
107 | oauth_method_t amr=oauth_auth_header ) | 279 | oauth_method_t amr=oauth_auth_header ) |
108 | : sep_request_token(rt,sm,ams), | 280 | : sep_request_token(rt,sm,ams), |
109 | sep_authorize_user(au,sm,oauth_url_query), | 281 | sep_authorize_user(au,sm,oauth_url_query), |
110 | sep_access_token(at,sm,ams), | 282 | sep_access_token(at,sm,ams), |
111 | sep_generic("",sm,amr) { } | 283 | sep_generic("",sm,amr) { } |
112 | 284 | ||
113 | const service_endpoint_t& get_request_token_endpoint() const; | 285 | const service_endpoint_t& get_request_token_endpoint() const; |
114 | const service_endpoint_t& get_authorize_user_endpoint() const; | 286 | const service_endpoint_t& get_authorize_user_endpoint() const; |
115 | const service_endpoint_t& get_access_token_endpoint() const; | 287 | const service_endpoint_t& get_access_token_endpoint() const; |
116 | service_endpoint_t& get_url_endpoint(service_endpoint_t& sep, | 288 | service_endpoint_t& get_url_endpoint(service_endpoint_t& sep, |
117 | const string& url) const; | 289 | const string& url) const; |
118 | }; | 290 | }; |
119 | 291 | ||
120 | class simple_consumer : public basic_consumer { | 292 | class simple_consumer : public basic_consumer { |
121 | public: | 293 | public: |
122 | simple_provider_endpoints peps; | 294 | simple_provider_endpoints peps; |
123 | 295 | ||
296 | /** | ||
297 | * @param eps provider endpoints | ||
298 | * @param ct consumer token | ||
299 | * @see simple_provider_endpoints | ||
300 | * @see token_t | ||
301 | */ | ||
124 | simple_consumer(const simple_provider_endpoints& eps, | 302 | simple_consumer(const simple_provider_endpoints& eps, |
125 | const token_t& ct) | 303 | const token_t& ct) |
126 | : basic_consumer(ct), peps(eps) { } | 304 | : basic_consumer(ct), peps(eps) { } |
127 | 305 | ||
128 | const basic_provider_endpoints& get_endpoints() const; | 306 | const basic_provider_endpoints& get_endpoints() const; |
129 | const string allocate_nonce(time_t ts); | 307 | const string allocate_nonce(time_t ts); |
130 | }; | 308 | }; |
131 | 309 | ||
132 | } | 310 | } |
133 | } | 311 | } |
134 | 312 | ||
135 | #endif /* __OPKELE_OAUTH_CONSUMER_H */ | 313 | #endif /* __OPKELE_OAUTH_CONSUMER_H */ |