Minor improvements

- almost irrelevant documentation updates
- introduced id_res_expired_on_delivery exception to be thrown if the
  association has expired right before it could've been used for signature
  verification.

Signed-off-by: Michael Krelin <hacker@klever.net>

3 files changed, 18 insertions, 3 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
@@ -66,8 +66,13 @@ namespace opkele {
 	     * The user is responsible for handling associations and this
 	     * function should never return an expired or invalidated
 	     * association.
 	     *
+	     * @note
+	     * It may be a good idea to pre-expire associations shortly before
+	     * their time is really up to avoid association expiry in the
+	     * middle of negotiations.
+	     *
 	     * @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
 	     */
@@ -136,8 +141,9 @@ namespace opkele {
 	     * @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 id_res_expired_on_delivery if the association expired before it could've been verified
 	     * @throw exception in case of other failures
 	     */
 	    virtual void id_res(const params_t& pin,const string& identity="",extension_t *ext=0);
 	    /**
diff --git a/include/opkele/exception.h b/include/opkele/exception.h
index 753a818..2ff44b7 100644
--- a/include/opkele/exception.h
+++ b/include/opkele/exception.h
@@ -169,8 +169,17 @@ namespace opkele {
 		: id_res_failed(OPKELE_E_CONS) { }
     };
 
     /**
+     * thrown if the association has expired before it could've been verified.
+     */
+    class id_res_expired_on_delivery : public id_res_failed {
+	public:
+	    id_res_expired_on_delivery(OPKELE_E_PARS)
+		: id_res_failed(OPKELE_E_CONS) { }
+    };
+
+    /**
      * openssl malfunction occured
      */
     class exception_openssl : public exception {
 	public:
diff --git a/lib/consumer.cc b/lib/consumer.cc
index 66db7dd..9f7530f 100644
--- a/lib/consumer.cc
+++ b/lib/consumer.cc
@@ -183,10 +183,10 @@ namespace opkele {
 	retrieve_links(identity.empty()?pin.get_param("openid.identity"):canonicalize(identity),server,delegate);
 	params_t ps;
 	try {
 	    assoc_t assoc = retrieve_assoc(server,pin.get_param("openid.assoc_handle"));
-	    if(assoc->is_expired()) /* TODO: or should I throw some other exception to force programmer fix his implementation? */
-		throw failed_lookup(OPKELE_CP_ "retrieve_assoc() has returned expired handle");
+	    if(assoc->is_expired())
+		throw id_res_expired_on_delivery(OPKELE_CP_ "retrieve_assoc() has returned expired handle");
 	    const string& sigenc = pin.get_param("openid.sig");
 	    vector<unsigned char> sig;
 	    util::decode_base64(sigenc,sig);
 	    const string& slist = pin.get_param("openid.signed");
@@ -213,9 +213,9 @@ namespace opkele {
 		    (const unsigned char *)kv.data(),kv.length(),
 		    0,&md_len);
 	    if(sig.size()!=md_len || memcmp(&(sig.front()),md,md_len))
 		throw id_res_mismatch(OPKELE_CP_ "signature mismatch");
-	}catch(failed_lookup& e) { /* XXX: more specific? */
+	}catch(failed_lookup& e) {
 	    const string& slist = pin.get_param("openid.signed");
 	    string::size_type pp = 0;
 	    params_t p;
 	    while(true) {