summaryrefslogtreecommitdiffabout
path: root/include/opkele/consumer.h
blob: f9939cff630092696c7db49225534c4d023979ad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
#ifndef __OPKELE_CONSUMER_H
#define __OPKELE_CONSUMER_H

#include <opkele/types.h>
#include <opkele/extension.h>

/**
 * @file
 * @brief OpenID consumer-side functionality
 */

/**
 * @brief the main opkele namespace
 */
namespace opkele {

    /**
     * implementation of basic consumer functionality
     */
    class consumer_t {
	public:

	    /**
	     * store association. The function should be overridden in the real
	     * implementation to provide persistent associations store.
	     * @param server the OpenID server
	     * @param handle association handle
	     * @param secret the secret associated with the server and handle
	     * @param expires_in the number of seconds until the handle is expired
	     * @return the auto_ptr<> for the newly allocated association_t object
	     */
	    virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0;
	    /**
	     * retrieve stored association. The function should be overridden
	     * in the real implementation to provide persistent assocations
	     * store.
	     * @param server the OpenID server
	     * @param handle association handle
	     * @return the autho_ptr<> for the newly allocated association_t object
	     * @throw failed_lookup in case of error
	     */
	    virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0;
	    /**
	     * invalidate stored association. The function should be overridden
	     * in the real implementation of the consumer.
	     * @param server the OpenID server
	     * @param handle association handle
	     */
	    virtual void invalidate_assoc(const string& server,const string& handle) = 0;
	    /**
	     * retrieve any unexpired association for the server. If the
	     * function is not overridden in the real implementation, the new
	     * association will be established for each request.
	     * @param server the OpenID server
	     * @return the auto_ptr<> for the newly allocated association_t object
	     * @throw failed_lookup in case of absence of the handle
	     */
	    virtual assoc_t find_assoc(const string& server);

	    /**
	     * retrieve the metainformation contained in link tags from the
	     * page pointed by url. the function may implement caching of the
	     * information.
	     * @param url url to harvest for link tags
	     * @param server reference to the string object where to put
	     * openid.server value
	     * @param delegate reference to the string object where to put the
	     * openid.delegate value (if any)
	     */
	    virtual void retrieve_links(const string& url,string& server,string& delegate);

	    /**
	     * perform the associate request to OpenID server.
	     * @param server the OpenID server
	     * @return the auto_ptr<> for the newly allocated association_t
	     * object, representing established association
	     * @throw exception in case of error
	     */
	    assoc_t associate(const string& server);
	    /**
	     * prepare the parameters for the checkid_immediate
	     * request.
	     * @param identity the identity to verify
	     * @param return_to the return_to url to pass with the request
	     * @param trust_root the trust root to advertise with the request
	     * @param ext pointer to an extension(s) hooks object
	     * @return the location string
	     * @throw exception in case of error
	     */
	    string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0);
	    /**
	     * prepare the parameters for the checkid_setup
	     * request.
	     * @param identity the identity to verify
	     * @param return_to the return_to url to pass with the request
	     * @param trust_root the trust root to advertise with the request
	     * @param ext pointer to an extension(s) hooks object
	     * @return the location string
	     * @throw exception in case of error
	     */
	    string checkid_setup(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0);
	    /**
	     * the actual implementation behind checkid_immediate() and
	     * checkid_setup() functions.
	     * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup
	     * @param identity the identity to verify
	     * @param return_to the return_to url to pass with the request
	     * @param trust_root the trust root to advertise with the request
	     * @param ext pointer to an extension(s) hooks object
	     * @return the location string
	     * @throw exception in case of error
	     */
	    string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0);
	    /**
	     * verify the id_res response
	     * @param pin the response parameters
	     * @param identity the identity being checked (if not specified,
	     * @param ext pointer to an extension(s) hooks object
	     * extracted from the openid.identity parameter
	     * @throw id_res_mismatch in case of signature mismatch
	     * @throw id_res_setup in case of openid.user_setup_url failure
	     * (supposedly checkid_immediate only)
	     * @throw id_res_failed in case of failure
	     * @throw exception in case of other failures
	     */
	    void id_res(const params_t& pin,const string& identity="",extension_t *ext=0);
	    /**
	     * perform a check_authentication request.
	     * @param server the OpenID server
	     * @param p request parameters
	     */
	    void check_authentication(const string& server,const params_t& p);

	    /**
	     * make URL canonical, by adding http:// and trailing slash, if needed.
	     * @param url
	     * @return canonicalized url
	     */
	    static string canonicalize(const string& url);

    };

}

#endif /* __OPKELE_CONSUMER_H */