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.h6
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
12namespace opkele { 12namespace 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 */