entp-ruby-openid 2.2

data/lib/openid/consumer.rb

@@ -0,0 +1,395 @@
+require "openid/consumer/idres.rb"
+require "openid/consumer/checkid_request.rb"
+require "openid/consumer/associationmanager.rb"
+require "openid/consumer/responses.rb"
+require "openid/consumer/discovery_manager"
+require "openid/consumer/discovery"
+require "openid/message"
+require "openid/yadis/discovery"
+require "openid/store/nonce"
+
+module OpenID
+  # OpenID support for Relying Parties (aka Consumers).
+  #
+  # This module documents the main interface with the OpenID consumer
+  # library.  The only part of the library which has to be used and
+  # isn't documented in full here is the store required to create an
+  # Consumer instance.
+  #
+  # = OVERVIEW
+  #
+  # The OpenID identity verification process most commonly uses the
+  # following steps, as visible to the user of this library:
+  #
+  # 1. The user enters their OpenID into a field on the consumer's
+  #    site, and hits a login button.
+  #
+  # 2. The consumer site discovers the user's OpenID provider using
+  #    the Yadis protocol.
+  #
+  # 3. The consumer site sends the browser a redirect to the OpenID
+  #    provider.  This is the authentication request as described in
+  #    the OpenID specification.
+  #
+  # 4. The OpenID provider's site sends the browser a redirect back to
+  #    the consumer site.  This redirect contains the provider's
+  #    response to the authentication request.
+  #
+  # The most important part of the flow to note is the consumer's site
+  # must handle two separate HTTP requests in order to perform the
+  # full identity check.
+  #
+  # = LIBRARY DESIGN
+  #
+  # This consumer library is designed with that flow in mind.  The
+  # goal is to make it as easy as possible to perform the above steps
+  # securely.
+  #
+  # At a high level, there are two important parts in the consumer
+  # library.  The first important part is this module, which contains
+  # the interface to actually use this library.  The second is
+  # openid/store/interface.rb, which describes the interface to use if
+  # you need to create a custom method for storing the state this
+  # library needs to maintain between requests.
+  #
+  # In general, the second part is less important for users of the
+  # library to know about, as several implementations are provided
+  # which cover a wide variety of situations in which consumers may
+  # use the library.
+  #
+  # The Consumer class has methods corresponding to the actions
+  # necessary in each of steps 2, 3, and 4 described in the overview.
+  # Use of this library should be as easy as creating an Consumer
+  # instance and calling the methods appropriate for the action the
+  # site wants to take.
+  #
+  # This library automatically detects which version of the OpenID
+  # protocol should be used for a transaction and constructs the
+  # proper requests and responses.  Users of this library do not need
+  # to worry about supporting multiple protocol versions; the library
+  # supports them implicitly.  Depending on the version of the
+  # protocol in use, the OpenID transaction may be more secure.  See
+  # the OpenID specifications for more information.
+  #
+  # = SESSIONS, STORES, AND STATELESS MODE
+  #
+  # The Consumer object keeps track of two types of state:
+  #
+  # 1. State of the user's current authentication attempt.  Things
+  #    like the identity URL, the list of endpoints discovered for
+  #    that URL, and in case where some endpoints are unreachable, the
+  #    list of endpoints already tried.  This state needs to be held
+  #    from Consumer.begin() to Consumer.complete(), but it is only
+  #    applicable to a single session with a single user agent, and at
+  #    the end of the authentication process (i.e. when an OP replies
+  #    with either <tt>id_res</tt>. or <tt>cancel</tt> it may be
+  #    discarded.
+  #
+  # 2. State of relationships with servers, i.e. shared secrets
+  #    (associations) with servers and nonces seen on signed messages.
+  #    This information should persist from one session to the next
+  #    and should not be bound to a particular user-agent.
+  #
+  # These two types of storage are reflected in the first two
+  # arguments of Consumer's constructor, <tt>session</tt> and
+  # <tt>store</tt>.  <tt>session</tt> is a dict-like object and we
+  # hope your web framework provides you with one of these bound to
+  # the user agent.  <tt>store</tt> is an instance of Store.
+  #
+  # Since the store does hold secrets shared between your application
+  # and the OpenID provider, you should be careful about how you use
+  # it in a shared hosting environment.  If the filesystem or database
+  # permissions of your web host allow strangers to read from them, do
+  # not store your data there!  If you have no safe place to store
+  # your data, construct your consumer with nil for the store, and it
+  # will operate only in stateless mode.  Stateless mode may be
+  # slower, put more load on the OpenID provider, and trusts the
+  # provider to keep you safe from replay attacks.
+  #
+  # Several store implementation are provided, and the interface is
+  # fully documented so that custom stores can be used as well.  See
+  # the documentation for the Consumer class for more information on
+  # the interface for stores.  The implementations that are provided
+  # allow the consumer site to store the necessary data in several
+  # different ways, including several SQL databases and normal files
+  # on disk.
+  #
+  # = IMMEDIATE MODE
+  #
+  # In the flow described above, the user may need to confirm to the
+  # OpenID provider that it's ok to disclose his or her identity.  The
+  # provider may draw pages asking for information from the user
+  # before it redirects the browser back to the consumer's site.  This
+  # is generally transparent to the consumer site, so it is typically
+  # ignored as an implementation detail.
+  #
+  # There can be times, however, where the consumer site wants to get
+  # a response immediately.  When this is the case, the consumer can
+  # put the library in immediate mode.  In immediate mode, there is an
+  # extra response possible from the server, which is essentially the
+  # server reporting that it doesn't have enough information to answer
+  # the question yet.
+  #
+  # = USING THIS LIBRARY
+  #
+  # Integrating this library into an application is usually a
+  # relatively straightforward process.  The process should basically
+  # follow this plan:
+  #
+  # Add an OpenID login field somewhere on your site.  When an OpenID
+  # is entered in that field and the form is submitted, it should make
+  # a request to the your site which includes that OpenID URL.
+  #
+  # First, the application should instantiate a Consumer with a
+  # session for per-user state and store for shared state using the
+  # store of choice.
+  #
+  # Next, the application should call the <tt>begin</tt> method of
+  # Consumer instance.  This method takes the OpenID URL as entered by
+  # the user.  The <tt>begin</tt> method returns a CheckIDRequest
+  # object.
+  #
+  # Next, the application should call the redirect_url method on the
+  # CheckIDRequest object.  The parameter <tt>return_to</tt> is the
+  # URL that the OpenID server will send the user back to after
+  # attempting to verify his or her identity.  The <tt>realm</tt>
+  # parameter is the URL (or URL pattern) that identifies your web
+  # site to the user when he or she is authorizing it.  Send a
+  # redirect to the resulting URL to the user's browser.
+  #
+  # That's the first half of the authentication process.  The second
+  # half of the process is done after the user's OpenID Provider sends
+  # the user's browser a redirect back to your site to complete their
+  # login.
+  #
+  # When that happens, the user will contact your site at the URL
+  # given as the <tt>return_to</tt> URL to the redirect_url call made
+  # above.  The request will have several query parameters added to
+  # the URL by the OpenID provider as the information necessary to
+  # finish the request.
+  #
+  # Get a Consumer instance with the same session and store as before
+  # and call its complete() method, passing in all the received query
+  # arguments and URL currently being handled.
+  #
+  # There are multiple possible return types possible from that
+  # method. These indicate the whether or not the login was
+  # successful, and include any additional information appropriate for
+  # their type.
+  class Consumer
+    attr_accessor :session_key_prefix
+
+    # Initialize a Consumer instance.
+    #
+    # You should create a new instance of the Consumer object with
+    # every HTTP request that handles OpenID transactions.
+    #
+    # session: the session object to use to store request information.
+    # The session should behave like a hash.
+    #
+    # store: an object that implements the interface in Store.
+    def initialize(session, store)
+      @session = session
+      @store = store
+      @session_key_prefix = 'OpenID::Consumer::'
+    end
+
+    # Start the OpenID authentication process. See steps 1-2 in the
+    # overview for the Consumer class.
+    #
+    # user_url: Identity URL given by the user. This method performs a
+    # textual transformation of the URL to try and make sure it is
+    # normalized. For example, a user_url of example.com will be
+    # normalized to http://example.com/ normalizing and resolving any
+    # redirects the server might issue.
+    #
+    # anonymous: A boolean value.  Whether to make an anonymous
+    # request of the OpenID provider.  Such a request does not ask for
+    # an authorization assertion for an OpenID identifier, but may be
+    # used with extensions to pass other data.  e.g. "I don't care who
+    # you are, but I'd like to know your time zone."
+    #
+    # Returns a CheckIDRequest object containing the discovered
+    # information, with a method for building a redirect URL to the
+    # server, as described in step 3 of the overview. This object may
+    # also be used to add extension arguments to the request, using
+    # its add_extension_arg method.
+    #
+    # Raises DiscoveryFailure when no OpenID server can be found for
+    # this URL.
+    def begin(openid_identifier, anonymous=false)
+      manager = discovery_manager(openid_identifier)
+      service = manager.get_next_service(&method(:discover))
+
+      if service.nil?
+        raise DiscoveryFailure.new("No usable OpenID services were found "\
+                                   "for #{openid_identifier.inspect}", nil)
+      else
+        begin_without_discovery(service, anonymous)
+      end
+    end
+
+    # Start OpenID verification without doing OpenID server
+    # discovery. This method is used internally by Consumer.begin()
+    # after discovery is performed, and exists to provide an interface
+    # for library users needing to perform their own discovery.
+    #
+    # service: an OpenID service endpoint descriptor.  This object and
+    # factories for it are found in the openid/consumer/discovery.rb
+    # module.
+    #
+    # Returns an OpenID authentication request object.
+    def begin_without_discovery(service, anonymous)
+      assoc = association_manager(service).get_association
+      checkid_request = CheckIDRequest.new(assoc, service)
+      checkid_request.anonymous = anonymous
+
+      if service.compatibility_mode
+        rt_args = checkid_request.return_to_args
+        rt_args[Consumer.openid1_return_to_nonce_name] = Nonce.mk_nonce
+        rt_args[Consumer.openid1_return_to_claimed_id_name] =
+          service.claimed_id
+      end
+
+      self.last_requested_endpoint = service
+      return checkid_request
+    end
+
+    # Called to interpret the server's response to an OpenID
+    # request. It is called in step 4 of the flow described in the
+    # Consumer overview.
+    #
+    # query: A hash of the query parameters for this HTTP request.
+    # Note that in rails, this is <b>not</b> <tt>params</tt> but
+    # <tt>params.reject{|k,v|request.path_parameters[k]}</tt>
+    # because <tt>controller</tt> and <tt>action</tt> and other
+    # "path parameters" are included in params.
+    #
+    # current_url: Extract the URL of the current request from your
+    # application's web request framework and specify it here to have it
+    # checked against the openid.return_to value in the response.  Do not
+    # just pass <tt>args['openid.return_to']</tt> here; that will defeat the
+    # purpose of this check.  (See OpenID Authentication 2.0 section 11.1.)
+    #
+    # If the return_to URL check fails, the status of the completion will be
+    # FAILURE.
+
+    #
+    # Returns a subclass of Response. The type of response is
+    # indicated by the status attribute, which will be one of
+    # SUCCESS, CANCEL, FAILURE, or SETUP_NEEDED.
+    def complete(query, current_url)
+      message = Message.from_post_args(query)
+      mode = message.get_arg(OPENID_NS, 'mode', 'invalid')
+      begin
+        meth = method('complete_' + mode)
+      rescue NameError
+        meth = method(:complete_invalid)
+      end
+      response = meth.call(message, current_url)
+      cleanup_last_requested_endpoint
+      if [SUCCESS, CANCEL].member?(response.status)
+        cleanup_session
+      end
+      return response
+    end
+
+    protected
+
+    def session_get(name)
+      @session[session_key(name)]
+    end
+
+    def session_set(name, val)
+      @session[session_key(name)] = val
+    end
+
+    def session_key(suffix)
+      @session_key_prefix + suffix
+    end
+
+    def last_requested_endpoint
+      session_get('last_requested_endpoint')
+    end
+
+    def last_requested_endpoint=(endpoint)
+      session_set('last_requested_endpoint', endpoint)
+    end
+
+    def cleanup_last_requested_endpoint
+      @session[session_key('last_requested_endpoint')] = nil
+    end
+
+    def discovery_manager(openid_identifier)
+      DiscoveryManager.new(@session, openid_identifier, @session_key_prefix)
+    end
+
+    def cleanup_session
+      discovery_manager(nil).cleanup(true)
+    end
+
+
+    def discover(identifier)
+      OpenID.discover(identifier)
+    end
+
+    def negotiator
+      DefaultNegotiator
+    end
+
+    def association_manager(service)
+      AssociationManager.new(@store, service.server_url,
+                             service.compatibility_mode, negotiator)
+    end
+
+    def handle_idres(message, current_url)
+      IdResHandler.new(message, current_url, @store, last_requested_endpoint)
+    end
+
+    def complete_invalid(message, unused_return_to)
+      mode = message.get_arg(OPENID_NS, 'mode', '<No mode set>')
+      return FailureResponse.new(last_requested_endpoint,
+                                 "Invalid openid.mode: #{mode}")
+    end
+
+    def complete_cancel(unused_message, unused_return_to)
+      return CancelResponse.new(last_requested_endpoint)
+    end
+
+    def complete_error(message, unused_return_to)
+      error = message.get_arg(OPENID_NS, 'error')
+      contact = message.get_arg(OPENID_NS, 'contact')
+      reference = message.get_arg(OPENID_NS, 'reference')
+
+      return FailureResponse.new(last_requested_endpoint,
+                                 error, contact, reference)
+    end
+
+    def complete_setup_needed(message, unused_return_to)
+      if message.is_openid1
+        return complete_invalid(message, nil)
+      else
+        setup_url = message.get_arg(OPENID2_NS, 'user_setup_url')
+        return SetupNeededResponse.new(last_requested_endpoint, setup_url)
+      end
+    end
+
+    def complete_id_res(message, current_url)
+      if message.is_openid1
+        setup_url = message.get_arg(OPENID_NS, 'user_setup_url')
+        if !setup_url.nil?
+          return SetupNeededResponse.new(last_requested_endpoint, setup_url)
+        end
+      end
+
+      begin
+        idres = handle_idres(message, current_url)
+      rescue OpenIDError => why
+        return FailureResponse.new(last_requested_endpoint, why.message)
+      else
+        return SuccessResponse.new(idres.endpoint, message,
+                                     idres.signed_fields)
+      end
+    end
+  end
+end

data/lib/openid/consumer/associationmanager.rb

@@ -0,0 +1,344 @@
+require "openid/dh"
+require "openid/util"
+require "openid/kvpost"
+require "openid/cryptutil"
+require "openid/protocolerror"
+require "openid/association"
+
+module OpenID
+  class Consumer
+
+    # A superclass for implementing Diffie-Hellman association sessions.
+    class DiffieHellmanSession
+      class << self
+        attr_reader :session_type, :secret_size, :allowed_assoc_types,
+          :hashfunc
+      end
+
+      def initialize(dh=nil)
+        if dh.nil?
+          dh = DiffieHellman.from_defaults
+        end
+        @dh = dh
+      end
+
+      # Return the query parameters for requesting an association
+      # using this Diffie-Hellman association session
+      def get_request
+        args = {'dh_consumer_public' => CryptUtil.num_to_base64(@dh.public)}
+        if (!@dh.using_default_values?)
+          args['dh_modulus'] = CryptUtil.num_to_base64(@dh.modulus)
+          args['dh_gen'] = CryptUtil.num_to_base64(@dh.generator)
+        end
+
+        return args
+      end
+
+      # Process the response from a successful association request and
+      # return the shared secret for this association
+      def extract_secret(response)
+        dh_server_public64 = response.get_arg(OPENID_NS, 'dh_server_public',
+                                              NO_DEFAULT)
+        enc_mac_key64 = response.get_arg(OPENID_NS, 'enc_mac_key', NO_DEFAULT)
+        dh_server_public = CryptUtil.base64_to_num(dh_server_public64)
+        enc_mac_key = Util.from_base64(enc_mac_key64)
+        return @dh.xor_secret(self.class.hashfunc,
+                              dh_server_public, enc_mac_key)
+      end
+    end
+
+    # A Diffie-Hellman association session that uses SHA1 as its hash
+    # function
+    class DiffieHellmanSHA1Session < DiffieHellmanSession
+      @session_type = 'DH-SHA1'
+      @secret_size = 20
+      @allowed_assoc_types = ['HMAC-SHA1']
+      @hashfunc = CryptUtil.method(:sha1)
+    end
+
+    # A Diffie-Hellman association session that uses SHA256 as its hash
+    # function
+    class DiffieHellmanSHA256Session < DiffieHellmanSession
+      @session_type = 'DH-SHA256'
+      @secret_size = 32
+      @allowed_assoc_types = ['HMAC-SHA256']
+      @hashfunc = CryptUtil.method(:sha256)
+    end
+
+    # An association session that does not use encryption
+    class NoEncryptionSession
+      class << self
+        attr_reader :session_type, :allowed_assoc_types
+      end
+      @session_type = 'no-encryption'
+      @allowed_assoc_types = ['HMAC-SHA1', 'HMAC-SHA256']
+
+      def get_request
+        return {}
+      end
+
+      def extract_secret(response)
+        mac_key64 = response.get_arg(OPENID_NS, 'mac_key', NO_DEFAULT)
+        return Util.from_base64(mac_key64)
+      end
+    end
+
+    # An object that manages creating and storing associations for an
+    # OpenID provider endpoint
+    class AssociationManager
+      def self.create_session(session_type)
+        case session_type
+        when 'no-encryption'
+          NoEncryptionSession.new
+        when 'DH-SHA1'
+          DiffieHellmanSHA1Session.new
+        when 'DH-SHA256'
+          DiffieHellmanSHA256Session.new
+        else
+          raise ArgumentError, "Unknown association session type: "\
+                               "#{session_type.inspect}"
+        end
+      end
+
+      def initialize(store, server_url, compatibility_mode=false,
+                     negotiator=nil)
+        @store = store
+        @server_url = server_url
+        @compatibility_mode = compatibility_mode
+        @negotiator = negotiator || DefaultNegotiator
+      end
+
+      def get_association
+        if @store.nil?
+          return nil
+        end
+
+        assoc = @store.get_association(@server_url)
+        if assoc.nil? || assoc.expires_in <= 0
+          assoc = negotiate_association
+          if !assoc.nil?
+            @store.store_association(@server_url, assoc)
+          end
+        end
+
+        return assoc
+      end
+
+      def negotiate_association
+        assoc_type, session_type = @negotiator.get_allowed_type
+        begin
+          return request_association(assoc_type, session_type)
+        rescue ServerError => why
+          supported_types = extract_supported_association_type(why, assoc_type)
+          if !supported_types.nil?
+            # Attempt to create an association from the assoc_type and
+            # session_type that the server told us it supported.
+            assoc_type, session_type = supported_types
+            begin
+              return request_association(assoc_type, session_type)
+            rescue ServerError => why
+              Util.log("Server #{@server_url} refused its suggested " \
+                       "association type: session_type=#{session_type}, " \
+                       "assoc_type=#{assoc_type}")
+              return nil
+            end
+          end
+        rescue InvalidOpenIDNamespace
+          Util.log("Server #{@server_url} returned a malformed association " \
+                   "response.  Falling back to check_id mode for this request.")
+          return nil
+        end
+      end
+
+      protected
+      def extract_supported_association_type(server_error, assoc_type)
+        # Any error message whose code is not 'unsupported-type' should
+        # be considered a total failure.
+        if (server_error.error_code != 'unsupported-type' or
+            server_error.message.is_openid1)
+          Util.log("Server error when requesting an association from "\
+                   "#{@server_url}: #{server_error.error_text}")
+          return nil
+        end
+
+        # The server didn't like the association/session type that we
+        # sent, and it sent us back a message that might tell us how to
+        # handle it.
+        Util.log("Unsupported association type #{assoc_type}: "\
+                 "#{server_error.error_text}")
+
+        # Extract the session_type and assoc_type from the error message
+        assoc_type = server_error.message.get_arg(OPENID_NS, 'assoc_type')
+        session_type = server_error.message.get_arg(OPENID_NS, 'session_type')
+
+        if assoc_type.nil? or session_type.nil?
+          Util.log("Server #{@server_url} responded with unsupported "\
+                   "association session but did not supply a fallback.")
+          return nil
+        elsif !@negotiator.allowed?(assoc_type, session_type)
+          Util.log("Server sent unsupported session/association type: "\
+                   "session_type=#{session_type}, assoc_type=#{assoc_type}")
+          return nil
+        else
+          return [assoc_type, session_type]
+        end
+      end
+
+      # Make and process one association request to this endpoint's OP
+      # endpoint URL. Returns an association object or nil if the
+      # association processing failed. Raises ServerError when the
+      # remote OpenID server returns an error.
+      def request_association(assoc_type, session_type)
+        assoc_session, args = create_associate_request(assoc_type, session_type)
+
+        begin
+          response = OpenID.make_kv_post(args, @server_url)
+          return extract_association(response, assoc_session)
+        rescue HTTPStatusError => why
+          Util.log("Got HTTP status error when requesting association: #{why}")
+          return nil
+        rescue Message::KeyNotFound => why
+          Util.log("Missing required parameter in response from "\
+                   "#{@server_url}: #{why}")
+          return nil
+
+        rescue ProtocolError => why
+          Util.log("Protocol error processing response from #{@server_url}: "\
+                   "#{why}")
+          return nil
+        end
+      end
+
+      # Create an association request for the given assoc_type and
+      # session_type. Returns a pair of the association session object
+      # and the request message that will be sent to the server.
+      def create_associate_request(assoc_type, session_type)
+        assoc_session = self.class.create_session(session_type)
+        args = {
+          'mode' => 'associate',
+          'assoc_type' => assoc_type,
+        }
+
+        if !@compatibility_mode
+          args['ns'] = OPENID2_NS
+        end
+
+        # Leave out the session type if we're in compatibility mode
+        # *and* it's no-encryption.
+        if !@compatibility_mode ||
+            assoc_session.class.session_type != 'no-encryption'
+          args['session_type'] = assoc_session.class.session_type
+        end
+
+        args.merge!(assoc_session.get_request)
+        message = Message.from_openid_args(args)
+        return assoc_session, message
+      end
+
+      # Given an association response message, extract the OpenID 1.X
+      # session type. Returns the association type for this message
+      #
+      # This function mostly takes care of the 'no-encryption' default
+      # behavior in OpenID 1.
+      #
+      # If the association type is plain-text, this function will
+      # return 'no-encryption'
+      def get_openid1_session_type(assoc_response)
+        # If it's an OpenID 1 message, allow session_type to default
+        # to nil (which signifies "no-encryption")
+        session_type = assoc_response.get_arg(OPENID_NS, 'session_type')
+
+        # Handle the differences between no-encryption association
+        # respones in OpenID 1 and 2:
+
+        # no-encryption is not really a valid session type for
+        # OpenID 1, but we'll accept it anyway, while issuing a
+        # warning.
+        if session_type == 'no-encryption'
+          Util.log("WARNING: #{@server_url} sent 'no-encryption'"\
+                   "for OpenID 1.X")
+
+        # Missing or empty session type is the way to flag a
+        # 'no-encryption' response. Change the session type to
+        # 'no-encryption' so that it can be handled in the same
+        # way as OpenID 2 'no-encryption' respones.
+        elsif session_type == '' || session_type.nil?
+          session_type = 'no-encryption'
+        end
+
+        return session_type
+      end
+
+      def self.extract_expires_in(message)
+        # expires_in should be a base-10 string.
+        expires_in_str = message.get_arg(OPENID_NS, 'expires_in', NO_DEFAULT)
+        if !(/\A\d+\Z/ =~ expires_in_str)
+          raise ProtocolError, "Invalid expires_in field: #{expires_in_str}"
+        end
+        expires_in_str.to_i
+      end
+
+      # Attempt to extract an association from the response, given the
+      # association response message and the established association
+      # session.
+      def extract_association(assoc_response, assoc_session)
+        # Extract the common fields from the response, raising an
+        # exception if they are not found
+        assoc_type = assoc_response.get_arg(OPENID_NS, 'assoc_type',
+                                            NO_DEFAULT)
+        assoc_handle = assoc_response.get_arg(OPENID_NS, 'assoc_handle',
+                                              NO_DEFAULT)
+        expires_in = self.class.extract_expires_in(assoc_response)
+
+        # OpenID 1 has funny association session behaviour.
+        if assoc_response.is_openid1
+            session_type = get_openid1_session_type(assoc_response)
+        else
+          session_type = assoc_response.get_arg(OPENID2_NS, 'session_type',
+                                                NO_DEFAULT)
+        end
+
+        # Session type mismatch
+        if assoc_session.class.session_type != session_type
+          if (assoc_response.is_openid1 and session_type == 'no-encryption')
+            # In OpenID 1, any association request can result in a
+            # 'no-encryption' association response. Setting
+            # assoc_session to a new no-encryption session should
+            # make the rest of this function work properly for
+            # that case.
+            assoc_session = NoEncryptionSession.new
+          else
+            # Any other mismatch, regardless of protocol version
+            # results in the failure of the association session
+            # altogether.
+            raise ProtocolError, "Session type mismatch. Expected "\
+                                 "#{assoc_session.class.session_type}, got "\
+                                 "#{session_type}"
+          end
+        end
+
+        # Make sure assoc_type is valid for session_type
+        if !assoc_session.class.allowed_assoc_types.member?(assoc_type)
+          raise ProtocolError, "Unsupported assoc_type for session "\
+                               "#{assoc_session.class.session_type} "\
+                               "returned: #{assoc_type}"
+        end
+
+        # Delegate to the association session to extract the secret
+        # from the response, however is appropriate for that session
+        # type.
+        begin
+          secret = assoc_session.extract_secret(assoc_response)
+        rescue Message::KeyNotFound, ArgumentError => why
+          raise ProtocolError, "Malformed response for "\
+                               "#{assoc_session.class.session_type} "\
+                               "session: #{why.message}"
+        end
+
+
+        return Association.from_expires_in(expires_in, assoc_handle, secret,
+                                           assoc_type)
+      end
+    end
+  end
+end