ruby-openid2 3.0.0

data/lib/openid/server.rb

@@ -0,0 +1,1571 @@
+require_relative "cryptutil"
+require_relative "util"
+require_relative "dh"
+require_relative "store/nonce"
+require_relative "trustroot"
+require_relative "association"
+require_relative "message"
+
+require "time"
+
+module OpenID
+  module Server
+    HTTP_OK = 200
+    HTTP_REDIRECT = 302
+    HTTP_ERROR = 400
+
+    BROWSER_REQUEST_MODES = %w[checkid_setup checkid_immediate]
+
+    ENCODE_KVFORM = ["kvform"].freeze
+    ENCODE_URL = ["URL/redirect"].freeze
+    ENCODE_HTML_FORM = ["HTML form"].freeze
+
+    UNUSED = nil
+
+    class OpenIDRequest
+      attr_accessor :message, :mode
+
+      # I represent an incoming OpenID request.
+      #
+      # Attributes:
+      # mode:: The "openid.mode" of this request
+      def initialize
+        @mode = nil
+        @message = nil
+      end
+
+      def namespace
+        raise "Request has no message" if @message.nil?
+
+        @message.get_openid_namespace
+      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
+      # 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.
+      #
+      # These parameters are assigned directly as class attributes.
+      #
+      # 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 = %w[identity return_to response_nonce].freeze
+
+        @sig = nil
+        @assoc_handle = assoc_handle
+        @signed = signed
+        @invalidate_handle = invalidate_handle
+      end
+
+      # 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
+        signed.set_arg(OPENID_NS, "mode", "id_res") if signed.has_key?(OPENID_NS, "mode")
+
+        obj = new(assoc_handle, signed, invalidate_handle)
+        obj.message = message
+        obj.sig = message.get_arg(OPENID_NS, "sig")
+
+        if !obj.assoc_handle or
+            !obj.sig
+          msg = format(
+            "%s request missing required parameter from message %s",
+            obj.mode,
+            message,
+          )
+          raise ProtocolError.new(message, msg)
+        end
+
+        obj
+      end
+
+      # 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, @signed)
+        # Now invalidate that assoc_handle so it this checkAuth
+        # message cannot be replayed.
+        signatory.invalidate(@assoc_handle, true)
+        response = OpenIDResponse.new(self)
+        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.set_arg(
+              OPENID_NS, "invalidate_handle", @invalidate_handle
+            )
+          end
+        end
+
+        response
+      end
+
+      def to_s
+        ih = nil
+
+        ih = if @invalidate_handle
+          format(" invalidate? %s", @invalidate_handle)
+        else
+          ""
+        end
+
+        format(
+          "<%s handle: %s sig: %s: signed: %s%s>",
+          self.class,
+          @assoc_handle,
+          @sig,
+          @signed,
+          ih,
+        )
+      end
+    end
+
+    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
+        super("no-encryption", %w[HMAC-SHA1 HMAC-SHA256])
+      end
+
+      def self.from_message(_unused_request)
+        new
+      end
+
+      def answer(secret)
+        {"mac_key" => Util.to_base64(secret)}
+      end
+    end
+
+    # 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
+
+      def initialize(dh, consumer_pubkey)
+        super("DH-SHA1", ["HMAC-SHA1"])
+
+        @hash_func = CryptUtil.method(:sha1)
+        @dh = dh
+        @consumer_pubkey = consumer_pubkey
+      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)
+
+          missing = if !dh_modulus
+            "modulus"
+          else
+            "generator"
+          end
+
+          raise ProtocolError.new(
+            message,
+            format(
+              "If non-default modulus or generator is " +
+                                  "supplied, both must be supplied. Missing %s",
+              missing,
+            ),
+          )
+        end
+
+        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 = message.get_arg(OPENID_NS, "dh_consumer_public")
+        unless consumer_pubkey
+          raise ProtocolError.new(
+            message,
+            format(
+              "Public key for DH-SHA1 session " +
+                                  "not found in message %s",
+              message,
+            ),
+          )
+        end
+
+        consumer_pubkey = CryptUtil.base64_to_num(consumer_pubkey)
+
+        new(dh, consumer_pubkey)
+      end
+
+      def answer(secret)
+        mac_key = @dh.xor_secret(
+          @hash_func,
+          @consumer_pubkey,
+          secret,
+        )
+        {
+          "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
+        @session_type = "DH-SHA256"
+        @hash_func = CryptUtil.method(:sha256)
+        @allowed_assoc_types = ["HMAC-SHA256"].freeze
+      end
+    end
+
+    # 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
+
+      @@session_classes = {
+        "no-encryption" => PlainTextServerSession,
+        "DH-SHA1" => DiffieHellmanSHA1ServerSession,
+        "DH-SHA256" => DiffieHellmanSHA256ServerSession,
+      }
+
+      # 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
+
+        @mode = "associate"
+      end
+
+      # Construct me from an OpenID Message.
+      def self.from_message(message, _op_endpoint = UNUSED)
+        if message.is_openid1
+          session_type = message.get_arg(OPENID_NS, "session_type")
+          if session_type == "no-encryption"
+            Util.log("Received OpenID 1 request with a no-encryption " +
+                     "association session type. Continuing anyway.")
+          elsif !session_type
+            session_type = "no-encryption"
+          end
+        else
+          session_type = message.get_arg(OPENID2_NS, "session_type")
+          unless session_type
+            raise ProtocolError.new(
+              message,
+              "session_type missing from request",
+            )
+          end
+        end
+
+        session_class = @@session_classes[session_type]
+
+        unless session_class
+          raise ProtocolError.new(
+            message,
+            format("Unknown session type %s", session_type),
+          )
+        end
+
+        begin
+          session = session_class.from_message(message)
+        rescue ArgumentError => e
+          # XXX
+          raise ProtocolError.new(
+            message,
+            format(
+              "Error parsing %s session: %s",
+              session_type,
+              e,
+            ),
+          )
+        end
+
+        assoc_type = message.get_arg(OPENID_NS, "assoc_type", "HMAC-SHA1")
+        unless session.allowed_assoc_type?(assoc_type)
+          msg = format(
+            "Session type %s does not support association type %s",
+            session_type,
+            assoc_type,
+          )
+          raise ProtocolError.new(message, msg)
+        end
+
+        obj = new(session, assoc_type)
+        obj.message = message
+        obj
+      end
+
+      # 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" => format("%d", assoc.expires_in),
+          "assoc_type" => @assoc_type,
+          "assoc_handle" => assoc.handle,
+        })
+        response.fields.update_args(
+          OPENID_NS,
+          @session.answer(assoc.secret),
+        )
+        unless @session.session_type == "no-encryption" and
+            @message.is_openid1
+          response.fields.set_arg(
+            OPENID_NS, "session_type", @session.session_type
+          )
+        end
+
+        response
+      end
+
+      # 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)
+        raise ProtocolError.new(@message) if @message.is_openid1
+
+        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
+
+        response
+      end
+    end
+
+    # A request to confirm the identity of a user.
+    #
+    # This class handles requests for openid modes
+    # +checkid_immediate+ and +checkid_setup+ .
+    class CheckIDRequest < OpenIDRequest
+      # 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 :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, claimed_id = nil)
+        @assoc_handle = assoc_handle
+        @identity = identity
+        @claimed_id = (claimed_id or identity)
+        @return_to = return_to
+        @trust_root = (trust_root or return_to)
+        @op_endpoint = op_endpoint
+        @message = nil
+
+        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
+
+        return if trust_root_valid
+
+        raise UntrustedReturnURL.new(nil, @return_to, @trust_root)
+      end
+
+      # 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 = allocate
+        obj.message = message
+        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
+
+        obj.return_to = message.get_arg(OPENID_NS, "return_to")
+        if message.is_openid1 and !obj.return_to
+          msg = format(
+            "Missing required field 'return_to' from %s",
+            message,
+          )
+          raise ProtocolError.new(message, msg)
+        end
+
+        obj.identity = message.get_arg(OPENID_NS, "identity")
+        obj.claimed_id = message.get_arg(OPENID_NS, "claimed_id")
+        if message.is_openid1
+          unless obj.identity
+            s = "OpenID 1 message did not contain openid.identity"
+            raise ProtocolError.new(message, s)
+          end
+        elsif obj.identity and !obj.claimed_id
+          s = ("OpenID 2.0 message contained openid.identity but not " +
+                 "claimed_id")
+          raise ProtocolError.new(message, s)
+        elsif obj.claimed_id and !obj.identity
+          s = ("OpenID 2.0 message contained openid.claimed_id but not " +
+               "identity")
+          raise ProtocolError.new(message, s)
+        end
+
+        # 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.
+        trust_root_param = if message.is_openid1
+          "trust_root"
+        else
+          "realm"
+        end
+        trust_root = message.get_arg(OPENID_NS, trust_root_param)
+        trust_root = obj.return_to if trust_root.nil? || trust_root.empty?
+        obj.trust_root = trust_root
+
+        if !message.is_openid1 and !obj.return_to and !obj.trust_root
+          raise ProtocolError.new(message, "openid.realm required when " +
+                                  "openid.return_to absent")
+        end
+
+        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
+
+        # 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?
+        raise UntrustedReturnURL.new(message, obj.return_to, obj.trust_root) unless obj.trust_root_valid
+
+        obj
+      end
+
+      # Is the identifier to be selected by the IDP?
+      def id_select
+        # So IDPs don't have to import the constant
+        @identity == IDENTIFIER_SELECT
+      end
+
+      # Is my return_to under my trust_root?
+      def trust_root_valid
+        return true unless @trust_root
+
+        tr = TrustRoot::TrustRoot.parse(@trust_root)
+        raise MalformedTrustRoot.new(@message, @trust_root) unless tr
+
+        return tr.validate_url(@return_to) if @return_to
+
+        true
+      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
+        TrustRoot.verify_return_to(@trust_root, @return_to)
+      end
+
+      # Respond to this request.
+      #
+      # allow:: Allow this user to claim this identity, and allow the
+      #         consumer to have this information?
+      #
+      # server_url:: DEPRECATED.  Passing op_endpoint to the
+      #              #Server constructor makes this optional.
+      #
+      #              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.
+      #
+      #              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.
+      #
+      # Returns an OpenIDResponse object containing a OpenID id_res message.
+      #
+      # Raises NoReturnToError if the return_to is missing.
+      #
+      # Version 2.0 deprecates +server_url+ and adds +claimed_id+.
+      def answer(allow, server_url = nil, identity = nil, claimed_id = nil)
+        raise NoReturnToError unless @return_to
+
+        unless server_url
+          if @message.is_openid2 and !@op_endpoint
+            # In other words, that warning I raised in
+            # Server.__init__?  You should pay attention to it now.
+            raise "#{self} should be constructed with " \
+              "op_endpoint to respond to OpenID 2.0 " \
+              "messages."
+          end
+
+          server_url = @op_endpoint
+        end
+
+        mode = if allow
+          "id_res"
+        elsif @message.is_openid1
+          if @immediate
+            "id_res"
+          else
+            "cancel"
+          end
+        elsif @immediate
+          "setup_needed"
+        else
+          "cancel"
+        end
+
+        response = OpenIDResponse.new(self)
+
+        if claimed_id and @message.is_openid1
+          raise VersionError, "claimed_id is new in OpenID 2.0 and not " \
+            "available for #{@message.get_openid_namespace}"
+        end
+
+        claimed_id = identity if identity and !claimed_id
+
+        if allow
+          if @identity == IDENTIFIER_SELECT
+            unless 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 @message.is_openid1 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 @message.is_openid2
+              response.fields.set_arg(
+                OPENID_NS,
+                "claimed_id",
+                response_claimed_id,
+              )
+            end
+          end
+        else
+          response.fields.set_arg(OPENID_NS, "mode", mode)
+          if @immediate
+            if @message.is_openid1 and !server_url
+              raise ArgumentError, "setup_url is required for allow=false " \
+                "in OpenID 1.x immediate mode."
+            end
+
+            # 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,
+              @claimed_id,
+            )
+            setup_request.message = Message.new(@message.get_openid_namespace)
+            setup_url = setup_request.encode_to_url(server_url)
+            response.fields.set_arg(OPENID_NS, "user_setup_url", setup_url)
+          end
+        end
+
+        response
+      end
+
+      def encode_to_url(server_url)
+        # Encode this request as a URL to GET.
+        #
+        # server_url:: The URL of the OpenID server to make this
+        #              request of.
+        raise NoReturnToError unless @return_to
+
+        # 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 @message.is_openid1
+            q["trust_root"] = @trust_root
+          else
+            q["realm"] = @trust_root
+          end
+        end
+
+        q["assoc_handle"] = @assoc_handle if @assoc_handle
+
+        response = Message.new(@message.get_openid_namespace)
+        response.update_args(@message.get_openid_namespace, q)
+        response.to_url(server_url)
+      end
+
+      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.
+        raise NoReturnToError unless @return_to
+
+        if @immediate
+          raise ArgumentError.new("Cancel is not an appropriate response to " +
+                                  "immediate mode requests.")
+        end
+
+        response = Message.new(@message.get_openid_namespace)
+        response.set_arg(OPENID_NS, "mode", "cancel")
+        response.to_url(@return_to)
+      end
+
+      def to_s
+        format(
+          "<%s id:%s im:%s tr:%s ah:%s>",
+          self.class,
+          @identity,
+          @immediate,
+          @trust_root,
+          @assoc_handle,
+        )
+      end
+    end
+
+    # 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
+
+      # 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
+
+      def initialize(request)
+        # Make a response to an OpenIDRequest.
+        @request = request
+        @fields = Message.new(request.namespace)
+      end
+
+      def to_s
+        format(
+          "%s for %s: %s",
+          self.class,
+          @request.class,
+          @fields,
+        )
+      end
+
+      # form_tag_attrs is a hash of attributes to be added to the form
+      # tag. 'accept-charset' and 'enctype' have defaults that can be
+      # overridden. If a value is supplied for 'action' or 'method',
+      # it will be replaced.
+      # Returns the form markup for this response.
+      def to_form_markup(form_tag_attrs = nil)
+        @fields.to_form_markup(@request.return_to, form_tag_attrs)
+      end
+
+      # Wraps the form tag from to_form_markup in a complete HTML document
+      # that uses javascript to autosubmit the form.
+      def to_html(form_tag_attrs = nil)
+        Util.auto_submit_html(to_form_markup(form_tag_attrs))
+      end
+
+      def render_as_form
+        # Returns true if this response's encoding is
+        # ENCODE_HTML_FORM.  Convenience method for server authors.
+        which_encoding == ENCODE_HTML_FORM
+      end
+
+      def needs_signing
+        # Does this response require signing?
+        @fields.get_arg(OPENID_NS, "mode") == "id_res"
+      end
+
+      # implements IEncodable
+
+      def which_encoding
+        # How should I be encoded?
+        # returns one of ENCODE_URL or ENCODE_KVFORM.
+        return ENCODE_KVFORM unless BROWSER_REQUEST_MODES.member?(@request.mode)
+
+        if @fields.is_openid2 and
+            encode_to_url.length > OPENID1_URL_LIMIT
+          ENCODE_HTML_FORM
+        else
+          ENCODE_URL
+        end
+      end
+
+      def encode_to_url
+        # Encode a response as a URL for the user agent to GET.
+        # You will generally use this URL with a HTTP redirect.
+        @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
+
+      def encode_to_kvform
+        # 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>
+        @fields.to_kvform
+      end
+
+      def copy
+        Marshal.load(Marshal.dump(self))
+      end
+    end
+
+    # 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
+        @headers = headers || {}
+        @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
+      # 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.truthy_assert(store)
+        @store = store
+        @secret_lifetime = 14 * 24 * 60 * 60
+      end
+
+      # Verify that the signature for some data is valid.
+      def verify(assoc_handle, message)
+        assoc = get_association(assoc_handle, true)
+        unless assoc
+          Util.log(format(
+            "failed to get assoc with handle %s to verify " +
+                                       "message %s",
+            assoc_handle,
+            message,
+          ))
+          return false
+        end
+
+        begin
+          valid = assoc.check_message_signature(message)
+        rescue StandardError => e
+          Util.log(format(
+            "Error in verifying %s with %s: %s",
+            message,
+            assoc,
+            e,
+          ))
+          return false
+        end
+
+        valid
+      end
+
+      # 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)
+        signed_response = response.copy
+        assoc_handle = response.request.assoc_handle
+        if assoc_handle
+          # 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 = create_association(true)
+        end
+
+        begin
+          signed_response.fields = assoc.sign_message(signed_response.fields)
+        rescue KVFormError => e
+          raise EncodingError, e
+        end
+        signed_response
+      end
+
+      # Make a new association.
+      def create_association(dumb = true, assoc_type = "HMAC-SHA1")
+        secret = CryptUtil.random_string(OpenID.get_secret_size(assoc_type))
+        uniq = Util.to_base64(CryptUtil.random_string(4))
+        handle = format("{%s}{%x}{%s}", assoc_type, Time.now.to_i, uniq)
+
+        assoc = Association.from_expires_in(
+          secret_lifetime, handle, secret, assoc_type
+        )
+
+        key = if dumb
+          @@_dumb_key
+        else
+          @@_normal_key
+        end
+
+        @store.store_association(key, assoc)
+        assoc
+      end
+
+      # Get the association with the specified handle.
+      def get_association(assoc_handle, dumb, check_expiration = 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.
+
+        raise ArgumentError.new("assoc_handle must not be None") unless assoc_handle
+
+        key = if dumb
+          @@_dumb_key
+        else
+          @@_normal_key
+        end
+
+        assoc = @store.get_association(key, assoc_handle)
+        if assoc and assoc.expires_in <= 0
+          Util.log(format(
+            "requested %sdumb key %s is expired (by %s seconds)",
+            (!dumb) ? "not-" : "",
+            assoc_handle,
+            assoc.expires_in,
+          ))
+          if check_expiration
+            @store.remove_association(key, assoc_handle)
+            assoc = nil
+          end
+        end
+
+        assoc
+      end
+
+      # Invalidates the association with the given handle.
+      def invalidate(assoc_handle, dumb)
+        key = if dumb
+          @@_dumb_key
+        else
+          @@_normal_key
+        end
+
+        @store.remove_association(key, assoc_handle)
+      end
+    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
+
+      # Encode a response to a WebResponse.
+      #
+      # Raises EncodingError when I can't figure out how to encode
+      # this message.
+      def encode(response)
+        encode_as = response.which_encoding
+        if encode_as == ENCODE_KVFORM
+          wr = @@responseFactory.new(
+            HTTP_OK,
+            nil,
+            response.encode_to_kvform,
+          )
+          wr.code = HTTP_ERROR if response.is_a?(Exception)
+        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
+          # 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
+
+        wr
+      end
+    end
+
+    # 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)
+        @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)
+        # 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
+          unless @signatory
+            raise ArgumentError.new(
+              format(
+                "Must have a store to sign this request: %s",
+                response,
+              ),
+              response,
+            )
+          end
+
+          raise AlreadySigned.new(response) if response.fields.has_key?(OPENID_NS, "sig")
+
+          response = @signatory.sign(response)
+        end
+
+        super
+      end
+    end
+
+    # I decode an incoming web request in to a OpenIDRequest.
+    class Decoder
+      @@handlers = {
+        "checkid_setup" => CheckIDRequest.method(:from_message),
+        "checkid_immediate" => CheckIDRequest.method(:from_message),
+        "check_authentication" => CheckAuthRequest.method(:from_message),
+        "associate" => AssociateRequest.method(:from_message),
+      }
+
+      attr_accessor :server
+
+      # Construct a Decoder. The server is necessary because some
+      # replies reference their server.
+      def initialize(server)
+        @server = server
+      end
+
+      # 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)
+        return if query.nil? or query.empty?
+
+        begin
+          message = Message.from_post_args(query)
+        rescue InvalidOpenIDNamespace => e
+          query = query.dup
+          query["openid.ns"] = OPENID2_NS
+          message = Message.from_post_args(query)
+          raise ProtocolError.new(message, e.to_s)
+        end
+
+        mode = message.get_arg(OPENID_NS, "mode")
+        unless mode
+          msg = format("No mode value in message %s", message)
+          raise ProtocolError.new(message, msg)
+        end
+
+        handler = @@handlers.fetch(mode, method(:default_decoder))
+        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 = format("Unrecognized OpenID mode %s", mode)
+        raise ProtocolError.new(message, msg)
+      end
+    end
+
+    # I handle requests for an OpenID server.
+    #
+    # 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.
+    #
+    # For your convenience, I also provide an interface to
+    # Decoder.decode and SigningEncoder.encode through my methods
+    # decodeRequest and encodeResponse.
+    #
+    # All my state is encapsulated in an store, which means I'm not
+    # generally pickleable but I am easy to reconstruct.
+    class Server
+      @@signatoryClass = Signatory
+      @@encoderClass = SigningEncoder
+      @@decoderClass = Decoder
+
+      # 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 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)
+        begin
+          handler = method("openid_" + request.mode)
+        rescue NameError
+          raise format(
+            "%s has no handler for a request of mode %s.",
+            self,
+            request.mode,
+          ).to_s
+        end
+
+        handler.call(request)
+      end
+
+      # Handle and respond to check_authentication requests.
+      def openid_check_authentication(request)
+        request.answer(@signatory)
+      end
+
+      # Handle and respond to associate requests.
+      def openid_associate(request)
+        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,
+          )
+          request.answer(assoc)
+        else
+          message = format(
+            "Association type %s is not supported with " +
+                                        "session type %s",
+            assoc_type,
+            session_type,
+          )
+          preferred_assoc_type, preferred_session_type = @negotiator.get_allowed_type
+          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)
+        @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)
+        @encoder.encode(response)
+      end
+    end
+
+    # A message did not conform to the OpenID protocol.
+    class ProtocolError < Exception
+      # The query that is failing to be a valid OpenID request.
+      attr_accessor :openid_message
+      attr_accessor :reference, :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.truthy_assert(!message.is_a?(String))
+        super(text)
+      end
+
+      # Get the return_to argument from the request, if any.
+      def get_return_to
+        return if @openid_message.nil?
+
+        @openid_message.get_arg(OPENID_NS, "return_to")
+      end
+
+      # Did this request have a return_to parameter?
+      def has_return_to
+        !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", to_s)
+
+        reply.set_arg(OPENID_NS, "contact", @contact.to_s) if @contact
+
+        reply.set_arg(OPENID_NS, "reference", @reference.to_s) if @reference
+
+        reply
+      end
+
+      # implements IEncodable
+
+      def encode_to_url
+        to_message.to_url(get_return_to)
+      end
+
+      def encode_to_kvform
+        to_message.to_kvform
+      end
+
+      def to_form_markup
+        to_message.to_form_markup(get_return_to)
+      end
+
+      def to_html
+        Util.auto_submit_html(to_form_markup)
+      end
+
+      # 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.is_openid2 and
+              encode_to_url.length > OPENID1_URL_LIMIT
+            return ENCODE_HTML_FORM
+          else
+            return ENCODE_URL
+          end
+        end
+
+        return if @openid_message.nil?
+
+        mode = @openid_message.get_arg(OPENID_NS, "mode")
+        return ENCODE_KVFORM if mode && !BROWSER_REQUEST_MODES.member?(mode)
+
+        # 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.
+        nil
+      end
+    end
+
+    # Raised when an operation was attempted that is not compatible
+    # with the protocol version being used.
+    class VersionError < Exception
+    end
+
+    # Raised when a response to a request cannot be generated
+    # because the request contains no return_to URL.
+    class NoReturnToError < Exception
+    end
+
+    # 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
+      end
+    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(message, return_to, trust_root)
+        super(message)
+        @return_to = return_to
+        @trust_root = trust_root
+      end
+
+      def to_s
+        format(
+          "return_to %s not under trust_root %s",
+          @return_to,
+          @trust_root,
+        )
+      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