////////////////////////////////////////////////////////////////////////////////
//
//  Microsoft Research Singularity
//
//  Copyright (c) Microsoft Corporation.  All rights reserved.
//
//  File:   Contracts/CredentialsManager.Contracts/GssSupplicantContract.sg
//
//  Note:	Defines a contract for use with authentication protocols that 
//			use the GSSAPI model for exchanging tokens between clients and
//			servers.
//

using System;
using Microsoft.Contracts;
using Microsoft.Singularity;
using Microsoft.Singularity.Channels;
using Microsoft.Singularity.Directory;
using Microsoft.SingSharp;

namespace Microsoft.Singularity.Security
{
	/**
	<summary>
		<para>
			This contract represents an active authentication session.  It is modeled after
			the GSS API, which is a standard API for performing authentication exchanges.
			(See RFC 2078.)  However, this contract models only the behavior of a supplicant
			(a client who wishes to prove its identity), not that of an authenticator.
		</para>

		<para>
			This contract is analogous to an SSPI session in Win32.  See InitializeSecurityContext
			and friends.
		</para>
		
		<para>
			In general, applications hold the import endpoint of this contract, while
			implementations of authentication protocols, implemented in the Credentials
			Manager Service, hold the export side.  The channel is bound using the
			CreateSupplicant or CreateSupplicantForProtocol requests of the
			CredentialsManagerContract.  Applications ferry opaque authentication tokens
			between the local supplicant and the remote network service until both sides
			decide that authentication has succeeded, or one side decides that authentication
			has failed.  Applications should not interpret or modify the contents of the tokens.
		</para>
		
		<para>
			Authentication protocols vary in the number of messages sent, in which side sends
			the first message, and in which side sends the last message.  This contract supports
			all message patterns.  The supplicant sends the first message to the client application,
			and that first message indicates whether the supplicant sends the first token,
			(supplicant sends FirstToken to application), or expects the network service to send
			the first token (supplicant sends NeedFirstToken).
		</para>
		
		<para>
			Currently, the only implementor of this contract is the NTLM authentication
			protocol.  However, it is intended that SPNEGO, Kerberos, etc. will eventually
			implement this contract as well.
		</para>
		
		<para>
			This contract should be expanded to allow applications to negotiate standard
			GSS options, such as integrity / confidentiality services, etc.  For now,
			it models only authentication (identification).
		</para>
	</summary>
	*/
	public contract GssSupplicantContract : ServiceContract
	{
		/// <summary>
		/// If the supplicant sends this as the first message out of the Start state,
		/// then the supplicant expects the remote network service to be the first to
		/// send an authentication token.
		/// </summary>
		out message NeedFirstToken();
		out message FirstToken(byte[]! in ExHeap token);
		
		override state Start : one
		{
			NeedFirstToken! -> WaitingForToken;
			FirstToken! -> WaitingForToken;
		}

		state WaitingForToken : one
		{
			AcceptToken? -> ProcessingToken;
		}

		// The application sends this message to the supplicant when it has received
		// an authentication token from the remote network service.  The supplicant
		// will process the token, and will either decide that authentication has
		// succeeded, or failed, or that another token must be sent to the network
		// service (ContinueNeeded).
		in message AcceptToken(byte[]! in ExHeap token);
		
		// The supplicant sends this message in response to AcceptToken when the
		// supplicant needs to send a message to the remote network service.
		// The application should send the message, using whatever network transport
		// is appropriate.  Then the application should receive the next authentication
		// token from the network service, and should forward the token to this
		// supplicant.
		out message ContinueNeeded(byte[]! in ExHeap token);
		
		// The supplicant sends this message in response to AcceptToken when the
		// supplicant has processed the last message in the authentication exchange,
		// and has decided that authentication has succeeded, and has a token it
		// needs to transmit to the remote network service.  The application should
		// transmit the token to the remote network service, and should consider
		// authentication to be complete.
		out message CompleteWithToken(byte[]! in ExHeap token);
		
		// The supplicant sends this message in response to AcceptToken when the
		// supplicant has processed the last message in the authentication exchange,
		// and has decided that authentication has succeeded, and there is no need
		// to send another token to the remote network service.  The application
		// should consider authentication to be complete.
		out message Complete();
		
		// The supplicant sends this message in response to AcceptToken when the
		// supplicant has decided that authentication has failed.
		out message AuthenticationFailed(GssErrorCode error);
		
		state ProcessingToken : one
		{
			AuthenticationFailed! -> Failed;
			ContinueNeeded! -> WaitingForToken;
			Complete! -> Succeeded;
			CompleteWithToken! -> Succeeded;
		}
		
		state Succeeded : one
		{
		}
		
		state Failed : one
		{
		}
		
	}
	
	public enum GssErrorCode
	{
		None = 0,
		
		/// <summary>The server refused the request, for some unspecified reason.</summary>
		ServerRefusedAuthentication,

		InternalError,
		
		// Add more error codes here, as appropriate, once GSS support is fleshed out more.
	}
}