associations robustness improvements and documentation updates

3 files changed, 24 insertions, 1 deletions

diff --git a/include/opkele/association.h b/include/opkele/association.h
index a8f3915..72eff5b 100644
--- a/include/opkele/association.h
+++ b/include/opkele/association.h
@@ -1,68 +1,70 @@
 #ifndef __OPKELE_ASSOCIATION_H
 #define __OPKELE_ASSOCIATION_H
 
 #include <time.h>
 #include <opkele/types.h>
 
 /**
  * @file
  * @brief reference implementation of association_t
  */
 
 namespace opkele {
 
     /**
      * reference implementation of association_t class.
      */
     class association : public association_t {
         public:
             /**
              * OpenID server name
              */
             string _server;
             /**
              * association handle
              */
             string _handle;
             /**
              * association type
              */
             string _assoc_type;
             /**
              * the secret
              */
             secret_t _secret;
             /**
              * expiration time
              */
             time_t _expires;
             /**
              * statelessness of the assoc_handle
              */
             bool _stateless;
 
             /**
              * @param __server the server name
              * @param __handle association handle
              * @param __assoc_type association type
              * @param __secret the secret
              * @param __expires expiration time
              * @param __stateless statelessness of the assoc_handle
              */
             association(const string& __server, const string& __handle,
                     const string& __assoc_type, const secret_t& __secret,
                     time_t __expires, bool __stateless)
                 : _server(__server), _handle(__handle), _assoc_type(__assoc_type),
                 _secret(__secret), _expires(__expires), _stateless(__stateless) { }
 
             virtual string server() const { return _server; }
             virtual string handle() const { return _handle; }
             virtual string assoc_type() const { return _assoc_type; }
             virtual secret_t secret() const { return _secret; }
             virtual int expires_in() const { return _expires-time(0); }
             virtual bool stateless() const { return _stateless; }
+
+            virtual bool is_expired() const { return _expires<time(0); }
     };
 
 }
 
 #endif /* __OPKELE_ASSOCIATION_H */
diff --git a/include/opkele/consumer.h b/include/opkele/consumer.h
index 042e2d1..b9d1e54 100644
--- a/include/opkele/consumer.h
+++ b/include/opkele/consumer.h
@@ -1,149 +1,166 @@
 #ifndef __OPKELE_CONSUMER_H
 #define __OPKELE_CONSUMER_H
 
 #include <opkele/types.h>
 #include <opkele/extension.h>
 
 /**
  * @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:
 
             /**
              * 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 in case of error
+             * @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.
+             *
              * @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 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/lib/consumer.cc b/lib/consumer.cc
index dd8e150..af309c1 100644
--- a/lib/consumer.cc
+++ b/lib/consumer.cc
@@ -19,273 +19,277 @@ namespace opkele {
     class curl_t {
         public:
             CURL *_c;
 
             curl_t() : _c(0) { }
             curl_t(CURL *c) : _c(c) { }
             ~curl_t() throw() { if(_c) curl_easy_cleanup(_c); }
 
             curl_t& operator=(CURL *c) { if(_c) curl_easy_cleanup(_c); _c=c; return *this; }
 
             operator const CURL*(void) const { return _c; }
             operator CURL*(void) { return _c; }
     };
 
     static CURLcode curl_misc_sets(CURL* c) {
         CURLcode r;
         (r=curl_easy_setopt(c,CURLOPT_FOLLOWLOCATION,1))
         || (r=curl_easy_setopt(c,CURLOPT_MAXREDIRS,5))
         || (r=curl_easy_setopt(c,CURLOPT_DNS_CACHE_TIMEOUT,120))
         || (r=curl_easy_setopt(c,CURLOPT_DNS_USE_GLOBAL_CACHE,1))
         || (r=curl_easy_setopt(c,CURLOPT_USERAGENT,PACKAGE_NAME"/"PACKAGE_VERSION))
         || (r=curl_easy_setopt(c,CURLOPT_TIMEOUT,20))
         #ifdefDISABLE_CURL_SSL_VERIFYHOST
         || (r=curl_easy_setopt(c,CURLOPT_SSL_VERIFYHOST,0))
 #endif
         #ifdefDISABLE_CURL_SSL_VERIFYPEER
         || (r=curl_easy_setopt(c,CURLOPT_SSL_VERIFYPEER,0))
 #endif
         ;
         return r;
     }
 
     static size_t _curl_tostring(void *ptr,size_t size,size_t nmemb,void *stream) {
         string *str = (string*)stream;
         size_t bytes = size*nmemb;
         size_t get = min(16384-str->length(),bytes);
         str->append((const char*)ptr,get);
         return get;
     }
 
     assoc_t consumer_t::associate(const string& server) {
         util::dh_t dh = DH_new();
         if(!dh)
             throw exception_openssl(OPKELE_CP_ "failed to DH_new()");
         dh->p = util::dec_to_bignum(data::_default_p);
         dh->g = util::dec_to_bignum(data::_default_g);
         if(!DH_generate_key(dh))
             throw exception_openssl(OPKELE_CP_ "failed to DH_generate_key()");
         string request = 
             "openid.mode=associate"
             "&openid.assoc_type=HMAC-SHA1"
             "&openid.session_type=DH-SHA1"
             "&openid.dh_consumer_public=";
         request += util::url_encode(util::bignum_to_base64(dh->pub_key));
         curl_t curl = curl_easy_init();
         if(!curl)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_init()");
         string response;
         CURLcode r;
         (r=curl_misc_sets(curl))
         || (r=curl_easy_setopt(curl,CURLOPT_URL,server.c_str()))
         || (r=curl_easy_setopt(curl,CURLOPT_POST,1))
         || (r=curl_easy_setopt(curl,CURLOPT_POSTFIELDS,request.data()))
         || (r=curl_easy_setopt(curl,CURLOPT_POSTFIELDSIZE,request.length()))
         || (r=curl_easy_setopt(curl,CURLOPT_WRITEFUNCTION,_curl_tostring))
         || (r=curl_easy_setopt(curl,CURLOPT_WRITEDATA,&response))
         ;
         if(r)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_setopt()",r);
         if(r=curl_easy_perform(curl))
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_perform()",r);
         params_t p; p.parse_keyvalues(response);
         if(p.has_param("assoc_type") && p.get_param("assoc_type")!="HMAC-SHA1")
             throw bad_input(OPKELE_CP_ "unsupported assoc_type");
         string st;
         if(p.has_param("session_type")) st = p.get_param("session_type");
         if((!st.empty()) && st!="DH-SHA1")
             throw bad_input(OPKELE_CP_ "unsupported session_type");
         secret_t secret;
         if(st.empty()) {
             secret.from_base64(p.get_param("mac_key"));
         }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();
+            if(ah->is_expired()) /* TODO: or should I throw some other exception to force programmer fix his implementation? */
+                throw failed_lookup(OPKELE_CP_ "find_assoc() has returned expired 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");
             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? */
             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_t curl = curl_easy_init();
         if(!curl)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_init()");
         string response;
         CURLcode r;
         (r=curl_misc_sets(curl))
         || (r=curl_easy_setopt(curl,CURLOPT_URL,server.c_str()))
         || (r=curl_easy_setopt(curl,CURLOPT_POST,1))
         || (r=curl_easy_setopt(curl,CURLOPT_POSTFIELDS,request.data()))
         || (r=curl_easy_setopt(curl,CURLOPT_POSTFIELDSIZE,request.length()))
         || (r=curl_easy_setopt(curl,CURLOPT_WRITEFUNCTION,_curl_tostring))
         || (r=curl_easy_setopt(curl,CURLOPT_WRITEDATA,&response))
         ;
         if(r)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_setopt()",r);
         if(r=curl_easy_perform(curl))
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_perform()",r);
         params_t pp; pp.parse_keyvalues(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");
     }
 
     void consumer_t::retrieve_links(const string& url,string& server,string& delegate) {
         server.erase();
         delegate.erase();
         curl_t curl = curl_easy_init();
         if(!curl)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_init()");
         string html;
         CURLcode r;
         (r=curl_misc_sets(curl))
         || (r=curl_easy_setopt(curl,CURLOPT_URL,url.c_str()))
         || (r=curl_easy_setopt(curl,CURLOPT_WRITEFUNCTION,_curl_tostring))
         || (r=curl_easy_setopt(curl,CURLOPT_WRITEDATA,&html))
         ;
         if(r)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_setopt()",r);
         r = curl_easy_perform(curl);
         if(r && r!=CURLE_WRITE_ERROR)
             throw exception_curl(OPKELE_CP_ "failed to curl_easy_perform()",r);
         pcrepp::Pcre bre("<body\\b",PCRE_CASELESS);
         // strip out everything past body
         if(bre.search(html))
             html.erase(bre.get_match_start());
         pcrepp::Pcre hdre("<head[^>]*>",PCRE_CASELESS);
         if(!hdre.search(html))
             throw bad_input(OPKELE_CP_ "failed to find head");
         html.erase(0,hdre.get_match_end()+1);
         pcrepp::Pcre lre("<link\\b([^>]+)>",PCRE_CASELESS),
             rre("\\brel=['\"]([^'\"]+)['\"]",PCRE_CASELESS),
             hre("\\bhref=['\"]([^'\"]+)['\"]",PCRE_CASELESS);
         while(lre.search(html)) {
             string attrs = lre[0];