author | Michael Krelin <hacker@klever.net> | 2008-02-08 21:24:46 (UTC) |
---|---|---|
committer | Michael Krelin <hacker@klever.net> | 2008-02-08 21:24:46 (UTC) |
commit | 2e93c9940944edab87c29a2a13d60090f15fea86 (patch) (side-by-side diff) | |
tree | 06cfab5d2c67f0937039dfe52f252f168441b300 | |
parent | 6c82575a47283fcd7fdd0cf42b96e90a0888c58c (diff) | |
download | libopkele-2e93c9940944edab87c29a2a13d60090f15fea86.zip libopkele-2e93c9940944edab87c29a2a13d60090f15fea86.tar.gz libopkele-2e93c9940944edab87c29a2a13d60090f15fea86.tar.bz2 |
further doxygenation of basic_OP, extension_t and verify_OP
Signed-off-by: Michael Krelin <hacker@klever.net>
-rw-r--r-- | include/opkele/basic_op.h | 3 | ||||
-rw-r--r-- | include/opkele/extension.h | 8 | ||||
-rw-r--r-- | include/opkele/verify_op.h | 10 |
3 files changed, 21 insertions, 0 deletions
diff --git a/include/opkele/basic_op.h b/include/opkele/basic_op.h index a0f0af0..0e3231d 100644 --- a/include/opkele/basic_op.h +++ b/include/opkele/basic_op.h @@ -1,202 +1,205 @@ #ifndef __OPKELE_BASIC_OP_H #define __OPKELE_BASIC_OP_H #include <string> #include <opkele/types.h> #include <opkele/extension.h> namespace opkele { using std::string; + /** + * Implementation of basic OP functionality + */ class basic_OP { public: /** * The request mode for the request being processed */ mode_t mode; /** * association used in transaction. reset in case of dumb operation */ assoc_t assoc; /** * true if the request is openid2 request */ bool openid2; /** * The return_to RP endpoint */ string return_to; /** * The realm we authenticate for */ string realm; /** * Claimed identifier */ string claimed_id; /** * The OP-Local identifier */ string identity; /** * The invalidate handle for the reply request */ string invalidate_handle; void reset_vars(); /** * @name Request information access * Setting and retrieval of the information pertaining to the request being processed * @{ */ /** * Check if the RP expects us to get back to them. * @return true if RP supplied return_to URL */ bool has_return_to() const; /** * Find out where the RP is waiting for us. * @return the return_to URL supplied * @throw no_return_to if no return_to is supplied with the request */ const string& get_return_to() const; /** * Find out what realm we are authenticating user for * @return the realm */ const string& get_realm() const; /** * Check if request is about identity * @return true if so */ bool has_identity() const; /** * Get claimed identifier supplied with the request * @return claimed identifier * @throw non_identity if request is not about identity */ const string& get_claimed_id() const; /** * Get the identity (OP-Local identifier) being confirmed * @return identity * @throw non_identity if request is not about identity */ const string& get_identity() const; /** * Is identifier supposed to be selected on our side? * @return true if identity is a special identifier select URI */ bool is_id_select() const; /** * Select the identity for identifier select request * @param cid claimed identifier * @param lid local identifier */ void select_identity(const string& cid,const string& lid); /** * Set claimed identifier (for instance if it's supposed to have * fragment part) * @param cid claimed identifier */ void set_claimed_id(const string& cid); /** * @} */ /** @name OpenID operations * @{ */ /** * Establish association with RP * @param oum reply message * @param inm request message */ basic_openid_message& associate( basic_openid_message& oum, const basic_openid_message& inm); /** * Parse the checkid_* request. The function parses input message, * retrieves the information needed for further processing, * verifies what can be verified at this stage. * @param inm incoming OpenID message * @param ext extension/chain of extensions supported */ void checkid_(const basic_openid_message& inm,extension_t *ext=0); /** * Build and sign a positive assertion message * @param om outpu OpenID message * @param ext extension/chain of extensions supported * @return reference to om */ basic_openid_message& id_res(basic_openid_message& om, extension_t *ext=0); /** * Build a 'cancel' negative assertion * @param om output OpenID message * @return reference to om */ basic_openid_message& cancel(basic_openid_message& om); /** * Build an 'error' reply * @param om output OpenID message * @param error a human-readable message indicating the cause * @param contact contact address for the server administrator (can be empty) * @param reference a reference token (can be empty) * @return reference to om */ basic_openid_message& error(basic_openid_message& om, const string& error,const string& contact, const string& reference ); /** * Build a setup_needed reply to checkid_immediate request * @param oum output OpenID message * @param inm incoming OpenID request being processed * @return reference to oum */ basic_openid_message& setup_needed( basic_openid_message& oum,const basic_openid_message& inm); /** * Process check_authentication request * @param oum output OpenID message * @param inm incoming request * @return reference to oum */ basic_openid_message& check_authentication( basic_openid_message& oum,const basic_openid_message& inm); /** * @} */ /** * Verify return_to url. The default implementation checks whether * return_to URI matches the realm * @throw bad_realm in case of invalid realm * @throw bad_return_to if return_to doesn't match the realm * @see verify_op::verify_return_to() */ virtual void verify_return_to(); /** * @name Global persistent store API * These functions are related to the associations with RPs storage * and retrieval and nonce management. * @{ */ /** * Allocate association. * @param type association type * @param kl association key length * @param sl true if the association is stateless * @return association object */ virtual assoc_t alloc_assoc(const string& type,size_t kl,bool sl) = 0; /** * Retrieve valid unexpired association * @param handle association handle diff --git a/include/opkele/extension.h b/include/opkele/extension.h index 37bcb90..38f61e3 100644 --- a/include/opkele/extension.h +++ b/include/opkele/extension.h @@ -1,61 +1,69 @@ #ifndef __OPKELE_EXTENSION_H #define __OPKELE_EXTENSION_H /** * @file * @brief extensions framework basics */ #include <opkele/opkele-config.h> #include <opkele/types.h> namespace opkele { /** * OpenID extension hooks base class */ class extension_t { public: virtual ~extension_t() { } /** * hook called by RP before submitting the message to OP. * @param om openid message to be submit */ virtual void rp_checkid_hook(basic_openid_message& om); /** * hook called by RP after verifying information received from OP. * @param om openid message received * @param sp signed part of the message */ virtual void rp_id_res_hook(const basic_openid_message& om, const basic_openid_message& sp); /** * hook called by OP after parsing incoming message * @param inm message received from RP */ virtual void op_checkid_hook(const basic_openid_message& inm); /** * hook called by OP before signing the reply to RP * @param oum message to be sent to RP */ virtual void op_id_res_hook(basic_openid_message& oum); + /** + * @name deprecated hooks, used by the deprecated consumer_t and + * server_t implementations + * @{ + */ virtual void checkid_hook(basic_openid_message& om) OPKELE_DEPRECATE; virtual void id_res_hook(const basic_openid_message& om, const basic_openid_message& sp) OPKELE_DEPRECATE; virtual void checkid_hook(const basic_openid_message& inm,basic_openid_message& oum); + /** + * @} + */ /** * Casts the object to pointer to itself. For convenient passing * of pointer. */ operator extension_t*(void) { return this; } }; } #endif /* __OPKELE_EXTENSION_H */ diff --git a/include/opkele/verify_op.h b/include/opkele/verify_op.h index 6c3c386..6b94240 100644 --- a/include/opkele/verify_op.h +++ b/include/opkele/verify_op.h @@ -1,16 +1,26 @@ #ifndef __OPKELE_VERIFY_OP_H #define __OPKELE_VERIFY_OP_H #include <opkele/basic_op.h> namespace opkele { + /** + * The OP implementation that does discovery verification on RP + */ class verify_op : public basic_OP { public: + /** + * In addition to basic_OP::verify_return_to() functionality this + * implementation does the discovery on RP to see if return_to matches + * the realm + * @throw bad_return_to in case we fail to discover corresponding + * service endpoint + */ void verify_return_to(); }; } #endif /* __OPKELE_VERIFY_OP_H */ |