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
@@ -6,163 +6,169 @@
 
 /**
  * @file
  * @brief OpenID consumer-side functionality
  */
 
 namespace opkele {
 
     /**
      * implementation of basic consumer functionality
      *
      * @note
      * The consumer uses libcurl internally, which means that if you're using
      * libopkele in multithreaded environment you should call curl_global_init
      * yourself before spawning any threads.
      */
     class consumer_t {
 	public:
 
 	    virtual ~consumer_t() { }
 
 	    /**
 	     * 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.
 	     *
 	     * @note
 	     * The user is responsible for handling associations expiry and
 	     * this function should never return an expired or invalidated
 	     * association.
 	     *
 	     * @param server the OpenID server
 	     * @param handle association handle
 	     * @return the autho_ptr<> for the newly allocated association_t object
 	     * @throw failed_lookup if no unexpired association found
 	     */
 	    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.
 	     *
 	     * @note
 	     * 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
 	     */
 	    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
 	     */
 	    virtual 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
 	     */
 	    virtual 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
 	     */
 	    virtual 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 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);
 	    /**
 	     * perform a check_authentication request.
 	     * @param server the OpenID server
 	     * @param p request parameters
 	     */
 	    void check_authentication(const string& server,const params_t& p);
 
 	    /**
 	     * normalize URL by adding http:// and trailing slash if needed.
 	     * @param url
 	     * @return normalized url
 	     */
 	    static string normalize(const string& url);
 
 	    /**
 	     * Canonicalize URL, by normalizing its appearance and following redirects.
 	     * @param url
 	     * @return canonicalized url
 	     */
 	    virtual string canonicalize(const string& url);
 
     };
 
 }
 
 #endif /* __OPKELE_CONSUMER_H */
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
@@ -109,118 +109,127 @@ namespace opkele {
     /**
      * thrown on failed assertion
      */
     class failed_assertion : public exception {
 	public:
 	    failed_assertion(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
 
     /**
      * thrown if the handle being retrieved is invalid
      */
     class invalid_handle : public exception {
 	public:
 	    invalid_handle(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
     /**
      * thrown if the handle passed to check_authentication request is not
      * stateless
      */
     class stateful_handle : public exception {
 	public:
 	    stateful_handle(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
 
     /**
      * thrown if check_authentication request fails
      */
     class failed_check_authentication : public exception {
 	public:
 	    failed_check_authentication(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
 
     /**
      * thrown if the id_res request result is negative
      */
     class id_res_failed : public exception {
 	public:
 	    id_res_failed(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
     /**
      * thrown if the user_setup_url is provided with negative response
      */
     class id_res_setup : public id_res_failed {
 	public:
 	    string setup_url;
 	    id_res_setup(OPKELE_E_PARS,const string& su)
 		: id_res_failed(OPKELE_E_CONS), setup_url(su) { }
 	    ~id_res_setup() throw() { }
     };
     /**
      * thrown in case of signature mismatch
      */
     class id_res_mismatch : public id_res_failed {
 	public:
 	    id_res_mismatch(OPKELE_E_PARS)
 		: 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:
 	    unsigned long _error;
 	    string _ssl_string;
 	    exception_openssl(OPKELE_E_PARS);
 	    ~exception_openssl() throw() { }
     };
 
     /**
      * network operation related error occured
      */
     class exception_network : public exception {
 	public:
 	    exception_network(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
 
     /**
      * network operation related error occured, specifically, related to
      * libcurl
      */
     class exception_curl : public exception_network {
 	public:
 	    CURLcode _error;
 	    string _curl_string;
 	    exception_curl(OPKELE_E_PARS);
 	    exception_curl(OPKELE_E_PARS,CURLcode e);
 	    ~exception_curl() throw() { }
     };
 
     /**
      * not implemented (think pure virtual) member function executed, signfies
      * programmer error
      */
     class not_implemented : public exception {
 	public:
 	    not_implemented(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
 
     /**
      * internal error, indicates internal libopkele problem
      */
     class internal_error : public exception {
 	public:
 	    internal_error(OPKELE_E_PARS)
 		: exception(OPKELE_E_CONS) { }
     };
 
 }
 
 #endif /* __OPKELE_EXCEPTION_H */
diff --git a/lib/consumer.cc b/lib/consumer.cc
index 66db7dd..9f7530f 100644
--- a/lib/consumer.cc
+++ b/lib/consumer.cc
@@ -123,159 +123,159 @@ namespace opkele {
 	}else{
 	    util::bignum_t s_pub = util::base64_to_bignum(p.get_param("dh_server_public"));
 	    vector<unsigned char> ck(DH_size(dh)+1);
 	    unsigned char *ckptr = &(ck.front())+1;
 	    int cklen = DH_compute_key(ckptr,s_pub,dh);
 	    if(cklen<0)
 		throw exception_openssl(OPKELE_CP_ "failed to DH_compute_key()");
 	    if(cklen && (*ckptr)&0x80) {
 		(*(--ckptr)) = 0; ++cklen;
 	    }
 	    unsigned char key_sha1[SHA_DIGEST_LENGTH];
 	    SHA1(ckptr,cklen,key_sha1);
 	    secret.enxor_from_base64(key_sha1,p.get_param("enc_mac_key"));
 	}
 	int expires_in = 0;
 	if(p.has_param("expires_in")) {
 	    expires_in = util::string_to_long(p.get_param("expires_in"));
 	}else if(p.has_param("issued") && p.has_param("expiry")) {
 	    expires_in = util::w3c_to_time(p.get_param("expiry"))-util::w3c_to_time(p.get_param("issued"));
 	}else
 	    throw bad_input(OPKELE_CP_ "no expiration information");
 	return store_assoc(server,p.get_param("assoc_handle"),secret,expires_in);
     }
 
     string consumer_t::checkid_immediate(const string& identity,const string& return_to,const string& trust_root,extension_t *ext) {
 	return checkid_(mode_checkid_immediate,identity,return_to,trust_root,ext);
     }
     string consumer_t::checkid_setup(const string& identity,const string& return_to,const string& trust_root,extension_t *ext) {
 	return checkid_(mode_checkid_setup,identity,return_to,trust_root,ext);
     }
     string consumer_t::checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root,extension_t *ext) {
 	params_t p;
 	if(mode==mode_checkid_immediate)
 	    p["mode"]="checkid_immediate";
 	else if(mode==mode_checkid_setup)
 	    p["mode"]="checkid_setup";
 	else
 	    throw bad_input(OPKELE_CP_ "unknown checkid_* mode");
 	string iurl = canonicalize(identity);
 	string server, delegate;
 	retrieve_links(iurl,server,delegate);
 	p["identity"] = delegate.empty()?iurl:delegate;
 	if(!trust_root.empty())
 	    p["trust_root"] = trust_root;
 	p["return_to"] = return_to;
 	try {
 	    string ah = find_assoc(server)->handle();
 	    p["assoc_handle"] = ah;
 	}catch(failed_lookup& fl) {
 	    string ah = associate(server)->handle();
 	    p["assoc_handle"] = ah;
 	}
 	if(ext) ext->checkid_hook(p,identity);
 	return p.append_query(server);
     }
 
     void consumer_t::id_res(const params_t& pin,const string& identity,extension_t *ext) {
 	if(pin.has_param("openid.user_setup_url"))
 	    throw id_res_setup(OPKELE_CP_ "assertion failed, setup url provided",pin.get_param("openid.user_setup_url"));
 	string server,delegate;
 	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");
 	    string kv;
 	    string::size_type p = 0;
 	    while(true) {
 		string::size_type co = slist.find(',',p);
 		string f = (co==string::npos)?slist.substr(p):slist.substr(p,co-p);
 		kv += f;
 		kv += ':';
 		f.insert(0,"openid.");
 		kv += pin.get_param(f);
 		kv += '\n';
 		if(ext) ps[f.substr(sizeof("openid.")-1)] = pin.get_param(f);
 		if(co==string::npos)
 		    break;
 		p = co+1;
 	    }
 	    secret_t secret = assoc->secret();
 	    unsigned int md_len = 0;
 	    unsigned char *md = HMAC(
 		    EVP_sha1(),
 		    &(secret.front()),secret.size(),
 		    (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) {
 		string::size_type co = slist.find(',',pp);
 		string f = "openid.";
 		f += (co==string::npos)?slist.substr(pp):slist.substr(pp,co-pp);
 		p[f] = pin.get_param(f);
 		if(co==string::npos)
 		    break;
 		pp = co+1;
 	    }
 	    p["openid.assoc_handle"] = pin.get_param("openid.assoc_handle");
 	    p["openid.sig"] = pin.get_param("openid.sig");
 	    p["openid.signed"] = pin.get_param("openid.signed");
 	    try {
 		string ih = pin.get_param("openid.invalidate_handle");
 		p["openid.invalidate_handle"] = ih;
 	    }catch(failed_lookup& fl) { }
 	    try {
 		check_authentication(server,p);
 	    }catch(failed_check_authentication& fca) {
 		throw id_res_failed(OPKELE_CP_ "failed to check_authentication()");
 	    }
 	}
 	if(ext) ext->id_res_hook(pin,ps,identity);
     }
 
     void consumer_t::check_authentication(const string& server,const params_t& p) {
 	string request = "openid.mode=check_authentication";
 	for(params_t::const_iterator i=p.begin();i!=p.end();++i) {
 	    if(i->first!="openid.mode") {
 		request += '&';
 		request += i->first;
 		request += '=';
 		request += util::url_encode(i->second);
 	    }
 	}
 	curl_pick_t curl = curl_pick_t::easy_init();
 	if(!curl)
 	    throw exception_curl(OPKELE_CP_ "failed to initialize curl");
 	CURLcode r;
 	(r=curl.misc_sets())
 	|| (r=curl.easy_setopt(CURLOPT_URL,server.c_str()))
 	|| (r=curl.easy_setopt(CURLOPT_POST,1))
 	|| (r=curl.easy_setopt(CURLOPT_POSTFIELDS,request.data()))
 	|| (r=curl.easy_setopt(CURLOPT_POSTFIELDSIZE,request.length()))
 	|| (r=curl.set_write())
 	;
 	if(r)
 	    throw exception_curl(OPKELE_CP_ "failed to set curly options",r);
 	if( (r=curl.easy_perform()) )
 	    throw exception_curl(OPKELE_CP_ "failed to perform curly request",r);
 	params_t pp; pp.parse_keyvalues(curl.response);
 	if(pp.has_param("invalidate_handle"))
 	    invalidate_assoc(server,pp.get_param("invalidate_handle"));
 	if(pp.has_param("is_valid")) {
 	    if(pp.get_param("is_valid")=="true")
 		return;
 	}else if(pp.has_param("lifetime")) {
 	    if(util::string_to_long(pp.get_param("lifetime")))
 		return;
 	}
 	throw failed_check_authentication(OPKELE_CP_ "failed to verify response");