5 files changed, 134 insertions, 29 deletions

diff --git a/include/opkele/basic_op.h b/include/opkele/basic_op.h
index 5bba1bf..4daed02 100644
--- a/include/opkele/basic_op.h
+++ b/include/opkele/basic_op.h
@@ -10,3 +10,3 @@ namespace opkele {
 
-    class basic_op {
+    class basic_OP {
         public:
@@ -37,2 +37,10 @@ namespace opkele {
 
+            /** @name OpenID operations
+             * @{
+             */
+            /**
+             * Establish association with RP
+             * @param oum reply message
+             * @param inm request message
+             */
             basic_openid_message& associate(
@@ -41,6 +49,32 @@ namespace opkele {
 
+            /**
+             * 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,
@@ -48,2 +82,8 @@ namespace opkele {
                     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(
@@ -51,15 +91,80 @@ namespace opkele {
 
+            /**
+             * 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();
 
-            virtual assoc_t alloc_assoc(const string& t,size_t kl,bool sl) = 0;
-            virtual assoc_t retrieve_assoc(const string& h) = 0;
-
-            virtual string& alloc_nonce(string& nonce,bool sl) = 0;
+            /**
+             * @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
+             * @return association object
+             */
+            virtual assoc_t retrieve_assoc(const string& handle) = 0;
+            /**
+             * Allocate nonce.
+             * @param nonce input-output parameter containing timestamp part of
+             * the nonce on input
+             * @param sl true if the nonce is
+             * @return reference to nonce
+             * @throw failed_lookup if no such valid unexpired association
+             * could be retrieved
+             */
+            virtual string& alloc_nonce(string& nonce) = 0;
+            /**
+             * Check nonce validity
+             * @param nonce nonce to check
+             * @return true if nonce found and isn't yet invalidated
+             */
             virtual bool check_nonce(const string& nonce) = 0;
+            /**
+             * Invalidate nonce
+             * @param nonce nonce to check
+             */
             virtual void invalidate_nonce(const string& nonce) = 0;
-
+            /**
+             * @}
+             */
+
+            /**
+             * @name Site particulars API
+             * @{
+             */
+            /**
+             * Query the absolute URL of the op endpoint
+             * @return fully qualified url of the OP endpoint
+             */
             virtual const string get_op_endpoint() const = 0;
+            /**
+             * @}
+             */
 
diff --git a/include/opkele/verify_op.h b/include/opkele/verify_op.h
index f5c97b2..6c3c386 100644
--- a/include/opkele/verify_op.h
+++ b/include/opkele/verify_op.h
@@ -7,3 +7,3 @@ namespace opkele {
 
-    class verify_op : public basic_op {
+    class verify_op : public basic_OP {
         public:
diff --git a/lib/basic_op.cc b/lib/basic_op.cc
index 7a2dbd2..18446dc 100644
--- a/lib/basic_op.cc
+++ b/lib/basic_op.cc
@@ -12,3 +12,3 @@ namespace opkele {
 
-    void basic_op::reset_vars() {
+    void basic_OP::reset_vars() {
         assoc.reset();
@@ -19,6 +19,6 @@ namespace opkele {
 
-    bool basic_op::has_return_to() const {
+    bool basic_OP::has_return_to() const {
         return !return_to.empty();
     }
-    const string& basic_op::get_return_to() const {
+    const string& basic_OP::get_return_to() const {
         if(return_to.empty())
@@ -28,3 +28,3 @@ namespace opkele {
 
-    const string& basic_op::get_realm() const {
+    const string& basic_OP::get_realm() const {
         assert(!realm.empty());
@@ -33,6 +33,6 @@ namespace opkele {
 
-    bool basic_op::has_identity() const {
+    bool basic_OP::has_identity() const {
         return !identity.empty();
     }
-    const string& basic_op::get_claimed_id() const {
+    const string& basic_OP::get_claimed_id() const {
         if(claimed_id.empty())
@@ -42,3 +42,3 @@ namespace opkele {
     }
-    const string& basic_op::get_identity() const {
+    const string& basic_OP::get_identity() const {
         if(identity.empty())
@@ -49,3 +49,3 @@ namespace opkele {
 
-    bool basic_op::is_id_select() const {
+    bool basic_OP::is_id_select() const {
         return identity==IDURI_SELECT20;
@@ -53,6 +53,6 @@ namespace opkele {
 
-    void basic_op::select_identity(const string& c,const string& i) {
+    void basic_OP::select_identity(const string& c,const string& i) {
         claimed_id = c; identity = i;
     }
-    void basic_op::set_claimed_id(const string& c) {
+    void basic_OP::set_claimed_id(const string& c) {
         claimed_id = c;
@@ -60,3 +60,3 @@ namespace opkele {
 
-    basic_openid_message& basic_op::associate(
+    basic_openid_message& basic_OP::associate(
             basic_openid_message& oum,
@@ -133,3 +133,3 @@ namespace opkele {
 
-    void basic_op::checkid_(const basic_openid_message& inm,
+    void basic_OP::checkid_(const basic_openid_message& inm,
             extension_t *ext) {
@@ -195,3 +195,3 @@ namespace opkele {
 
-    basic_openid_message& basic_op::id_res(basic_openid_message& om,
+    basic_openid_message& basic_OP::id_res(basic_openid_message& om,
             extension_t *ext) {
@@ -220,3 +220,3 @@ namespace opkele {
         string nonce = w3timestr;
-        om.set_field("response_nonce",alloc_nonce(nonce,assoc->stateless()));
+        om.set_field("response_nonce",alloc_nonce(nonce));
         if(!invalidate_handle.empty()) {
@@ -232,3 +232,3 @@ namespace opkele {
 
-    basic_openid_message& basic_op::cancel(basic_openid_message& om) {
+    basic_openid_message& basic_OP::cancel(basic_openid_message& om) {
         assert(!return_to.empty());
@@ -239,3 +239,3 @@ namespace opkele {
 
-    basic_openid_message& basic_op::error(basic_openid_message& om,
+    basic_openid_message& basic_OP::error(basic_openid_message& om,
             const string& error,const string& contact,
@@ -251,3 +251,3 @@ namespace opkele {
 
-    basic_openid_message& basic_op::setup_needed(
+    basic_openid_message& basic_OP::setup_needed(
             basic_openid_message& oum,const basic_openid_message& inm) {
@@ -268,3 +268,3 @@ namespace opkele {
 
-    basic_openid_message& basic_op::check_authentication(
+    basic_openid_message& basic_OP::check_authentication(
             basic_openid_message& oum,
@@ -322,3 +322,3 @@ namespace opkele {
 
-    void basic_op::verify_return_to() {
+    void basic_OP::verify_return_to() {
         if(realm.find('#')!=string::npos)
diff --git a/lib/verify_op.cc b/lib/verify_op.cc
index e7c26b5..0beca2d 100644
--- a/lib/verify_op.cc
+++ b/lib/verify_op.cc
@@ -35,3 +35,3 @@ namespace opkele {
     void verify_op::verify_return_to() {
-        basic_op::verify_return_to();
+        basic_OP::verify_return_to();
         try {
diff --git a/test/OP.cc b/test/OP.cc
index c919d7f..ce54d92 100644
--- a/test/OP.cc
+++ b/test/OP.cc
@@ -163,3 +163,3 @@ class example_op_t : public opkele::verify_op {
 
-        string& alloc_nonce(string& nonce,bool stateless) {
+        string& alloc_nonce(string& nonce) {
             uuid_t uuid; uuid_generate(uuid);