summaryrefslogtreecommitdiffabout
path: root/include/opkele/consumer.h
Unidiff
Diffstat (limited to 'include/opkele/consumer.h') (more/less context) (ignore whitespace changes)
-rw-r--r--include/opkele/consumer.h135
1 files changed, 135 insertions, 0 deletions
diff --git a/include/opkele/consumer.h b/include/opkele/consumer.h
new file mode 100644
index 0000000..b9c29bd
--- a/dev/null
+++ b/include/opkele/consumer.h
@@ -0,0 +1,135 @@
1#ifndef __OPKELE_CONSUMER_H
2#define __OPKELE_CONSUMER_H
3
4#include <opkele/types.h>
5
6/**
7 * @file
8 * @brief OpenID consumer-side functionality
9 */
10
11/**
12 * @brief the main opkele namespace
13 */
14namespace opkele {
15
16 /**
17 * implementation of basic consumer functionality
18 */
19 class consumer_t {
20 public:
21
22 /**
23 * store association. The function should be overridden in the real
24 * implementation to provide persistent associations store.
25 * @param server the OpenID server
26 * @param handle association handle
27 * @param secret the secret associated with the server and handle
28 * @param expires_in the number of seconds until the handle is expired
29 * @return the auto_ptr<> for the newly allocated association_t object
30 */
31 virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0;
32 /**
33 * retrieve stored association. The function should be overridden
34 * in the real implementation to provide persistent assocations
35 * store.
36 * @param server the OpenID server
37 * @param handle association handle
38 * @return the autho_ptr<> for the newly allocated association_t object
39 * @throw failed_lookup in case of error
40 */
41 virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0;
42 /**
43 * invalidate stored association. The function should be overridden
44 * in the real implementation of the consumer.
45 * @param server the OpenID server
46 * @param handle association handle
47 */
48 virtual void invalidate_assoc(const string& server,const string& handle) = 0;
49 /**
50 * retrieve any unexpired association for the server. If the
51 * function is not overridden in the real implementation, the new
52 * association will be established for each request.
53 * @param server the OpenID server
54 * @return the auto_ptr<> for the newly allocated association_t object
55 * @throw failed_lookup in case of absence of the handle
56 */
57 virtual assoc_t find_assoc(const string& server);
58
59 /**
60 * retrieve the metainformation contained in link tags from the
61 * page pointed by url. the function may implement caching of the
62 * information.
63 * @param url url to harvest for link tags
64 * @param server reference to the string object where to put
65 * openid.server value
66 * @param delegate reference to the string object where to put the
67 * openid.delegate value (if any)
68 */
69 virtual void retrieve_links(const string& url,string& server,string& delegate);
70
71 /**
72 * perform the associate request to OpenID server.
73 * @param server the OpenID server
74 * @return the auto_ptr<> for the newly allocated association_t
75 * object, representing established association
76 * @throw exception in case of error
77 */
78 assoc_t associate(const string& server);
79 /**
80 * prepare the parameters for the checkid_immediate
81 * request.
82 * @param identity the identity to verify
83 * @param return_to the return_to url to pass with the request
84 * @param trust_root the trust root to advertise with the request
85 * @return the location string
86 * @throw exception in case of error
87 */
88 string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="");
89 /**
90 * prepare the parameters for the checkid_setup
91 * request.
92 * @param identity the identity to verify
93 * @param return_to the return_to url to pass with the request
94 * @param trust_root the trust root to advertise with the request
95 * @return the location string
96 * @throw exception in case of error
97 */
98 string checkid_setup(const string& identity,const string& return_to,const string& trust_root="");
99 /**
100 * the actual implementation behind checkid_immediate() and
101 * checkid_setup() functions.
102 * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup
103 * @param identity the identity to verify
104 * @param return_to the return_to url to pass with the request
105 * @param trust_root the trust root to advertise with the request
106 * @return the location string
107 * @throw exception in case of error
108 */
109 string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="");
110 /**
111 * verify the id_res response
112 * @param pin the response parameters
113 * @param identity the identity being checked (if not specified, extracted
114 * from the openid.identity parameter
115 * @throw id_res_mismatch in case of signature
116 * mismatch
117 * @throw id_res_setup in case of
118 * openid.user_setup_url failure (supposedly
119 * checkid_immediate only)
120 * @throw id_res_failed in case of failure
121 * @throw exception in case of other failures
122 */
123 void id_res(const params_t& pin,const string& identity="");
124 /**
125 * perform a check_authentication request.
126 * @param server the OpenID server
127 * @param p request parameters
128 */
129 void check_authentication(const string& server,const params_t& p);
130
131 };
132
133}
134
135#endif /* __OPKELE_CONSUMER_H */