/// <summary>
		/// Analyzes an incoming request message payload to discover what kind of 
		/// message is embedded in it and returns the type, or null if no match is found.
		/// </summary>
		/// <param name="request">
		/// The message that was sent as a request that resulted in the response.
		/// Null on a Consumer site that is receiving an indirect message from the Service Provider.
		/// </param>
		/// <param name="fields">The name/value pairs that make up the message payload.</param>
		/// <returns>
		/// A newly instantiated <see cref="IProtocolMessage"/>-derived object that this message can
		/// deserialize to.  Null if the request isn't recognized as a valid protocol message.
		/// </returns>
		/// <remarks>
		/// The response messages are:
		/// UnauthorizedTokenResponse
		/// AuthorizedTokenResponse
		/// </remarks>
		public virtual IDirectResponseProtocolMessage GetNewResponseMessage(IDirectedProtocolMessage request, IDictionary<string, string> fields) {
			MessageBase message = null;

			// All response messages have the oauth_token field.
			if (!fields.ContainsKey("oauth_token")) {
				return null;
			}

			// All direct message responses should have the oauth_token_secret field.
			if (!fields.ContainsKey("oauth_token_secret")) {
				Logger.OAuth.Error("An OAuth message was expected to contain an oauth_token_secret but didn't.");
				return null;
			}

			var unauthorizedTokenRequest = request as UnauthorizedTokenRequest;
			var authorizedTokenRequest = request as AuthorizedTokenRequest;
			if (unauthorizedTokenRequest != null) {
				Protocol protocol = fields.ContainsKey("oauth_callback_confirmed") ? Protocol.V10a : Protocol.V10;
				message = new UnauthorizedTokenResponse(unauthorizedTokenRequest, protocol.Version);
			} else if (authorizedTokenRequest != null) {
				message = new AuthorizedTokenResponse(authorizedTokenRequest);
			} else {
				Logger.OAuth.ErrorFormat("Unexpected response message given the request type {0}", request.GetType().Name);
				throw new ProtocolException(OAuthStrings.InvalidIncomingMessage);
			}

			if (message != null) {
				message.SetAsIncoming();
			}

			return message;
		}

		/// <summary>
		/// Reads an access token to find out what data it authorizes access to.
		/// </summary>
		/// <param name="message">The message carrying the access token.</param>
		/// <param name="accessToken">The access token.</param>
		/// <param name="user">The user whose data is accessible with this access token.</param>
		/// <param name="scope">The scope of access authorized by this access token.</param>
		/// <returns>
		/// A value indicating whether this access token is valid.
		/// </returns>
		/// <remarks>
		/// This method also responsible to throw a <see cref="ProtocolException"/> or return
		/// <c>false</c> when the access token is expired, invalid, or from an untrusted authorization server.
		/// </remarks>
		public virtual bool TryValidateAccessToken(IDirectedProtocolMessage message, string accessToken, out string user, out HashSet<string> scope) {
			var accessTokenFormatter = AccessToken.CreateFormatter(this.AuthorizationServerPublicSigningKey, this.ResourceServerPrivateEncryptionKey);
			var token = accessTokenFormatter.Deserialize(message, accessToken);
			user = token.User;
			scope = new HashSet<string>(token.Scope, OAuthUtilities.ScopeStringComparer);
			return true;
		}

        /// <summary>
        /// Initializes a new instance of the <see cref="AutoResponsiveRequest"/> class.
        /// </summary>
        /// <param name="request">The request message.</param>
        /// <param name="response">The response that is ready for transmittal.</param>
        internal AutoResponsiveRequest(IDirectedProtocolMessage request, IProtocolMessage response)
            : base(request)
        {
            ErrorUtilities.VerifyArgumentNotNull(response, "response");

            this.response = response;
        }

		/// <summary>
		/// Reads an access token to find out what data it authorizes access to.
		/// </summary>
		/// <param name="message">The message carrying the access token.</param>
		/// <param name="accessToken">The access token.</param>
		/// <param name="user">The user whose data is accessible with this access token.</param>
		/// <param name="scope">The scope of access authorized by this access token.</param>
		/// <returns>
		/// A value indicating whether this access token is valid.
		/// </returns>
		bool IAccessTokenAnalyzer.TryValidateAccessToken(IDirectedProtocolMessage message, string accessToken, out string user, out HashSet<string> scope) {
			Requires.NotNull(message, "message");
			Requires.NotNullOrEmpty(accessToken, "accessToken");
			Contract.Ensures(Contract.Result<bool>() == (Contract.ValueAtReturn<string>(out user) != null));

			throw new NotImplementedException();
		}

        /// <summary>
        /// Initializes a new instance of the <see cref="AutoResponsiveRequest"/> class.
        /// </summary>
        /// <param name="request">The request message.</param>
        /// <param name="response">The response that is ready for transmittal.</param>
        /// <param name="securitySettings">The security settings.</param>
        internal AutoResponsiveRequest(IDirectedProtocolMessage request, IProtocolMessage response, ProviderSecuritySettings securitySettings)
            : base(request, securitySettings)
        {
            ErrorUtilities.VerifyArgumentNotNull(response, "response");

            this.response = response;
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="MessageBase"/> class for direct response messages.
        /// </summary>
        /// <param name="protectionRequired">The level of protection the message requires.</param>
        /// <param name="originatingRequest">The request that asked for this direct response.</param>
        protected MessageBase(MessageProtections protectionRequired, IDirectedProtocolMessage originatingRequest)
        {
            ErrorUtilities.VerifyArgumentNotNull(originatingRequest, "originatingRequest");

            this.protectionRequired = protectionRequired;
            this.transport = MessageTransport.Direct;
            this.originatingRequest = originatingRequest;
        }

		/// <summary>
		/// Initializes a new instance of the <see cref="MessageBase"/> class.
		/// </summary>
		/// <param name="request">The originating request.</param>
		/// <param name="recipient">The recipient of the directed message.  Null if not applicable.</param>
		protected MessageBase(IDirectedProtocolMessage request, Uri recipient = null) {
			Requires.NotNull(request, "request");
			this.originatingRequest = request;
			this.messageTransport = request.Transport;
			this.version = request.Version;
			this.Recipient = recipient;
			this.HttpMethods = HttpDeliveryMethods.GetRequest;
		}

		/// <summary>
		/// Initializes a new instance of the <see cref="MessageBase"/> class.
		/// </summary>
		/// <param name="request">The originating request.</param>
		/// <param name="recipient">The recipient of the directed message.  Null if not applicable.</param>
		protected MessageBase(IDirectedProtocolMessage request, Uri recipient = null) {
			Contract.Requires<ArgumentNullException>(request != null);
			this.originatingRequest = request;
			this.messageTransport = request.Transport;
			this.version = request.Version;
			this.Recipient = recipient;
			this.HttpMethods = HttpDeliveryMethods.GetRequest;
		}

		/// <summary>
		/// Initializes a new instance of the <see cref="MessageBase"/> class for direct response messages.
		/// </summary>
		/// <param name="protectionRequired">The level of protection the message requires.</param>
		/// <param name="originatingRequest">The request that asked for this direct response.</param>
		/// <param name="version">The OAuth version.</param>
		protected MessageBase(MessageProtections protectionRequired, IDirectedProtocolMessage originatingRequest, Version version) {
			Requires.NotNull(originatingRequest, "originatingRequest");
			Requires.NotNull(version, "version");

			this.protectionRequired = protectionRequired;
			this.transport = MessageTransport.Direct;
			this.originatingRequest = originatingRequest;
			this.Version = version;
		}

		/// <summary>
		/// Initializes a new instance of the <see cref="MessageBase"/> class for direct response messages.
		/// </summary>
		/// <param name="protectionRequired">The level of protection the message requires.</param>
		/// <param name="originatingRequest">The request that asked for this direct response.</param>
		/// <param name="version">The OAuth version.</param>
		protected MessageBase(MessageProtections protectionRequired, IDirectedProtocolMessage originatingRequest, Version version) {
			Contract.Requires<ArgumentNullException>(originatingRequest != null);
			Contract.Requires<ArgumentNullException>(version != null);

			this.protectionRequired = protectionRequired;
			this.transport = MessageTransport.Direct;
			this.originatingRequest = originatingRequest;
			this.Version = version;
		}

		/// <summary>
		/// Prepares an HTTP request that carries a given message.
		/// </summary>
		/// <param name="request">The message to send.</param>
		/// <returns>
		/// The <see cref="HttpWebRequest"/> prepared to send the request.
		/// </returns>
		/// <remarks>
		/// This method must be overridden by a derived class, unless the <see cref="Channel.RequestCore"/> method
		/// is overridden and does not require this method.
		/// </remarks>
		protected override HttpWebRequest CreateHttpRequest(IDirectedProtocolMessage request) {
			HttpWebRequest httpRequest;
			if ((request.HttpMethods & HttpDeliveryMethods.GetRequest) != 0) {
				httpRequest = InitializeRequestAsGet(request);
			} else if ((request.HttpMethods & HttpDeliveryMethods.PostRequest) != 0) {
				httpRequest = InitializeRequestAsPost(request);
			} else {
				throw new NotSupportedException();
			}

			return httpRequest;
		}

		/// <summary>
		/// Reads an access token to find out what data it authorizes access to.
		/// </summary>
		/// <param name="message">The message carrying the access token.</param>
		/// <param name="accessToken">The access token's serialized representation.</param>
		/// <returns>The deserialized, validated token.</returns>
		/// <exception cref="ProtocolException">Thrown if the access token is expired, invalid, or from an untrusted authorization server.</exception>
		public virtual AccessToken DeserializeAccessToken(IDirectedProtocolMessage message, string accessToken) {
			ErrorUtilities.VerifyProtocol(!string.IsNullOrEmpty(accessToken), ResourceServerStrings.MissingAccessToken);
			var accessTokenFormatter = AccessToken.CreateFormatter(this.AuthorizationServerPublicSigningKey, this.ResourceServerPrivateEncryptionKey);
			var token = new AccessToken();
			try {
				accessTokenFormatter.Deserialize(token, accessToken, message, Protocol.access_token);
			} catch (IOException ex) {
				throw new ProtocolException(ResourceServerStrings.InvalidAccessToken, ex);
			}

			return token;
		}

		/// <summary>
		/// Analyzes an incoming request message payload to discover what kind of
		/// message is embedded in it and returns the type, or null if no match is found.
		/// </summary>
		/// <param name="request">The message that was sent as a request that resulted in the response.</param>
		/// <param name="fields">The name/value pairs that make up the message payload.</param>
		/// <returns>
		/// A newly instantiated <see cref="IProtocolMessage"/>-derived object that this message can
		/// deserialize to.  Null if the request isn't recognized as a valid protocol message.
		/// </returns>
		public IDirectResponseProtocolMessage GetNewResponseMessage(IDirectedProtocolMessage request, IDictionary<string, string> fields) {
			DirectResponseBase message = null;

			// Discern the OpenID version of the message.
			Protocol protocol = Protocol.V11;
			string ns;
			if (fields.TryGetValue(Protocol.V20.openidnp.ns, out ns)) {
				ErrorUtilities.VerifyProtocol(string.Equals(ns, Protocol.OpenId2Namespace, StringComparison.Ordinal), MessagingStrings.UnexpectedMessagePartValue, Protocol.V20.openidnp.ns, ns);
				protocol = Protocol.V20;
			}

			// Handle error messages generally.
			if (fields.ContainsKey(protocol.openidnp.error)) {
				message = new DirectErrorResponse(protocol.Version, request);
			}

			var associateRequest = request as AssociateRequest;
			if (associateRequest != null) {
				if (protocol.Version.Major >= 2 && fields.ContainsKey(protocol.openidnp.error_code)) {
					// This is a special recognized error case that we create a special message for.
					message = new AssociateUnsuccessfulResponse(protocol.Version, associateRequest);
				} else if (message == null) {
					if (OpenIdUtilities.IsDiffieHellmanPresent) {
						var associateDiffieHellmanRequest = request as AssociateDiffieHellmanRequest;
						if (associateDiffieHellmanRequest != null) {
							message = new AssociateDiffieHellmanRelyingPartyResponse(protocol.Version, associateDiffieHellmanRequest);
						}
					}

					var associateUnencryptedRequest = request as AssociateUnencryptedRequest;
					if (associateUnencryptedRequest != null) {
						message = new AssociateUnencryptedResponseRelyingParty(protocol.Version, associateUnencryptedRequest);
					}
				}
			}

			var checkAuthenticationRequest = request as CheckAuthenticationRequest;
			if (checkAuthenticationRequest != null && message == null) {
				message = new CheckAuthenticationResponse(protocol.Version, checkAuthenticationRequest);
			}

			if (message != null) {
				message.SetAsIncoming();
			}

			return message;
		}

		/// <summary>
		/// Analyzes an incoming request message payload to discover what kind of
		/// message is embedded in it and returns the type, or null if no match is found.
		/// </summary>
		/// <param name="request">The message that was sent as a request that resulted in the response.</param>
		/// <param name="fields">The name/value pairs that make up the message payload.</param>
		/// <returns>
		/// A newly instantiated <see cref="IProtocolMessage"/>-derived object that this message can
		/// deserialize to.  Null if the request isn't recognized as a valid protocol message.
		/// </returns>
		IDirectResponseProtocolMessage IMessageFactory.GetNewResponseMessage(IDirectedProtocolMessage request, IDictionary<string, string> fields) {
			Requires.NotNull(request, "request");
			Requires.NotNull(fields, "fields");
			throw new NotImplementedException();
		}

		protected override HttpWebRequest CreateHttpRequest(IDirectedProtocolMessage request) {
			throw new NotImplementedException("CreateHttpRequest");
		}

		/// <summary>
		/// Scans the incoming request for an authorization response message.
		/// </summary>
		/// <param name="authorizationState">The authorization.</param>
		/// <param name="response">The incoming authorization response message.</param>
		/// <returns>
		/// The granted authorization, or <c>null</c> if the incoming HTTP request did not contain an authorization server response or authorization was rejected.
		/// </returns>
		internal IAuthorizationState ProcessUserAuthorization(IAuthorizationState authorizationState, IDirectedProtocolMessage response) {
			Requires.NotNull(authorizationState, "authorizationState");
			Requires.NotNull(response, "response");

			EndUserAuthorizationSuccessAccessTokenResponse accessTokenSuccess;
			EndUserAuthorizationSuccessAuthCodeResponse authCodeSuccess;
			if ((accessTokenSuccess = response as EndUserAuthorizationSuccessAccessTokenResponse) != null) {
				UpdateAuthorizationWithResponse(authorizationState, accessTokenSuccess);
			} else if ((authCodeSuccess = response as EndUserAuthorizationSuccessAuthCodeResponse) != null) {
				this.UpdateAuthorizationWithResponse(authorizationState, authCodeSuccess);
			} else if (response is EndUserAuthorizationFailedResponse) {
				authorizationState.Delete();
				return null;
			}

			return authorizationState;
		}

		/// <summary>
		/// Prepares an HTTP request that carries a given message.
		/// </summary>
		/// <param name="request">The message to send.</param>
		/// <returns>
		/// The <see cref="HttpRequest"/> prepared to send the request.
		/// </returns>
		protected override HttpWebRequest CreateHttpRequest(IDirectedProtocolMessage request) {
			HttpWebRequest httpRequest;

			HttpDeliveryMethods transmissionMethod = request.HttpMethods;
			if ((transmissionMethod & HttpDeliveryMethods.AuthorizationHeaderRequest) != 0) {
				httpRequest = this.InitializeRequestAsAuthHeader(request);
			} else if ((transmissionMethod & HttpDeliveryMethods.PostRequest) != 0) {
				var requestMessageWithBinaryData = request as IMessageWithBinaryData;
				ErrorUtilities.VerifyProtocol(requestMessageWithBinaryData == null || !requestMessageWithBinaryData.SendAsMultipart, OAuthStrings.MultipartPostMustBeUsedWithAuthHeader);
				httpRequest = this.InitializeRequestAsPost(request);
			} else if ((transmissionMethod & HttpDeliveryMethods.GetRequest) != 0) {
				httpRequest = InitializeRequestAsGet(request);
			} else if ((transmissionMethod & HttpDeliveryMethods.HeadRequest) != 0) {
				httpRequest = InitializeRequestAsHead(request);
			} else if ((transmissionMethod & HttpDeliveryMethods.PutRequest) != 0) {
				httpRequest = this.InitializeRequestAsPut(request);
			} else if ((transmissionMethod & HttpDeliveryMethods.DeleteRequest) != 0) {
				httpRequest = InitializeRequestAsDelete(request);
			} else {
				throw new NotSupportedException();
			}
			return httpRequest;
		}

		/// <summary>
		/// Prepares the return value for the GetRequest method in the event of an exception.
		/// </summary>
		/// <param name="ex">The exception that forms the basis of the error response.  Must not be null.</param>
		/// <param name="httpRequestInfo">The incoming HTTP request.  Must not be null.</param>
		/// <param name="incomingMessage">The incoming message.  May be null in the case that it was malformed.</param>
		/// <returns>
		/// Either the <see cref="IRequest"/> to return to the host site or null to indicate no response could be reasonably created and that the caller should rethrow the exception.
		/// </returns>
		private IRequest GetErrorResponse(ProtocolException ex, HttpRequestInfo httpRequestInfo, IDirectedProtocolMessage incomingMessage) {
			Contract.Requires<ArgumentNullException>(ex != null);
			Contract.Requires<ArgumentNullException>(httpRequestInfo != null);

			Logger.OpenId.Error("An exception was generated while processing an incoming OpenID request.", ex);
			IErrorMessage errorMessage;

			// We must create the appropriate error message type (direct vs. indirect)
			// based on what we see in the request.
			string returnTo = httpRequestInfo.QueryString[Protocol.Default.openid.return_to];
			if (returnTo != null) {
				// An indirect request message from the RP
				// We need to return an indirect response error message so the RP can consume it.
				// Consistent with OpenID 2.0 section 5.2.3.
				var indirectRequest = incomingMessage as SignedResponseRequest;
				if (indirectRequest != null) {
					errorMessage = new IndirectErrorResponse(indirectRequest);
				} else {
					errorMessage = new IndirectErrorResponse(Protocol.Default.Version, new Uri(returnTo));
				}
			} else if (httpRequestInfo.HttpMethod == "POST") {
				// A direct request message from the RP
				// We need to return a direct response error message so the RP can consume it.
				// Consistent with OpenID 2.0 section 5.1.2.2.
				errorMessage = new DirectErrorResponse(Protocol.Default.Version, incomingMessage);
			} else {
				// This may be an indirect request from an RP that was so badly
				// formed that we cannot even return an error to the RP.
				// The best we can do is display an error to the user.
				// Returning null cues the caller to "throw;"
				return null;
			}

			errorMessage.ErrorMessage = ex.ToStringDescriptive();

			// Allow host to log this error and issue a ticket #.
			// We tear off the field to a local var for thread safety.
			IErrorReporting hostErrorHandler = this.ErrorReporting;
			if (hostErrorHandler != null) {
				errorMessage.Contact = hostErrorHandler.Contact;
				errorMessage.Reference = hostErrorHandler.LogError(ex);
			}

			if (incomingMessage != null) {
				return new AutoResponsiveRequest(incomingMessage, errorMessage, this.SecuritySettings);
			} else {
				return new AutoResponsiveRequest(errorMessage, this.SecuritySettings);
			}
		}

		/// <summary>
		/// Initializes a new instance of the <see cref="DirectResponseBase"/> class.
		/// </summary>
		/// <param name="responseVersion">The OpenID version of the response message.</param>
		/// <param name="originatingRequest">The originating request.  May be null in case the request is unrecognizable and this is an error response.</param>
		protected DirectResponseBase(Version responseVersion, IDirectedProtocolMessage originatingRequest) {
			Requires.NotNull(responseVersion, "responseVersion");

			this.Version = responseVersion;
			this.originatingRequest = originatingRequest;
		}

		internal new void PrepareIndirectResponse(IDirectedProtocolMessage message) {
			base.PrepareIndirectResponse(message);
		}