ruby-openid 1.1.4 → 2.0.1

data/lib/openid/server.rb

@@ -1,960 +1,1509 @@
+
+require 'openid/cryptutil'
 require 'openid/util'
-require 'openid/association'
 require 'openid/dh'
+require 'openid/store/nonce'
 require 'openid/trustroot'
+require 'openid/association'
+require 'openid/message'
+
+require 'time'
 
 module OpenID
 
-  # This module contains classes specific to implemeting an OpenID
-  # server.
-  #
-  # ==Overview
-  #
-  # An OpenID server must perform three tasks:
-  #
-  #   1. Examine the incoming request to determine its nature and validity.
-  #
-  #   2. Make a decision about how to respond to this request.
-  #
-  #   3. Format the response according to the protocol.
-  #
-  # The first and last of these tasks may performed by
-  # the Server.decode_request and Server.encode_response methods of the
-  # OpenID::Server::Server object.  Who gets to do the intermediate task --
-  # deciding how to respond to the request -- will depend on what type of
-  # request it is.
-  #
-  # If it's a request to authenticate a user (a checkid_setup or
-  # checkid_immediate request), you need to decide if you will assert
-  # that this user may claim the identity in question.  Exactly how you do
-  # that is a matter of application policy, but it generally involves making
-  # sure the user has an account with your system and is logged in, checking
-  # to see if that identity is hers to claim, and verifying with the user that
-  # she does consent to releasing that information to the party making the
-  # request.  Do this by examining the properties of the CheckIDRequest
-  # object, and when you've come to a decision, form a response by calling
-  # CheckIDRequest.answer.
-  #
-  # Other types of requests relate to establishing associations between client
-  # and server and verifing the authenticity of previous communications.
-  # Server contains all the logic and data necessary to respond to
-  # such requests; just pass it to Server.handle_request.
-  #
-  #
-  # ==OpenID Extensions
-  # 
-  # Do you want to provide other information for your users
-  # in addition to authentication?  Version 1.2 of the OpenID
-  # protocol allows consumers to add extensions to their requests.
-  # For example, with sites using the Simple Registration Extension
-  # http://www.openidenabled.com/openid/simple-registration-extension/,
-  # a user can agree to have their nickname and e-mail address sent to a
-  # site when they sign up.
-  #
-  # Since extensions do not change the way OpenID authentication works,
-  # code to handle extension requests may be completely separate from the
-  # OpenIDRequest class here.  But you'll likely want data sent back by
-  # your extension to be signed.  OpenIDResponse provides methods with
-  # which you can add data to it which can be signed with the other data in
-  # the OpenID signature.
-  #
-  # For example when request is a checkid_* request:
-  #   
-  #   response = request.answer(true)
-  #   # this will add a signed 'openid.sreg.timezone' parameter to the response
-  #   response.add_field('sreg', 'timezone', 'America/Los_Angeles')
-  #
-  #
-  # ==Stores
-  #
-  # The OpenID server needs to maintain state between requests in order
-  # to function.  Its mechanism for doing this is called a store.  The
-  # store interface is defined in OpenID::Store.
-  # Additionally, several concrete store implementations are provided, so that
-  # most sites won't need to implement a custom store.  For a store backed
-  # by flat files on disk, see OpenID::FilesystemStore.
-  # 
-  # ==Upgrading
-  #
-  # The keys by which a server looks up associations in its store have changed
-  # in version 1.2 of this library.  If your store has entries created from
-  # version 1.0 code, you should empty it.
   module Server
-       
-    HTTP_REDIRECT = 302
+
     HTTP_OK = 200
+    HTTP_REDIRECT = 302
     HTTP_ERROR = 400
-    
+
     BROWSER_REQUEST_MODES = ['checkid_setup', 'checkid_immediate']
-    OPENID_PREFIX = 'openid.'
 
     ENCODE_KVFORM = ['kvform'].freeze
     ENCODE_URL = ['URL/redirect'].freeze
+    ENCODE_HTML_FORM = ['HTML form'].freeze
+
+    UNUSED = nil
 
-    # Represents an incoming OpenID request.
     class OpenIDRequest
-      
-      attr_reader :mode
+      attr_accessor :namespace, :message, :mode
 
-      # +mode+ is the corresponsing "openid.mode" value of the request,
-      # and is available through the +mode+ method.
-      def initialize(mode)
-        @mode = mode
+      # I represent an incoming OpenID request.
+      #
+      # Attributes:
+      # mode:: The "openid.mode" of this request
+      def initialize
+        @mode = nil
       end
-
     end
 
     # A request to verify the validity of a previous response.
+    #
+    # See OpenID Specs, Verifying Directly with the OpenID Provider
+    # <http://openid.net/specs/openid-authentication-2_0-12.html#verifying_signatures>
     class CheckAuthRequest < OpenIDRequest
-      
-      attr_accessor :assoc_handle, :sig, :signed, :invalidate_handle
 
-      # Create a new CheckAuthRequest. Please see the
-      # CheckAuthRequest.from_query class method, as it is the preferred
-      # way to produce this object.
-      #
-      # ==Parameters
-      #
-      # [+assoc_handle+]
-      #   String value of the "openid.assoc_handle" from the incoming request
-      #
-      # [+sig+]
-      #   String signature for the request. This is "openid.sig"
+      # The association handle the response was signed with.
+      attr_accessor :assoc_handle
+
+      # The message with the signature which wants checking.
+      attr_accessor :signed
+
+      # An association handle the client is asking about the validity
+      # of. May be nil.
+      attr_accessor :invalidate_handle
+
+      attr_accessor :sig
+
+      # Construct me.
       #
-      # [+signed+]
-      #   An array of pairs of [key, value], where key is the signed paramter
-      #   name without the "openid." prefix.  Value is the String value of 
-      #   of the paramter.
+      # These parameters are assigned directly as class attributes.
       #
-      # [+invalidate_handle+]
-      #   Optional. The association handle that the consumer is asking about
-      #   the validity of.  May be nil.
-      def initialize(assoc_handle, sig, signed, invalidate_handle=nil)
-        super('check_authentication')
+      # Parameters:
+      # assoc_handle:: the association handle for this request
+      # signed:: The signed message
+      # invalidate_handle:: An association handle that the relying
+      #                     party is checking to see if it is invalid
+      def initialize(assoc_handle, signed, invalidate_handle=nil)
+        super()
+
+        @mode = "check_authentication"
+        @required_fields = ["identity", "return_to", "response_nonce"].freeze
+
+        @sig = nil
         @assoc_handle = assoc_handle
-        @sig = sig
         @signed = signed
         @invalidate_handle = invalidate_handle
+        @namespace = OPENID2_NS
       end
 
-      # Produce a CheckAuthRequest instance from the request query.  Raises
-      # a ProtocolError if the request is malformed, and returns an instance
-      # CheckAuthRequest on success.
-      def CheckAuthRequest.from_query(query)       
-        assoc_handle = query['openid.assoc_handle']
-        sig = query['openid.sig']
-        signed = query['openid.signed']
-        invalidate_handle = query['openid.invalidate_handle']
-
-        unless assoc_handle and sig and signed
-          raise ProtocolError.new(query,
-                                  "#{@mode} request missing required paramter")
+      # Construct me from an OpenID::Message.
+      def self.from_message(message, op_endpoint=UNUSED)
+        assoc_handle = message.get_arg(OPENID_NS, 'assoc_handle')
+        invalidate_handle = message.get_arg(OPENID_NS, 'invalidate_handle')
+
+        signed = message.copy()
+        # openid.mode is currently check_authentication because
+        # that's the mode of this request.  But the signature
+        # was made on something with a different openid.mode.
+        # http://article.gmane.org/gmane.comp.web.openid.general/537
+        if signed.has_key?(OPENID_NS, "mode")
+          signed.set_arg(OPENID_NS, "mode", "id_res")
         end
 
-        signed = signed.split(',')
-        signed_pairs = []
+        obj = self.new(assoc_handle, signed, invalidate_handle)
+        obj.message = message
+        obj.namespace = message.get_openid_namespace()
+        obj.sig = message.get_arg(OPENID_NS, 'sig')
 
-        signed.each do |field|
-          if field == 'mode'
-            value = 'id_res'
-          else
-            value = query['openid.'+field]
-            if value.nil?
-              raise ProtocolError.new(query, "Couldn't find signed field #{field}")
-            end
-          end
-          signed_pairs << [field, value]
+        if !obj.assoc_handle or
+            !obj.sig
+          msg = sprintf("%s request missing required parameter from message %s",
+                        obj.mode, message)
+            raise ProtocolError.new(message, msg)
         end
-        
-        return new(assoc_handle, sig, signed_pairs, invalidate_handle)
+
+        return obj
       end
 
-      # Respond to this request.  Given an OpenID::Server::Signatory instance
-      # the validity of the signature and invalidate_handle can be checked.
-      # 
-      # Returns an OpenIDResponse object with an appropriate "is_valid" field
-      # and an "invalidate_handle" field if appropriate.
+      # Respond to this request.
+      #
+      # Given a Signatory, I can check the validity of the signature
+      # and the invalidate_handle.  I return a response with an
+      # is_valid (and, if appropriate invalidate_handle) field.
       def answer(signatory)
-        is_valid = signatory.verify(@assoc_handle, @sig, @signed)
-        signatory.invalidate(assoc_handle, true)
-
+        is_valid = signatory.verify(@assoc_handle, @signed)
+        # Now invalidate that assoc_handle so it this checkAuth
+        # message cannot be replayed.
+        signatory.invalidate(@assoc_handle, dumb=true)
         response = OpenIDResponse.new(self)
-        response.fields['is_valid'] = is_valid ? 'true' : 'false'
-        
+        valid_str = is_valid ? "true" : "false"
+        response.fields.set_arg(OPENID_NS, 'is_valid', valid_str)
+
         if @invalidate_handle
           assoc = signatory.get_association(@invalidate_handle, false)
-          unless assoc
-            response.fields['invalidate_handle'] = @invalidate_handle
-          end          
+          if !assoc
+            response.fields.set_arg(
+                    OPENID_NS, 'invalidate_handle', @invalidate_handle)
+          end
         end
 
         return response
       end
 
+      def to_s
+        ih = nil
+
+        if @invalidate_handle
+          ih = sprintf(" invalidate? %s", @invalidate_handle)
+        else
+          ih = ""
+        end
+
+        s = sprintf("<%s handle: %s sig: %s: signed: %s%s>",
+                    self.class, @assoc_handle,
+                    @sig, @signed, ih)
+        return s
+      end
     end
-    
-    # An object that knows how to handle association requests with no
-    # session type.
-    class PlainTextServerSession
 
+    class BaseServerSession
+      attr_reader :session_type
+
+      def initialize(session_type, allowed_assoc_types)
+        @session_type = session_type
+        @allowed_assoc_types = allowed_assoc_types.dup.freeze
+      end
+
+      def allowed_assoc_type?(typ)
+        @allowed_assoc_types.member?(typ)
+      end
+    end
+
+    # An object that knows how to handle association requests with
+    # no session type.
+    #
+    # See OpenID Specs, Section 8: Establishing Associations
+    # <http://openid.net/specs/openid-authentication-2_0-12.html#associations>
+    class PlainTextServerSession < BaseServerSession
+      # The session_type for this association session. There is no
+      # type defined for plain-text in the OpenID specification, so we
+      # use 'no-encryption'.
       attr_reader :session_type
 
       def initialize
-        @session_type = 'plaintext'
+        super('no-encryption', ['HMAC-SHA1', 'HMAC-SHA256'])
       end
 
-      def PlainTextServerSession.from_query(query)
-        new
+      def self.from_message(unused_request)
+        return self.new
       end
-      
+
       def answer(secret)
-        return {'mac_key' => OpenID::Util.to_base64(secret)}
+        return {'mac_key' => Util.to_base64(secret)}
       end
-
     end
 
-    # An object that knows how to handle Diffie Hellman (DH-SHA1) association
-    # requests.
-    class DiffieHellmanServerSession
+    # An object that knows how to handle association requests with the
+    # Diffie-Hellman session type.
+    #
+    # See OpenID Specs, Section 8: Establishing Associations
+    # <http://openid.net/specs/openid-authentication-2_0-12.html#associations>
+    class DiffieHellmanSHA1ServerSession < BaseServerSession
+
+      # The Diffie-Hellman algorithm values for this request
+      attr_accessor :dh
+
+      # The public key sent by the consumer in the associate request
+      attr_accessor :consumer_pubkey
+
+      # The session_type for this association session.
+      attr_reader :session_type
 
-      attr_reader :session_type, :dh, :consumer_pubkey
-      
-      # In general you should create instances of DiffieHellmanServerSession
-      # with the from_query class method.
-      # 
-      # ==Parameters
-      #
-      # [+dh+]
-      #   OpenID::DiffieHellman instance
-      #
-      # [+consumer_pubkey+]
-      #   Decoded "openid.dh_consumer_public".
       def initialize(dh, consumer_pubkey)
+        super('DH-SHA1', ['HMAC-SHA1'])
+
+        @hash_func = CryptUtil.method('sha1')
         @dh = dh
         @consumer_pubkey = consumer_pubkey
-        @session_type = 'DH-SHA1'
-      end      
+      end
+
+      # Construct me from OpenID Message
+      #
+      # Raises ProtocolError when parameters required to establish the
+      # session are missing.
+      def self.from_message(message)
+        dh_modulus = message.get_arg(OPENID_NS, 'dh_modulus')
+        dh_gen = message.get_arg(OPENID_NS, 'dh_gen')
+        if ((!dh_modulus and dh_gen) or
+            (!dh_gen and dh_modulus))
+
+          if !dh_modulus
+            missing = 'modulus'
+          else
+            missing = 'generator'
+          end
+
+          raise ProtocolError.new(message,
+                  sprintf('If non-default modulus or generator is ' +
+                          'supplied, both must be supplied. Missing %s',
+                          missing))
+        end
 
-      # Creates a new DiffieHellmanServerSession from the incoming request.
-      # Raises a ProtocolError for malformed requests, and returns a 
-      # DiffieHellmanServerSession instnace on success.
-      def DiffieHellmanServerSession.from_query(query)
-        dh_modulus = query['openid.dh_modulus']
-        dh_gen = query['openid.dh_gen']
-        dh = OpenID::DiffieHellman.from_base64(dh_modulus, dh_gen)
+        if dh_modulus or dh_gen
+          dh_modulus = CryptUtil.base64_to_num(dh_modulus)
+          dh_gen = CryptUtil.base64_to_num(dh_gen)
+          dh = DiffieHellman.new(dh_modulus, dh_gen)
+        else
+          dh = DiffieHellman.from_defaults()
+        end
 
-        consumer_pubkey = query['openid.dh_consumer_public']
-        unless consumer_pubkey
-          msg = 'No openid.dh_consumer_public found for DH-SHA1 session'
-          raise ProtocolError.new(query, msg)
+        consumer_pubkey = message.get_arg(OPENID_NS, 'dh_consumer_public')
+        if !consumer_pubkey
+          raise ProtocolError.new(message,
+                  sprintf("Public key for DH-SHA1 session " +
+                          "not found in message %s", message))
         end
 
-        consumer_pubkey = OpenID::Util.base64_to_num(consumer_pubkey)
-        return new(dh, consumer_pubkey)
+        consumer_pubkey = CryptUtil.base64_to_num(consumer_pubkey)
+
+        return self.new(dh, consumer_pubkey)
       end
 
-      # Generate the arguments to be added to the response using +secret+.
       def answer(secret)
-        mac_key = @dh.xor_secrect(@consumer_pubkey, secret)
+        mac_key = @dh.xor_secret(@hash_func,
+                                 @consumer_pubkey,
+                                 secret)
         return {
-          'dh_server_public' => OpenID::Util.num_to_base64(@dh.public),
-          'enc_mac_key' => OpenID::Util.to_base64(mac_key)
-        }
+            'dh_server_public' => CryptUtil.num_to_base64(@dh.public),
+            'enc_mac_key' => Util.to_base64(mac_key),
+            }
       end
+    end
 
+    class DiffieHellmanSHA256ServerSession < DiffieHellmanSHA1ServerSession
+      def initialize(*args)
+        super(*args)
+        @session_type = 'DH-SHA256'
+        @hash_func = CryptUtil.method('sha256')
+        @allowed_assoc_types = ['HMAC-SHA256'].freeze
+      end
     end
 
-    # A request to establish an OpenID association.  This object contains the
-    # logic for handling "openid.mode=associate" requests.
+    # A request to establish an association.
+    #
+    # See OpenID Specs, Section 8: Establishing Associations
+    # <http://openid.net/specs/openid-authentication-2_0-12.html#associations>
     class AssociateRequest < OpenIDRequest
+      # An object that knows how to handle association requests of a
+      # certain type.
+      attr_accessor :session
+
+      # The type of association. Supported values include HMAC-SHA256
+      # and HMAC-SHA1
+      attr_accessor :assoc_type
 
-      attr_accessor :assoc_type, :session
+      @@session_classes = {
+        'no-encryption' => PlainTextServerSession,
+        'DH-SHA1' => DiffieHellmanSHA1ServerSession,
+        'DH-SHA256' => DiffieHellmanSHA256ServerSession,
+      }
 
-      # +session+ is an instance of PlainTextServerSession or 
-      # DiffieHellmanServerSession
-      def initialize(session)
-        super('associate')
-        @assoc_type = 'HMAC-SHA1'
+      # Construct me.
+      #
+      # The session is assigned directly as a class attribute. See my
+      # class documentation for its description.
+      def initialize(session, assoc_type)
+        super()
         @session = session
+        @assoc_type = assoc_type
+        @namespace = OPENID2_NS
+
+        @mode = "associate"
       end
 
-      # Generate an AssociateRequest instance from the incoming query.
-      # Raises a ProtocolError on malformed requests.
-      def AssociateRequest.from_query(query)
-        session_type = query['openid.session_type']
-        if session_type == 'DH-SHA1'
-          session = DiffieHellmanServerSession.from_query(query)
-        elsif session_type.nil?
-          session = PlainTextServerSession.from_query(query)
+      # Construct me from an OpenID Message.
+      def self.from_message(message, op_endpoint=UNUSED)
+        if message.is_openid1()
+          session_type = message.get_arg(OPENID1_NS, 'session_type')
+          if session_type == 'no-encryption'
+            Util.log('Received OpenID 1 request with a no-encryption ' +
+                     'assocaition session type. Continuing anyway.')
+          elsif !session_type
+            session_type = 'no-encryption'
+          end
         else
-          raise ProtocolError.new(query,
-                                  "Unknown session_type #{session_type}")
+          session_type = message.get_arg(OPENID2_NS, 'session_type')
+          if !session_type
+            raise ProtocolError.new(message,
+                                    text="session_type missing from request")
+          end
+        end
+
+        session_class = @@session_classes[session_type]
+
+        if !session_class
+          raise ProtocolError.new(message,
+                  sprintf("Unknown session type %s", session_type))
+        end
+
+        begin
+          session = session_class.from_message(message)
+        rescue ArgumentError => why
+          # XXX
+          raise ProtocolError.new(message,
+                                  sprintf('Error parsing %s session: %s',
+                                          session_type, why))
         end
-        
-        return new(session)
+
+        assoc_type = message.get_arg(OPENID_NS, 'assoc_type', 'HMAC-SHA1')
+        if !session.allowed_assoc_type?(assoc_type)
+          msg = sprintf('Session type %s does not support association type %s',
+                        session_type, assoc_type)
+          raise ProtocolError.new(message, msg)
+        end
+
+        obj = self.new(session, assoc_type)
+        obj.message = message
+        obj.namespace = message.get_openid_namespace()
+        return obj
       end
 
-      # Respond to this request with an association.  +assoc+ is an
-      # OpenID::Association instance that represents the association to
-      # respond with.
+      # Respond to this request with an association.
+      #
+      # assoc:: The association to send back.
+      #
+      # Returns a response with the association information, encrypted
+      # to the consumer's public key if appropriate.
       def answer(assoc)
         response = OpenIDResponse.new(self)
+        response.fields.update_args(OPENID_NS, {
+            'expires_in' => sprintf('%d', assoc.expires_in()),
+            'assoc_type' => @assoc_type,
+            'assoc_handle' => assoc.handle,
+            })
+        response.fields.update_args(OPENID_NS,
+                                   @session.answer(assoc.secret))
+        if @session.session_type != 'no-encryption'
+          response.fields.set_arg(
+              OPENID_NS, 'session_type', @session.session_type)
+        end
 
-        fields = {
-          'expires_in' => assoc.expires_in.to_s,
-          'assoc_type' => 'HMAC-SHA1',
-          'assoc_handle' => assoc.handle
-        }
+        return response
+      end
 
-        # add the session specific arguments to the response fields
-        response.fields.update(fields)        
-        response.fields.update(@session.answer(assoc.secret))
-        
-        if @session.session_type != 'plaintext'
-          response.fields['session_type'] = @session.session_type
+      # Respond to this request indicating that the association type
+      # or association session type is not supported.
+      def answer_unsupported(message, preferred_association_type=nil,
+                             preferred_session_type=nil)
+        if @message.is_openid1()
+          raise ProtocolError.new(@message)
+        end
+
+        response = OpenIDResponse.new(self)
+        response.fields.set_arg(OPENID_NS, 'error_code', 'unsupported-type')
+        response.fields.set_arg(OPENID_NS, 'error', message)
+
+        if preferred_association_type
+          response.fields.set_arg(
+              OPENID_NS, 'assoc_type', preferred_association_type)
+        end
+
+        if preferred_session_type
+          response.fields.set_arg(
+              OPENID_NS, 'session_type', preferred_session_type)
         end
 
         return response
       end
-
     end
 
-    # Object representing a request to confirm the identity of a
-    # user. This object handles requests for openid.mode checkid_immediate, and
-    # checkid_setup.
+    # A request to confirm the identity of a user.
+    #
+    # This class handles requests for openid modes
+    # +checkid_immediate+ and +checkid_setup+ .
     class CheckIDRequest < OpenIDRequest
-      
-      attr_accessor :identity, :return_to, :trust_root, :immediate, \
-                    :assoc_handle, :mode, :query
-      
-      # Create a new CheckIDRequest instance.  Most likely you'll want to
-      # use CheckIDRequest.from_query to create this object.
-      def initialize(mode, identity, return_to,
-                     trust_root=nil, assoc_handle=nil)
-        
-        unless ['checkid_immediate', 'checkid_setup'].include?(mode)
-          raise ProtocolError, "Can't create CheckIDRequest for mode #{mode}"
-        end
-
-        super(mode)
+
+      # Provided in smart mode requests, a handle for a previously
+      # established association.  nil for dumb mode requests.
+      attr_accessor :assoc_handle
+
+      # Is this an immediate-mode request?
+      attr_accessor :immediate
+
+      # The URL to send the user agent back to to reply to this
+      # request.
+      attr_accessor :return_to
+
+      # The OP-local identifier being checked.
+      attr_accessor :identity
+
+      # The claimed identifier.  Not present in OpenID 1.x
+      # messages.
+      attr_accessor :claimed_id
+
+      # This URL identifies the party making the request, and the user
+      # will use that to make her decision about what answer she
+      # trusts them to have. Referred to as "realm" in OpenID 2.0.
+      attr_accessor :trust_root
+
+      # mode:: +checkid_immediate+ or +checkid_setup+
+      attr_accessor :mode
+
+      attr_accessor :return_to, :op_endpoint
+
+      # These parameters are assigned directly as attributes,
+      # see the #CheckIDRequest class documentation for their
+      # descriptions.
+      #
+      # Raises #MalformedReturnURL when the +return_to+ URL is not
+      # a URL.
+      def initialize(identity, return_to, op_endpoint, trust_root=nil,
+                     immediate=false, assoc_handle=nil)
+        @namespace = OPENID2_NS
+        @assoc_handle = assoc_handle
         @identity = identity
+        @claimed_id = identity
         @return_to = return_to
-        @trust_root = trust_root
-        @immediate = mode == 'checkid_immediate' ? true : false
-        @assoc_handle = assoc_handle
-        @query = {}
+        @trust_root = trust_root or return_to
+        @op_endpoint = op_endpoint
+
+        if immediate
+          @immediate = true
+          @mode = "checkid_immediate"
+        else
+          @immediate = false
+          @mode = "checkid_setup"
+        end
+
+        if @return_to and
+            !TrustRoot::TrustRoot.parse(@return_to)
+          raise MalformedReturnURL.new(nil, @return_to)
+        end
+
+        if !trust_root_valid()
+          raise UntrustedReturnURL.new(nil, @return_to, @trust_root)
+        end
       end
-       
-      
-      # Create a CheckIDRequest object from a web query.  May raise a
-      # ProtocolError if request is a malformed checkid_* reuquest.
-      def CheckIDRequest.from_query(query)
-        mode = query['openid.mode']
 
-        identity = query['openid.identity']
-        raise ProtocolError.new(query, 'openid.identity missing') unless identity
-        return_to = query['openid.return_to']
-        raise ProtocolError.new(query, 'openid.return_to missing') unless return_to
+      # Construct me from an OpenID message.
+      #
+      # message:: An OpenID checkid_* request Message
+      #
+      # op_endpoint:: The endpoint URL of the server that this
+      #               message was sent to.
+      #
+      # Raises:
+      # ProtocolError:: When not all required parameters are present
+      #                 in the message.
+      #
+      # MalformedReturnURL:: When the +return_to+ URL is not a URL.
+      #
+      # UntrustedReturnURL:: When the +return_to+ URL is
+      #                      outside the +trust_root+.
+      def self.from_message(message, op_endpoint)
+        obj = self.allocate
+        obj.message = message
+        obj.namespace = message.get_openid_namespace()
+        obj.op_endpoint = op_endpoint
+        mode = message.get_arg(OPENID_NS, 'mode')
+        if mode == "checkid_immediate"
+          obj.immediate = true
+          obj.mode = "checkid_immediate"
+        else
+          obj.immediate = false
+          obj.mode = "checkid_setup"
+        end
 
-        trust_root = query['openid.trust_root']
-        trust_root = nil if trust_root and trust_root.empty?
+        obj.return_to = message.get_arg(OPENID_NS, 'return_to')
+        if obj.namespace == OPENID1_NS and !obj.return_to
+          msg = sprintf("Missing required field 'return_to' from %s",
+                        message)
+          raise ProtocolError.new(message, msg)
+        end
+
+        obj.identity = message.get_arg(OPENID_NS, 'identity')
+        if obj.identity and message.is_openid2()
+          obj.claimed_id = message.get_arg(OPENID_NS, 'claimed_id')
+          if !obj.claimed_id
+            s = ("OpenID 2.0 message contained openid.identity but not " +
+                 "claimed_id")
+            raise ProtocolError.new(message, s)
+          end
+        else
+          obj.claimed_id = nil
+        end
 
-        unless OpenID::TrustRoot.parse(return_to)
-          raise MalformedReturnURL.new(query, return_to)
+        if !obj.identity and obj.namespace == OPENID1_NS
+          s = "OpenID 1 message did not contain openid.identity"
+          raise ProtocolError.new(message, s)
         end
 
-        if trust_root and not OpenID::TrustRoot.parse(trust_root)
-          raise MalformedTrustRoot.new(query, trust_root)
+        # There's a case for making self.trust_root be a TrustRoot
+        # here.  But if TrustRoot isn't currently part of the "public"
+        # API, I'm not sure it's worth doing.
+        if obj.namespace == OPENID1_NS
+          obj.trust_root = message.get_arg(
+                OPENID_NS, 'trust_root', obj.return_to)
+        else
+          obj.trust_root = message.get_arg(
+                OPENID_NS, 'realm', obj.return_to)
+
+          if !obj.return_to and
+              !obj.trust_root
+            raise ProtocolError.new(message, "openid.realm required when " +
+                                    "openid.return_to absent")
+          end
         end
-       
-        assoc_handle = query['openid.assoc_handle']
-        
-        req = new(mode, identity, return_to, trust_root, assoc_handle)        
-        req.query = query
-        
-        unless req.trust_root_valid
-          raise UntrustedReturnURL.new(query, return_to, trust_root)
+
+        obj.assoc_handle = message.get_arg(OPENID_NS, 'assoc_handle')
+
+        # Using TrustRoot.parse here is a bit misleading, as we're not
+        # parsing return_to as a trust root at all.  However, valid
+        # URLs are valid trust roots, so we can use this to get an
+        # idea if it is a valid URL.  Not all trust roots are valid
+        # return_to URLs, however (particularly ones with wildcards),
+        # so this is still a little sketchy.
+        if obj.return_to and \
+          !TrustRoot::TrustRoot.parse(obj.return_to)
+          raise MalformedReturnURL.new(message, obj.return_to)
         end
 
-        return req
+        # I first thought that checking to see if the return_to is
+        # within the trust_root is premature here, a
+        # logic-not-decoding thing.  But it was argued that this is
+        # really part of data validation.  A request with an invalid
+        # trust_root/return_to is broken regardless of application,
+        # right?
+        if !obj.trust_root_valid()
+          raise UntrustedReturnURL.new(message, obj.return_to, obj.trust_root)
+        end
+
+        return obj
+      end
+
+      # Is the identifier to be selected by the IDP?
+      def id_select
+        # So IDPs don't have to import the constant
+        return @identity == IDENTIFIER_SELECT
       end
 
-      # Returns +true+ or +false+ according to whether the return_to
-      # is under the supplied trust_root.
+      # Is my return_to under my trust_root?
       def trust_root_valid
-        return true unless @trust_root
-        tr = OpenID::TrustRoot.parse(@trust_root)
-        raise MalformedTrustRoot.new(nil, @trust_root) if tr.nil?
-        return tr.validate_url(@return_to)
+        if !@trust_root
+          return true
+        end
+
+        tr = TrustRoot::TrustRoot.parse(@trust_root)
+        if !tr
+          raise MalformedTrustRoot.new(nil, @trust_root)
+        end
+
+        if @return_to
+          return tr.validate_url(@return_to)
+        else
+          return true
+        end
+      end
+
+      # Does the relying party publish the return_to URL for this
+      # response under the realm? It is up to the provider to set a
+      # policy for what kinds of realms should be allowed. This
+      # return_to URL verification reduces vulnerability to
+      # data-theft attacks based on open proxies,
+      # corss-site-scripting, or open redirectors.
+      #
+      # This check should only be performed after making sure that
+      # the return_to URL matches the realm.
+      #
+      # Raises DiscoveryFailure if the realm
+      # URL does not support Yadis discovery (and so does not
+      # support the verification process).
+      #
+      # Returns true if the realm publishes a document with the
+      # return_to URL listed
+      def return_to_verified
+        return TrustRoot.verify_return_to(@trust_root, @return_to)
       end
 
-      # Generate a response to this checkid_* request.
+      # Respond to this request.
       #
-      # ==Paramters
+      # allow:: Allow this user to claim this identity, and allow the
+      #         consumer to have this information?
       #
-      # [+allow+]
-      #   Boolean value stating whether or not to allow this user to "claim"
-      #   supplied identity and let the consumer have the information. The
-      #   value of allow should be follow the following algorithm:
+      # server_url:: DEPRECATED.  Passing op_endpoint to the
+      #              #Server constructor makes this optional.
       #
-      #   The identity URL provided (openid.identity) and available
-      #   through the +identity_url+ method of this object is owned by
-      #   the logged in user, and they have approved the consumer receive
-      #   the identity assertion.
+      #              When an OpenID 1.x immediate mode request does
+      #              not succeed, it gets back a URL where the request
+      #              may be carried out in a not-so-immediate fashion.
+      #              Pass my URL in here (the fully qualified address
+      #              of this server's endpoint, i.e.
+      #              <tt>http://example.com/server</tt>), and I will
+      #              use it as a base for the URL for a new request.
       #
-      # [+server_url+]
-      #   When an immeditate mode request does not succeed, it gets back a URL
-      #   where the request may be continued in a not-so-immediate fashion.
-      #   The URL returned is generated using the supplied +server_url+ here.
-      #   +server_url+ should be the full URL of you openid server endpoint.
-      def answer(allow, server_url=nil)
-        if allow or @immediate
+      #              Optional for requests where
+      #              #CheckIDRequest.immediate is false or +allow+ is
+      #              true.
+      #
+      # identity:: The OP-local identifier to answer with.  Only for use
+      #            when the relying party requested identifier selection.
+      #
+      # claimed_id:: The claimed identifier to answer with,
+      #              for use with identifier selection in the case where the
+      #              claimed identifier and the OP-local identifier differ,
+      #              i.e. when the claimed_id uses delegation.
+      #
+      #              If +identity+ is provided but this is not,
+      #              +claimed_id+ will default to the value of +identity+.
+      #              When answering requests that did not ask for identifier
+      #              selection, the response +claimed_id+ will default to
+      #              that of the request.
+      #
+      #              This parameter is new in OpenID 2.0.
+      #
+      # Version 2.0 deprecates +server_url+ and adds +claimed_id+.
+      def answer(allow, server_url=nil, identity=nil, claimed_id=nil)
+        # FIXME: undocumented exceptions
+        if !@return_to
+          raise NoReturnToError
+        end
+
+        if !server_url
+          if @namespace != OPENID1_NS and !@op_endpoint
+            # In other words, that warning I raised in
+            # Server.__init__?  You should pay attention to it now.
+            raise RuntimeError, ("#{self} should be constructed with "\
+                                 "op_endpoint to respond to OpenID 2.0 "\
+                                 "messages.")
+          end
+
+          server_url = @op_endpoint
+        end
+
+        if allow
           mode = 'id_res'
+        elsif @namespace == OPENID1_NS
+          if @immediate
+            mode = 'id_res'
+          else
+            mode = 'cancel'
+          end
         else
-          mode = 'cancel'
+          if @immediate
+            mode = 'setup_needed'
+          else
+            mode = 'cancel'
+          end
         end
 
         response = OpenIDResponse.new(self)
 
+        if claimed_id and @namespace == OPENID1_NS
+          raise VersionError, ("claimed_id is new in OpenID 2.0 and not "\
+                               "available for #{@namespace}")
+        end
+
+        if identity and !claimed_id
+          claimed_id = identity
+        end
+
         if allow
-          response.add_fields(nil, {
-                                'mode' => mode,
-                                'identity' => @identity,
-                                'return_to' => @return_to
-                              })
+          if @identity == IDENTIFIER_SELECT
+            if !identity
+              raise ArgumentError, ("This request uses IdP-driven "\
+                                    "identifier selection.You must supply "\
+                                    "an identifier in the response.")
+            end
+
+            response_identity = identity
+            response_claimed_id = claimed_id
+
+          elsif @identity
+            if identity and (@identity != identity)
+              raise ArgumentError, ("Request was for identity #{@identity}, "\
+                                    "cannot reply with identity #{identity}")
+            end
+
+            response_identity = @identity
+            response_claimed_id = @claimed_id
+          else
+            if identity
+              raise ArgumentError, ("This request specified no identity "\
+                                    "and you supplied #{identity}")
+            end
+            response_identity = nil
+          end
+
+          if @namespace == OPENID1_NS and !response_identity
+            raise ArgumentError, ("Request was an OpenID 1 request, so "\
+                                  "response must include an identifier.")
+          end
+
+          response.fields.update_args(OPENID_NS, {
+                'mode' => mode,
+                'op_endpoint' => server_url,
+                'return_to' => @return_to,
+                'response_nonce' => Nonce.mk_nonce(),
+                })
+
+          if response_identity
+            response.fields.set_arg(OPENID_NS, 'identity', response_identity)
+            if @namespace == OPENID2_NS
+              response.fields.set_arg(OPENID_NS,
+                                      'claimed_id', response_claimed_id)
+            end
+          end
         else
-          response.add_field(nil, 'mode', mode, false)
-          response.signed.clear
+          response.fields.set_arg(OPENID_NS, 'mode', mode)
           if @immediate
-            unless server_url
-              raise ArgumentError, "setup_url is required for allow=false in immediate mode"
+            if @namespace == OPENID1_NS and !server_url
+              raise ArgumentError, ("setup_url is required for allow=false "\
+                                    "in OpenID 1.x immediate mode.")
             end
-            # make a request just like this one, but immediate mode
-            setup_request = self.class.new('checkid_immediate',
-                                           @identity,
-                                           @return_to,
-                                           @trust_root)
+
+            # Make a new request just like me, but with
+            # immediate=false.
+            setup_request = self.class.new(@identity, @return_to,
+                                           @op_endpoint, @trust_root, false,
+                                           @assoc_handle)
             setup_url = setup_request.encode_to_url(server_url)
-            response.add_field(nil, 'user_setup_url', setup_url, false)
+            response.fields.set_arg(OPENID_NS, 'user_setup_url', setup_url)
           end
-
         end
-        
+
         return response
       end
 
-      # Encode this request as a GET URL, returning the URL.
       def encode_to_url(server_url)
-        q = {
-          'openid.mode' => @mode,
-          'openid.identity' => @identity,
-          'openid.return_to' => @return_to
-        }
-
-        q['openid.trust_root'] = @trust_root if @trust_root
-        q['openid.assoc_handle'] = @assoc_handle if @assoc_handle
+        # Encode this request as a URL to GET.
+        #
+        # server_url:: The URL of the OpenID server to make this
+        #              request of.
+        if !@return_to
+          raise NoReturnToError
+        end
 
-        # add other openid stuff into the query (extensions)
-        @query.each do |k,v|
-          if k.starts_with?('openid.') and not q.has_key?(k)
-            q[k] = v
+        # Imported from the alternate reality where these classes are
+        # used in both the client and server code, so Requests are
+        # Encodable too.  That's right, code imported from alternate
+        # realities all for the love of you, id_res/user_setup_url.
+        q = {'mode' => @mode,
+             'identity' => @identity,
+             'claimed_id' => @claimed_id,
+             'return_to' => @return_to}
+
+        if @trust_root
+          if @namespace == OPENID1_NS
+            q['trust_root'] = @trust_root
+          else
+            q['realm'] = @trust_root
           end
         end
 
-        return OpenID::Util.append_args(server_url, q)
+        if @assoc_handle
+          q['assoc_handle'] = @assoc_handle
+        end
+
+        response = Message.new(@namespace)
+        response.update_args(@namespace, q)
+        return response.to_url(server_url)
       end
 
-      # Create the URL to cancel this request.  Useful for creating a "Cancel"
-      # button on your "approve this openid transaction" form.
       def cancel_url
+        # Get the URL to cancel this request.
+        #
+        # Useful for creating a "Cancel" button on a web form so that
+        # operation can be carried out directly without another trip
+        # through the server.
+        #
+        # (Except you may want to make another trip through the
+        # server so that it knows that the user did make a decision.)
+        #
+        # Returns a URL as a string.
+        if !@return_to
+          raise NoReturnToError
+        end
+
         if @immediate
-          raise ProtocolError.new(nil, 'cancel is not an appropriate reponse to immediate mode requests')
+          raise ArgumentError.new("Cancel is not an appropriate response to " +
+                                  "immediate mode requests.")
         end
-        return OpenID::Util.append_args(@return_to,{'openid.mode' => 'cancel'})
-      end
 
-      # The identity_url which was requested to be verified.  Your server
-      # should provide a page at identity_url, and be able to assert
-      # that the logged in user does or does not "own" that URL.
-      # "Owning" an identity_url is in the details of the
-      # server account name to URL mapping.
-      def identity_url
-        @identity
+        response = Message.new(@namespace)
+        response.set_arg(OPENID_NS, 'mode', 'cancel')
+        return response.to_url(@return_to)
       end
 
+      def to_s
+        return sprintf('<%s id:%s im:%s tr:%s ah:%s>', self.class,
+                       @identity,
+                       @immediate,
+                       @trust_root,
+                       @assoc_handle)
+      end
     end
-    
-    # Object representing a response to an OpenIDRequest
+
+    # I am a response to an OpenID request.
+    #
+    # Attributes:
+    # signed:: A list of the names of the fields which should be signed.
+    #
+    # Implementer's note: In a more symmetric client/server
+    # implementation, there would be more types of #OpenIDResponse
+    # object and they would have validated attributes according to
+    # the type of response.  But as it is, Response objects in a
+    # server are basically write-only, their only job is to go out
+    # over the wire, so this is just a loose wrapper around
+    # #OpenIDResponse.fields.
     class OpenIDResponse
+      # The #OpenIDRequest I respond to.
+      attr_accessor :request
 
-      attr_accessor :request, :fields, :signed
+      # An #OpenID::Message with the data to be returned.
+      # Keys are parameter names with no
+      # leading openid. e.g. identity and mac_key
+      # never openid.identity.
+      attr_accessor :fields
 
-      # +request+ is a subclass of OpenIDRequest that this object
-      # should respond to.
       def initialize(request)
+        # Make a response to an OpenIDRequest.
         @request = request
-        @fields = {}
-        @signed = []
+        @fields = Message.new(request.namespace)
       end
 
-      # Add an extra field to this response.
-      #
-      # [+namespace+]
-      #   Extension namespace the field is in with no leading "openid.". For
-      #   example, if you are adding a simple registration argument, you would
-      #   pass 'sreg' as the namespace.
-      def add_field(namespace, key, value, signed=true)
-        if namespace and namespace != ''
-          key = namespace + '.' + key
-        end
-        @fields[key] = value
-        if signed and not @signed.member?(key)
-          @signed << key
-        end
+      def to_s
+        return sprintf("%s for %s: %s",
+                       self.class,
+                       @request.class,
+                       @fields)
       end
 
-      # Same as OpenIDResponse.add_field, except that it accepts a Hash
-      # fields to be added as the +fields+ argument.
-      def add_fields(namespace, fields, signed=true)
-        fields.each {|k,v| self.add_field(namespace, k, v, signed)}
+      def to_form_markup
+        # Returns the form markup for this response.
+        return @fields.to_form_markup(
+                 @fields.get_arg(OPENID_NS, 'return_to'))
       end
 
-      # Update the fields of this request with another OpenIDResponse, +other+.
-      def update(namespace, other)
-        if namespace and namespace != ''
-          namespaced_fields = {}
-          other.fields.each {|k,v| namespaced_fields[namespace+'.'+k] = v}
-          namespaced_signed = other.signed.collect {|k| namespace+'.'+k}
-        else
-          namespaced_fields = other.fields.dup
-          namespaced_signed = other.signed.dup
-        end
-        
-        @fields.update(namespaced_fields)
-        @signed |= namespaced_signed
+      def render_as_form
+        # Returns true if this response's encoding is
+        # ENCODE_HTML_FORM.  Convenience method for server authors.
+        return self.which_encoding == ENCODE_HTML_FORM
       end
 
-      # Returns a boolean saying whether or not this response requires
-      # signing.
-      def needs_signing?
-        ['checkid_immediate','checkid_setup'].member?(@request.mode) and \
-           @signed.length > 0
+      def needs_signing
+        # Does this response require signing?
+        return @fields.get_arg(OPENID_NS, 'mode') == 'id_res'
       end
 
-      # OpenID responses can be sent back as a URL redirect or as a kvform
-      # reponse to a POST. This method returns a code describing how the
-      # response should be encoded, and return either
-      # OpenID::Server::ENCODE_URL or OpenID::Server::ENCODE_KVFORM.
-      def which_encoding?
+      # implements IEncodable
+
+      def which_encoding
+        # How should I be encoded?
+        # returns one of ENCODE_URL or ENCODE_KVFORM.
         if BROWSER_REQUEST_MODES.member?(@request.mode)
-          return ENCODE_URL
+          if @fields.get_openid_namespace == OPENID2_NS and
+              encode_to_url.length > OPENID1_URL_LIMIT
+            return ENCODE_HTML_FORM
+          else
+            return ENCODE_URL
+          end
         else
           return ENCODE_KVFORM
         end
       end
 
-      # Encode the response to a URL, suitable to be send via 302 redirect.
       def encode_to_url
-        fields = {}
-        @fields.each {|k,v| fields['openid.'+k] = v}
-        return OpenID::Util.append_args(@request.return_to, fields)
+        # Encode a response as a URL for the user agent to GET.
+        # You will generally use this URL with a HTTP redirect.
+        return @fields.to_url(@request.return_to)
+      end
+
+      def add_extension(extension_response)
+        # Add an extension response to this response message.
+        #
+        # extension_response:: An object that implements the
+        #     #OpenID::Extension interface for adding arguments to an OpenID
+        #     message.
+        extension_response.to_message(@fields)
       end
 
-      # Encode the response to kvform format.
       def encode_to_kvform
-        return OpenID::Util.kvform(@fields)
+        # Encode a response in key-value colon/newline format.
+        #
+        # This is a machine-readable format used to respond to
+        # messages which came directly from the consumer and not
+        # through the user agent.
+        #
+        # see: OpenID Specs,
+        #    <a href="http://openid.net/specs.bml#keyvalue">Key-Value Colon/Newline format</a>
+        return @fields.to_kvform
+      end
+
+      def copy
+        return Marshal.load(Marshal.dump(self))
       end
-      
     end
 
-    # Object responsible for signing responses, and checking signatures.
+    # I am a response to an OpenID request in terms a web server
+    # understands.
+    #
+    # I generally come from an #Encoder, either directly or from
+    # #Server.encodeResponse.
+    class WebResponse
+
+      # The HTTP code of this response as an integer.
+      attr_accessor :code
+
+      # #Hash of headers to include in this response.
+      attr_accessor :headers
+
+      # The body of this response.
+      attr_accessor :body
+
+      def initialize(code=HTTP_OK, headers=nil, body="")
+        # Construct me.
+        #
+        # These parameters are assigned directly as class attributes,
+        # see my class documentation for their
+        # descriptions.
+        @code = code
+        if headers
+          @headers = headers
+        else
+          @headers = {}
+        end
+        @body = body
+      end
+    end
+
+    # I sign things.
+    #
+    # I also check signatures.
+    #
+    # All my state is encapsulated in a store, which means I'm not
+    # generally pickleable but I am easy to reconstruct.
     class Signatory
-      @@secret_lifetime = 14 * 24 * 60 * 6
-      @@normal_key = 'http://localhost/|normal'
-      @@dumb_key = 'http://localhost/|dumb'
-      
-      attr_reader :dumb_key
-
-      # Accepts an object that implements the OpenID::Store interface.  See
-      # OpenID::FilesystemStore for a simple file based store.
+      # The number of seconds a secret remains valid. Defaults to 14 days.
+      attr_accessor :secret_lifetime
+
+      # keys have a bogus server URL in them because the filestore
+      # really does expect that key to be a URL.  This seems a little
+      # silly for the server store, since I expect there to be only
+      # one server URL.
+      @@_normal_key = 'http://localhost/|normal'
+      @@_dumb_key = 'http://localhost/|dumb'
+
+      def self._normal_key
+        @@_normal_key
+      end
+
+      def self._dumb_key
+        @@_dumb_key
+      end
+
+      attr_accessor :store
+
+      # Create a new Signatory. store is The back-end where my
+      # associations are stored.
       def initialize(store)
+        Util.assert(store)
         @store = store
+        @secret_lifetime = 14 * 24 * 60 * 60
       end
 
       # Verify that the signature for some data is valid.
-      #
-      # ==Paramters
-      #
-      # [+assoc_handle+]
-      #   The association handle used to get the secret out of the store, and
-      #   passed in via openid.assoc_handle.
-      #
-      # [+sig+]
-      #   Value of openid.sig
-      #
-      # [+signed_pairs+]
-      #   Array of Array pairs of key, value signed data.
-      #
-      # [+dumb+]
-      #   boolean representing whether this is a dumb mode request      
-      def verify(assoc_handle, sig, signed_pairs, dumb=true)
-        assoc = self.get_association(assoc_handle, dumb)
-        unless assoc
-          OpenID::Util.log("failed to get assoc with handle #{assoc_handle} to verify sig #{sig}")
+      def verify(assoc_handle, message)
+        assoc = get_association(assoc_handle, true)
+        if !assoc
+          Util.log(sprintf("failed to get assoc with handle %s to verify " +
+                           "message %s", assoc_handle, message))
           return false
         end
-        
-        expected_sig = OpenID::Util.to_base64(assoc.sign(signed_pairs))
 
-        if sig == expected_sig
-          return true
-        else
-          OpenID::Util.log("signture mismatch: expected #{expected_sig}, got #{sig}")
+        begin
+          valid = assoc.check_message_signature(message)
+        rescue StandardError => ex
+          Util.log(sprintf("Error in verifying %s with %s: %s",
+                           message, assoc, ex))
           return false
         end
+
+        return valid
       end
 
-      # Sign a response, creating a signature based on everything in it's
-      # +signed+ array.  Returns a new response object with sig and signed
-      # values in its field set.
+      # Sign a response.
+      #
+      # I take an OpenIDResponse, create a signature for everything in
+      # its signed list, and return a new copy of the response object
+      # with that signature included.
       def sign(response)
-        # get a deep copy of the response
-        signed_response = Marshal.load(Marshal.dump(response))
+        signed_response = response.copy
         assoc_handle = response.request.assoc_handle
-
         if assoc_handle
-          assoc = self.get_association(assoc_handle, false)
-          unless assoc
-            # no assoc for handle, fall back to dumb mode
-            signed_response.fields['invalidate_handle'] = assoc_handle
-            assoc = self.create_association(true)
+          # normal mode disabling expiration check because even if the
+          # association is expired, we still need to know some
+          # properties of the association so that we may preserve
+          # those properties when creating the fallback association.
+          assoc = get_association(assoc_handle, false, false)
+
+          if !assoc or assoc.expires_in <= 0
+            # fall back to dumb mode
+            signed_response.fields.set_arg(
+                  OPENID_NS, 'invalidate_handle', assoc_handle)
+            assoc_type = assoc ? assoc.assoc_type : 'HMAC-SHA1'
+            if assoc and assoc.expires_in <= 0
+              # now do the clean-up that the disabled checkExpiration
+              # code didn't get to do.
+              invalidate(assoc_handle, false)
+            end
+            assoc = create_association(true, assoc_type)
           end
         else
-          # dumb mode
-          assoc = self.create_association(true)
+          # dumb mode.
+          assoc = create_association(true)
         end
-        
-        signed_response.fields['assoc_handle'] = assoc.handle
-        assoc.add_signature(signed_response.signed,
-                            signed_response.fields, '')
+
+        signed_response.fields = assoc.sign_message(signed_response.fields)
         return signed_response
       end
 
-      # Make a new assocation.
+      # Make a new association.
       def create_association(dumb=true, assoc_type='HMAC-SHA1')
-        secret = OpenID::Util.get_random_bytes(20)
-        uniq = OpenID::Util.to_base64(OpenID::Util.get_random_bytes(4))
-        handle = "{%s}{%x}{%s}" % [assoc_type, Time.now.to_i, uniq]
-        assoc = Association.from_expires_in(@@secret_lifetime,
-                                            handle,
-                                            secret,
-                                            assoc_type)
-
-        key = dumb ? @@dumb_key : @@normal_key
+        secret = CryptUtil.random_string(OpenID.get_secret_size(assoc_type))
+        uniq = Util.to_base64(CryptUtil.random_string(4))
+        handle = sprintf('{%s}{%x}{%s}', assoc_type, Time.now.to_i, uniq)
+
+        assoc = Association.from_expires_in(
+            secret_lifetime, handle, secret, assoc_type)
+
+        if dumb
+          key = @@_dumb_key
+        else
+          key = @@_normal_key
+        end
+
         @store.store_association(key, assoc)
         return assoc
       end
 
-      # Get an association by assoc_handle and mode
-      def get_association(assoc_handle, dumb)
-        if assoc_handle.nil?
-          raise ArgumentError, 'assoc_handle must not be nil'
+      # Get the association with the specified handle.
+      def get_association(assoc_handle, dumb, checkExpiration=true)
+        # Hmm.  We've created an interface that deals almost entirely
+        # with assoc_handles.  The only place outside the Signatory
+        # that uses this (and thus the only place that ever sees
+        # Association objects) is when creating a response to an
+        # association request, as it must have the association's
+        # secret.
+
+        if !assoc_handle
+          raise ArgumentError.new("assoc_handle must not be None")
+        end
+
+        if dumb
+          key = @@_dumb_key
+        else
+          key = @@_normal_key
         end
-        
-        key = dumb ? @@dumb_key : @@normal_key
-        
+
         assoc = @store.get_association(key, assoc_handle)
-        if assoc and assoc.expired?
-          @store.remove_association(key, assoc_handle)
-          assoc = nil
+        if assoc and assoc.expires_in <= 0
+          Util.log(sprintf("requested %sdumb key %s is expired (by %s seconds)",
+                           (!dumb) ? 'not-' : '',
+                           assoc_handle, assoc.expires_in))
+          if checkExpiration
+            @store.remove_association(key, assoc_handle)
+            assoc = nil
+          end
         end
-        
+
         return assoc
       end
 
-      # Invalidate an association by assoc_handle and mode
+      # Invalidates the association with the given handle.
       def invalidate(assoc_handle, dumb)
-        key = dumb ? @@dumb_key : @@normal_key
+        if dumb
+          key = @@_dumb_key
+        else
+          key = @@_normal_key
+        end
+
         @store.remove_association(key, assoc_handle)
       end
-
     end
 
-    # Response to an OpenID request that a web server can understand. Proper
-    # responses can be issued to your framework by examining the +code+
-    # method and associated methods.
-    class WebResponse
-      
-      attr_accessor :code, :headers, :body
-
-      def initialize
-        @code = HTTP_OK
-        @headers = {}
-        @body = ''
-      end
-
-      def set_redirect(url)
-        @code = HTTP_REDIRECT
-        @headers['location'] = url
-      end
+    # I encode responses in to WebResponses.
+    #
+    # If you don't like WebResponses, you can do
+    # your own handling of OpenIDResponses with
+    # OpenIDResponse.whichEncoding,
+    # OpenIDResponse.encodeToURL, and
+    # OpenIDResponse.encodeToKVForm.
+    class Encoder
+      @@responseFactory = WebResponse
 
-      # If this method returns true, a redirect should be issued by the
-      # webserver to the value returned by the redirect_url method.
+      # Encode a response to a WebResponse.
       #
-      # If this method returns false, the value returned by the +body+
-      # method should be returned to ther server as-is without modification.
-      def is_redirect?
-        @code == HTTP_REDIRECT
-      end
-
-      def redirect_url
-        @headers['location']
-      end
-
-    end
-
-    # Object that encodes OpenIDResponse objects into WebResponse objects.
-    class Encoder
-      
+      # Raises EncodingError when I can't figure out how to encode
+      # this message.
       def encode(response)
-        webresponse = WebResponse.new
-
-        case response.which_encoding?
-        when ENCODE_KVFORM
-          webresponse.code = HTTP_ERROR if response.kind_of?(Exception)
-          webresponse.body = response.encode_to_kvform
-
-        when ENCODE_URL
-          webresponse.set_redirect(response.encode_to_url)
-
+        encode_as = response.which_encoding()
+        if encode_as == ENCODE_KVFORM
+          wr = @@responseFactory.new(HTTP_OK, nil,
+                                     response.encode_to_kvform())
+          if response.is_a?(Exception)
+            wr.code = HTTP_ERROR
+          end
+        elsif encode_as == ENCODE_URL
+          location = response.encode_to_url()
+          wr = @@responseFactory.new(HTTP_REDIRECT,
+                                     {'location' => location})
+        elsif encode_as == ENCODE_HTML_FORM
+          wr = @@responseFactory.new(HTTP_OK, nil,
+                                     response.to_form_markup())
         else
-          # don't know how to encode response
+          # Can't encode this to a protocol message.  You should
+          # probably render it to HTML and show it to the user.
           raise EncodingError.new(response)
         end
-        
-        return webresponse
-      end
 
+        return wr
+      end
     end
 
-    # Object that encodes OpenIDResponse objects into WebResponse objects,
-    # potentially adding a signature along the way.
+    # I encode responses in to WebResponses, signing
+    # them when required.
     class SigningEncoder < Encoder
-      
+
+      attr_accessor :signatory
+
+      # Create a SigningEncoder given a Signatory
       def initialize(signatory)
-        if signatory.nil?
-          raise ArgumentError, "signatory must not be nil"
-        end
         @signatory = signatory
       end
 
+      # Encode a response to a WebResponse, signing it first if
+      # appropriate.
+      #
+      # Raises EncodingError when I can't figure out how to encode this
+      # message.
+      #
+      # Raises AlreadySigned when this response is already signed.
       def encode(response)
-        if (not response.kind_of?(Exception)) and response.needs_signing?
-          if response.fields.has_key?('sig')
-            raise AlreadySigned
+        # the is_a? is a bit of a kludge... it means there isn't
+        # really an adapter to make the interfaces quite match.
+        if !response.is_a?(Exception) and response.needs_signing()
+          if !@signatory
+            raise ArgumentError.new(
+              sprintf("Must have a store to sign this request: %s",
+                      response), response)
+          end
+
+          if response.fields.has_key?(OPENID_NS, 'sig')
+            raise AlreadySigned.new(response)
           end
+
           response = @signatory.sign(response)
         end
+
         return super(response)
       end
-
     end
 
-    # Decode incoming web requests into an OpenIDRequest object.
+    # I decode an incoming web request in to a OpenIDRequest.
     class Decoder
 
-      def decode(query)
-        return nil if query.length == 0
-        
-        mode = query['openid.mode']
-        return nil if mode.nil?
+      @@handlers = {
+        'checkid_setup' => CheckIDRequest.method('from_message'),
+        'checkid_immediate' => CheckIDRequest.method('from_message'),
+        'check_authentication' => CheckAuthRequest.method('from_message'),
+        'associate' => AssociateRequest.method('from_message'),
+        }
 
-        if mode.class == Array
-          raise ArgumentError, 'query hash must have one value for each key'
-        end
+      attr_accessor :server
+
+      # Construct a Decoder. The server is necessary because some
+      # replies reference their server.
+      def initialize(server)
+        @server = server
+      end
 
-        case mode
-        when 'checkid_setup', 'checkid_immediate'
-          return CheckIDRequest.from_query(query)
+      # I transform query parameters into an OpenIDRequest.
+      #
+      # If the query does not seem to be an OpenID request at all, I
+      # return nil.
+      #
+      # Raises ProtocolError when the query does not seem to be a valid
+      # OpenID request.
+      def decode(query)
+        if query.nil? or query.length == 0
+          return nil
+        end
 
-        when 'check_authentication'
-          return CheckAuthRequest.from_query(query)
+        message = Message.from_post_args(query)
 
-        when 'associate'
-          return AssociateRequest.from_query(query)
-          
-        else
-          raise ProtocolError.new(query, "Unknown mode #{mode}")
+        mode = message.get_arg(OPENID_NS, 'mode')
+        if !mode
+          msg = sprintf("No mode value in message %s", message)
+          raise ProtocolError.new(message, msg)
         end
-        
+
+        handler = @@handlers.fetch(mode, self.method('default_decoder'))
+        return handler.call(message, @server.op_endpoint)
       end
 
+      # Called to decode queries when no handler for that mode is
+      # found.
+      #
+      # This implementation always raises ProtocolError.
+      def default_decoder(message, server)
+        mode = message.get_arg(OPENID_NS, 'mode')
+        msg = sprintf("No decoder for mode %s", mode)
+        raise ProtocolError.new(message, msg)
+      end
     end
 
-    # Top level object that handles incoming requests for an OpenID server.
-    # 
-    # Some types of requests (those which are not CheckIDRequest objects) may
-    # be handed to the handle_request method, and an appropriate response
-    # will be returned.
-    #
-    # For convenienve, decode and encode methods are exposed which should be
-    # used as the entry and exit points of the OpenID server logic.  The first
-    # step when handling an OpenID server action should be to call
-    # Server.decode_request with the query arguments.
+    # I handle requests for an OpenID server.
     #
-    # This object needs an instance of OpenID::Store to store state between
-    # sessions and associations.  See OpenID::FilesystemStore for a simple
-    # file based solution.
+    # Some types of requests (those which are not checkid requests)
+    # may be handed to my handleRequest method, and I will take care
+    # of it and return a response.
     #
-    # ==Pseudo Code
-    # 
-    # Below is some pseudo code for using this object to handle OpenID server
-    # requests. The +params+ variable represents a Hash of the incoming
-    # arguments.  is_authorized and show_decide_page are methods you provide.
-    # At the end you have a WebResponse object suitable for examining and
-    # issuing a response to your web server.
-    #   
-    #   include OpenID
-    #   store = FilesystemStore.new('/var/openid/store')
-    #   server = Server::Server.new(store)
-    #   request = server.decode_request(params)
-    #   if request.kind_of?(CheckIDRequest)
-    #     if is_authorized(request.identity, request.trust_root)
-    #       response = request.answer(true)
-    #     elsif request.immediate
-    #       response = request.answer(false,'http://example.com/openid-server')
-    #     else
-    #       show_decide_page(request)
-    #       return
-    #     end
-    #   else
-    #     response = server.handle_request(request)
-    #   end
+    # For your convenience, I also provide an interface to
+    # Decoder.decode and SigningEncoder.encode through my methods
+    # decodeRequest and encodeResponse.
     #
-    #   web_response = server.encode_response(response)
-    #
-    # For an actual working example, please see the rails_server
-    # directory inside of the examples directory.  Have a look at the
-    # app/controllers/server_controller.rb and the +index+ method of the
-    # ServerController object.
+    # All my state is encapsulated in an store, which means I'm not
+    # generally pickleable but I am easy to reconstruct.
     class Server
-      
-      # +store+ is a kind of OpenID::Store
-      def initialize(store)
-        @store = store
-        @signatory = Signatory.new(store)
-        @encoder = SigningEncoder.new(@signatory)
-        @decoder = Decoder.new
-      end
+      @@signatoryClass = Signatory
+      @@encoderClass = SigningEncoder
+      @@decoderClass = Decoder
 
-      # Decode an incoming web request into a kind of OpenIDRequest object.
-      # +query+ should be a hash of request arguments. Rails users will want to
-      # pass in the @params instance variable of the ActionController.
-      def decode_request(query)
-        return @decoder.decode(query)
+      # The back-end where my associations and nonces are stored.
+      attr_accessor :store
+
+      # I'm using this for associate requests and to sign things.
+      attr_accessor :signatory
+
+      # I'm using this to encode things.
+      attr_accessor :encoder
+
+      # I'm using this to decode things.
+      attr_accessor :decoder
+
+      # I use this instance of OpenID::AssociationNegotiator to
+      # determine which kinds of associations I can make and how.
+      attr_accessor :negotiator
+
+      # My URL.
+      attr_accessor :op_endpoint
+
+      # op_endpoint is new in library version 2.0.
+      def initialize(store, op_endpoint)
+        @store = store
+        @signatory = @@signatoryClass.new(@store)
+        @encoder = @@encoderClass.new(@signatory)
+        @decoder = @@decoderClass.new(self)
+        @negotiator = DefaultNegotiator.copy()
+        @op_endpoint = op_endpoint
       end
 
-      # Handle all non checkid_* OpenID requests.
+      # Handle a request.
+      #
+      # Give me a request, I will give you a response.  Unless it's a
+      # type of request I cannot handle myself, in which case I will
+      # raise RuntimeError.  In that case, you can handle it yourself,
+      # or add a method to me for handling that request type.
       def handle_request(request)
-        return self.send('openid_'+request.mode, request)
-      end
-      
-      # Return a WebResponse object given an OpenIDResponse object
-      def encode_response(response)
-        return @encoder.encode(response)
+        begin
+          handler = self.method('openid_' + request.mode)
+        rescue NameError
+          raise RuntimeError.new(
+            sprintf("%s has no handler for a request of mode %s.",
+                    self, request.mode))
+        end
+
+        return handler.call(request)
       end
-      
-      # called by handle_request to perform check auth calls
+
+      # Handle and respond to check_authentication requests.
       def openid_check_authentication(request)
         return request.answer(@signatory)
       end
 
-      # called by handle_request to perform openid.mode=associate calls.
+      # Handle and respond to associate requests.
       def openid_associate(request)
-        assoc = @signatory.create_association(false)
-        return request.answer(assoc)
+        assoc_type = request.assoc_type
+        session_type = request.session.session_type
+        if @negotiator.allowed?(assoc_type, session_type)
+          assoc = @signatory.create_association(false,
+                                                assoc_type)
+          return request.answer(assoc)
+        else
+          message = sprintf('Association type %s is not supported with ' +
+                            'session type %s', assoc_type, session_type)
+          preferred_assoc_type, preferred_session_type = @negotiator.get_allowed_type()
+          return request.answer_unsupported(message,
+                                            preferred_assoc_type,
+                                            preferred_session_type)
+        end
       end
 
+      # Transform query parameters into an OpenIDRequest.
+      # query should contain the query parameters as a Hash with
+      # each key mapping to one value.
+      #
+      # If the query does not seem to be an OpenID request at all, I
+      # return nil.
+      def decode_request(query)
+        return @decoder.decode(query)
+      end
+
+      # Encode a response to a WebResponse, signing it first if
+      # appropriate.
+      #
+      # Raises EncodingError when I can't figure out how to encode this
+      # message.
+      #
+      # Raises AlreadySigned When this response is already signed.
+      def encode_response(response)
+        return @encoder.encode(response)
+      end
     end
 
-    # Raised when an OpenID request encounters some kind of protocol error.
+    # A message did not conform to the OpenID protocol.
     class ProtocolError < Exception
-      
-      attr_reader :query
-
-      def initialize(query, text=nil)
+      # The query that is failing to be a valid OpenID request.
+      attr_accessor :openid_message
+      attr_accessor :reference
+      attr_accessor :contact
+
+      # text:: A message about the encountered error.
+      def initialize(message, text=nil, reference=nil, contact=nil)
+        @openid_message = message
+        @reference = reference
+        @contact = contact
+        Util.assert(!message.is_a?(String))
         super(text)
-        @query = query
       end
 
-      def has_return_to?
-        @query.has_key?('openid.return_to')
+      # Get the return_to argument from the request, if any.
+      def get_return_to
+        if @openid_message.nil?
+          return nil
+        else
+          return @openid_message.get_arg(OPENID_NS, 'return_to')
+        end
+      end
+
+      # Did this request have a return_to parameter?
+      def has_return_to
+        return !get_return_to.nil?
+      end
+
+      # Generate a Message object for sending to the relying party,
+      # after encoding.
+      def to_message
+        namespace = @openid_message.get_openid_namespace()
+        reply = Message.new(namespace)
+        reply.set_arg(OPENID_NS, 'mode', 'error')
+        reply.set_arg(OPENID_NS, 'error', self.to_s)
+
+        if @contact
+          reply.set_arg(OPENID_NS, 'contact', @contact.to_s)
+        end
+
+        if @reference
+          reply.set_arg(OPENID_NS, 'reference', @reference.to_s)
+        end
+
+        return reply
       end
 
+      # implements IEncodable
+
       def encode_to_url
-        return_to = @query['openid.return_to']
-        unless return_to
-          raise ArgumentError, 'No return_to in query'
-        end
-        
-        args = {
-          'openid.mode' => 'error',
-          'openid.error' => self.to_s
-        }
-        
-        return OpenID::Util.append_args(return_to, args)
+        return to_message().to_url(get_return_to())
       end
 
       def encode_to_kvform
-        args = {
-          'mode' => 'error',
-          'error' => self.to_s
-        }        
-        return OpenID::Util.kvform(args)        
+        return to_message().to_kvform()
+      end
+
+      def to_form_markup
+        return to_message().to_form_markup(get_return_to())
       end
 
-      def which_encoding?
-        if self.has_return_to?
-          return ENCODE_URL
+      # How should I be encoded?
+      #
+      # Returns one of ENCODE_URL, ENCODE_KVFORM, or None.  If None,
+      # I cannot be encoded as a protocol message and should be
+      # displayed to the user.
+      def which_encoding
+        if has_return_to()
+          if @openid_message.get_openid_namespace() == OPENID2_NS and
+              encode_to_url().length > OPENID1_URL_LIMIT
+            return ENCODE_HTML_FORM
+          else
+            return ENCODE_URL
+          end
         end
 
-        mode = @query['openid.mode']
-        if mode and not BROWSER_REQUEST_MODES.member?(mode)
-          return ENCODE_KVFORM          
+        if @openid_message.nil?
+          return nil
         end
-        
+
+        mode = @openid_message.get_arg(OPENID_NS, 'mode')
+        if mode
+          if !BROWSER_REQUEST_MODES.member?(mode)
+            return ENCODE_KVFORM
+          end
+        end
+
+        # If your request was so broken that you didn't manage to
+        # include an openid.mode, I'm not going to worry too much
+        # about returning you something you can't parse.
         return nil
       end
+    end
 
+    # Raised when an operation was attempted that is not compatible
+    # with the protocol version being used.
+    class VersionError < Exception
     end
 
-    class EncodingError < Exception; end    
-    class AlreadySigned < EncodingError; end
-    
-    class MalformedReturnURL < ProtocolError
-      
-      attr_reader :return_to
+    # Raised when a response to a request cannot be generated
+    # because the request contains no return_to URL.
+    class NoReturnToError < Exception
+    end
 
-      def initialize(query, return_to)
-        super(query)
-        @return_to = return_to
+    # Could not encode this as a protocol message.
+    #
+    # You should probably render it and show it to the user.
+    class EncodingError < Exception
+      # The response that failed to encode.
+      attr_reader :response
+
+      def initialize(response)
+        super(response)
+        @response = response
       end
-
     end
 
-    class MalformedTrustRoot < ProtocolError; end
+    # This response is already signed.
+    class AlreadySigned < EncodingError
+    end
 
+    # A return_to is outside the trust_root.
     class UntrustedReturnURL < ProtocolError
-
       attr_reader :return_to, :trust_root
 
-      def initialize(query, return_to, trust_root)
-        super(query)
+      def initialize(message, return_to, trust_root)
+        super(message)
         @return_to = return_to
-        @trust_root = trust_root        
+        @trust_root = trust_root
+      end
+
+      def to_s
+        return sprintf("return_to %s not under trust_root %s",
+                       @return_to,
+                       @trust_root)
       end
     end
 
-  end
+    # The return_to URL doesn't look like a valid URL.
+    class MalformedReturnURL < ProtocolError
+      attr_reader :return_to
 
+      def initialize(openid_message, return_to)
+        @return_to = return_to
+        super(openid_message)
+      end
+    end
+
+    # The trust root is not well-formed.
+    class MalformedTrustRoot < ProtocolError
+    end
+  end
 end