-rw-r--r-- | include/opkele/consumer.h | 6 |
1 files changed, 6 insertions, 0 deletions
diff --git a/include/opkele/consumer.h b/include/opkele/consumer.h index 50ff692..c463787 100644 --- a/include/opkele/consumer.h +++ b/include/opkele/consumer.h | |||
@@ -6,163 +6,169 @@ | |||
6 | 6 | ||
7 | /** | 7 | /** |
8 | * @file | 8 | * @file |
9 | * @brief OpenID consumer-side functionality | 9 | * @brief OpenID consumer-side functionality |
10 | */ | 10 | */ |
11 | 11 | ||
12 | namespace opkele { | 12 | namespace opkele { |
13 | 13 | ||
14 | /** | 14 | /** |
15 | * implementation of basic consumer functionality | 15 | * implementation of basic consumer functionality |
16 | * | 16 | * |
17 | * @note | 17 | * @note |
18 | * The consumer uses libcurl internally, which means that if you're using | 18 | * The consumer uses libcurl internally, which means that if you're using |
19 | * libopkele in multithreaded environment you should call curl_global_init | 19 | * libopkele in multithreaded environment you should call curl_global_init |
20 | * yourself before spawning any threads. | 20 | * yourself before spawning any threads. |
21 | */ | 21 | */ |
22 | class consumer_t { | 22 | class consumer_t { |
23 | public: | 23 | public: |
24 | 24 | ||
25 | virtual ~consumer_t() { } | 25 | virtual ~consumer_t() { } |
26 | 26 | ||
27 | /** | 27 | /** |
28 | * store association. The function should be overridden in the real | 28 | * store association. The function should be overridden in the real |
29 | * implementation to provide persistent associations store. | 29 | * implementation to provide persistent associations store. |
30 | * @param server the OpenID server | 30 | * @param server the OpenID server |
31 | * @param handle association handle | 31 | * @param handle association handle |
32 | * @param secret the secret associated with the server and handle | 32 | * @param secret the secret associated with the server and handle |
33 | * @param expires_in the number of seconds until the handle is expired | 33 | * @param expires_in the number of seconds until the handle is expired |
34 | * @return the auto_ptr<> for the newly allocated association_t object | 34 | * @return the auto_ptr<> for the newly allocated association_t object |
35 | */ | 35 | */ |
36 | virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0; | 36 | virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0; |
37 | /** | 37 | /** |
38 | * retrieve stored association. The function should be overridden | 38 | * retrieve stored association. The function should be overridden |
39 | * in the real implementation to provide persistent assocations | 39 | * in the real implementation to provide persistent assocations |
40 | * store. | 40 | * store. |
41 | * | 41 | * |
42 | * @note | 42 | * @note |
43 | * The user is responsible for handling associations expiry and | 43 | * The user is responsible for handling associations expiry and |
44 | * this function should never return an expired or invalidated | 44 | * this function should never return an expired or invalidated |
45 | * association. | 45 | * association. |
46 | * | 46 | * |
47 | * @param server the OpenID server | 47 | * @param server the OpenID server |
48 | * @param handle association handle | 48 | * @param handle association handle |
49 | * @return the autho_ptr<> for the newly allocated association_t object | 49 | * @return the autho_ptr<> for the newly allocated association_t object |
50 | * @throw failed_lookup if no unexpired association found | 50 | * @throw failed_lookup if no unexpired association found |
51 | */ | 51 | */ |
52 | virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0; | 52 | virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0; |
53 | /** | 53 | /** |
54 | * invalidate stored association. The function should be overridden | 54 | * invalidate stored association. The function should be overridden |
55 | * in the real implementation of the consumer. | 55 | * in the real implementation of the consumer. |
56 | * @param server the OpenID server | 56 | * @param server the OpenID server |
57 | * @param handle association handle | 57 | * @param handle association handle |
58 | */ | 58 | */ |
59 | virtual void invalidate_assoc(const string& server,const string& handle) = 0; | 59 | virtual void invalidate_assoc(const string& server,const string& handle) = 0; |
60 | /** | 60 | /** |
61 | * retrieve any unexpired association for the server. If the | 61 | * retrieve any unexpired association for the server. If the |
62 | * function is not overridden in the real implementation, the new | 62 | * function is not overridden in the real implementation, the new |
63 | * association will be established for each request. | 63 | * association will be established for each request. |
64 | * | 64 | * |
65 | * @note | 65 | * @note |
66 | * The user is responsible for handling associations and this | 66 | * The user is responsible for handling associations and this |
67 | * function should never return an expired or invalidated | 67 | * function should never return an expired or invalidated |
68 | * association. | 68 | * association. |
69 | * | 69 | * |
70 | * @note | ||
71 | * It may be a good idea to pre-expire associations shortly before | ||
72 | * their time is really up to avoid association expiry in the | ||
73 | * middle of negotiations. | ||
74 | * | ||
70 | * @param server the OpenID server | 75 | * @param server the OpenID server |
71 | * @return the auto_ptr<> for the newly allocated association_t object | 76 | * @return the auto_ptr<> for the newly allocated association_t object |
72 | * @throw failed_lookup in case of absence of the handle | 77 | * @throw failed_lookup in case of absence of the handle |
73 | */ | 78 | */ |
74 | virtual assoc_t find_assoc(const string& server); | 79 | virtual assoc_t find_assoc(const string& server); |
75 | 80 | ||
76 | /** | 81 | /** |
77 | * retrieve the metainformation contained in link tags from the | 82 | * retrieve the metainformation contained in link tags from the |
78 | * page pointed by url. the function may implement caching of the | 83 | * page pointed by url. the function may implement caching of the |
79 | * information. | 84 | * information. |
80 | * @param url url to harvest for link tags | 85 | * @param url url to harvest for link tags |
81 | * @param server reference to the string object where to put | 86 | * @param server reference to the string object where to put |
82 | * openid.server value | 87 | * openid.server value |
83 | * @param delegate reference to the string object where to put the | 88 | * @param delegate reference to the string object where to put the |
84 | * openid.delegate value (if any) | 89 | * openid.delegate value (if any) |
85 | */ | 90 | */ |
86 | virtual void retrieve_links(const string& url,string& server,string& delegate); | 91 | virtual void retrieve_links(const string& url,string& server,string& delegate); |
87 | 92 | ||
88 | /** | 93 | /** |
89 | * perform the associate request to OpenID server. | 94 | * perform the associate request to OpenID server. |
90 | * @param server the OpenID server | 95 | * @param server the OpenID server |
91 | * @return the auto_ptr<> for the newly allocated association_t | 96 | * @return the auto_ptr<> for the newly allocated association_t |
92 | * object, representing established association | 97 | * object, representing established association |
93 | * @throw exception in case of error | 98 | * @throw exception in case of error |
94 | */ | 99 | */ |
95 | assoc_t associate(const string& server); | 100 | assoc_t associate(const string& server); |
96 | /** | 101 | /** |
97 | * prepare the parameters for the checkid_immediate | 102 | * prepare the parameters for the checkid_immediate |
98 | * request. | 103 | * request. |
99 | * @param identity the identity to verify | 104 | * @param identity the identity to verify |
100 | * @param return_to the return_to url to pass with the request | 105 | * @param return_to the return_to url to pass with the request |
101 | * @param trust_root the trust root to advertise with the request | 106 | * @param trust_root the trust root to advertise with the request |
102 | * @param ext pointer to an extension(s) hooks object | 107 | * @param ext pointer to an extension(s) hooks object |
103 | * @return the location string | 108 | * @return the location string |
104 | * @throw exception in case of error | 109 | * @throw exception in case of error |
105 | */ | 110 | */ |
106 | virtual string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); | 111 | virtual string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); |
107 | /** | 112 | /** |
108 | * prepare the parameters for the checkid_setup | 113 | * prepare the parameters for the checkid_setup |
109 | * request. | 114 | * request. |
110 | * @param identity the identity to verify | 115 | * @param identity the identity to verify |
111 | * @param return_to the return_to url to pass with the request | 116 | * @param return_to the return_to url to pass with the request |
112 | * @param trust_root the trust root to advertise with the request | 117 | * @param trust_root the trust root to advertise with the request |
113 | * @param ext pointer to an extension(s) hooks object | 118 | * @param ext pointer to an extension(s) hooks object |
114 | * @return the location string | 119 | * @return the location string |
115 | * @throw exception in case of error | 120 | * @throw exception in case of error |
116 | */ | 121 | */ |
117 | virtual string checkid_setup(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); | 122 | virtual string checkid_setup(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); |
118 | /** | 123 | /** |
119 | * the actual implementation behind checkid_immediate() and | 124 | * the actual implementation behind checkid_immediate() and |
120 | * checkid_setup() functions. | 125 | * checkid_setup() functions. |
121 | * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup | 126 | * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup |
122 | * @param identity the identity to verify | 127 | * @param identity the identity to verify |
123 | * @param return_to the return_to url to pass with the request | 128 | * @param return_to the return_to url to pass with the request |
124 | * @param trust_root the trust root to advertise with the request | 129 | * @param trust_root the trust root to advertise with the request |
125 | * @param ext pointer to an extension(s) hooks object | 130 | * @param ext pointer to an extension(s) hooks object |
126 | * @return the location string | 131 | * @return the location string |
127 | * @throw exception in case of error | 132 | * @throw exception in case of error |
128 | */ | 133 | */ |
129 | virtual string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); | 134 | virtual string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); |
130 | /** | 135 | /** |
131 | * verify the id_res response | 136 | * verify the id_res response |
132 | * @param pin the response parameters | 137 | * @param pin the response parameters |
133 | * @param identity the identity being checked (if not specified, | 138 | * @param identity the identity being checked (if not specified, |
134 | * @param ext pointer to an extension(s) hooks object | 139 | * @param ext pointer to an extension(s) hooks object |
135 | * extracted from the openid.identity parameter | 140 | * extracted from the openid.identity parameter |
136 | * @throw id_res_mismatch in case of signature mismatch | 141 | * @throw id_res_mismatch in case of signature mismatch |
137 | * @throw id_res_setup in case of openid.user_setup_url failure | 142 | * @throw id_res_setup in case of openid.user_setup_url failure |
138 | * (supposedly checkid_immediate only) | 143 | * (supposedly checkid_immediate only) |
139 | * @throw id_res_failed in case of failure | 144 | * @throw id_res_failed in case of failure |
145 | * @throw id_res_expired_on_delivery if the association expired before it could've been verified | ||
140 | * @throw exception in case of other failures | 146 | * @throw exception in case of other failures |
141 | */ | 147 | */ |
142 | virtual void id_res(const params_t& pin,const string& identity="",extension_t *ext=0); | 148 | virtual void id_res(const params_t& pin,const string& identity="",extension_t *ext=0); |
143 | /** | 149 | /** |
144 | * perform a check_authentication request. | 150 | * perform a check_authentication request. |
145 | * @param server the OpenID server | 151 | * @param server the OpenID server |
146 | * @param p request parameters | 152 | * @param p request parameters |
147 | */ | 153 | */ |
148 | void check_authentication(const string& server,const params_t& p); | 154 | void check_authentication(const string& server,const params_t& p); |
149 | 155 | ||
150 | /** | 156 | /** |
151 | * normalize URL by adding http:// and trailing slash if needed. | 157 | * normalize URL by adding http:// and trailing slash if needed. |
152 | * @param url | 158 | * @param url |
153 | * @return normalized url | 159 | * @return normalized url |
154 | */ | 160 | */ |
155 | static string normalize(const string& url); | 161 | static string normalize(const string& url); |
156 | 162 | ||
157 | /** | 163 | /** |
158 | * Canonicalize URL, by normalizing its appearance and following redirects. | 164 | * Canonicalize URL, by normalizing its appearance and following redirects. |
159 | * @param url | 165 | * @param url |
160 | * @return canonicalized url | 166 | * @return canonicalized url |
161 | */ | 167 | */ |
162 | virtual string canonicalize(const string& url); | 168 | virtual string canonicalize(const string& url); |
163 | 169 | ||
164 | }; | 170 | }; |
165 | 171 | ||
166 | } | 172 | } |
167 | 173 | ||
168 | #endif /* __OPKELE_CONSUMER_H */ | 174 | #endif /* __OPKELE_CONSUMER_H */ |