singrdk/base/Contracts/CredentialsManager.Contracts/CredentialsManagerContract.sg

////////////////////////////////////////////////////////////////////////////////
//
//  Microsoft Research Singularity
//
//  Copyright (c) Microsoft Corporation.  All rights reserved.
//
//  File:
//
//  Note:
//

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

namespace Microsoft.Singularity.Security
{
    // This structure describes a "protocol context" or a "protocol tuple".
    // This captures (roughly) the parameters that are relevant to security
    // that a client application uses.
    //
    public rep struct ProtocolTuple : ITracked
    {
        // The protocol that is specific to the application in question.
        // For example, "smb" or "http" or "ftp".
        public char[]! in ExHeap ApplicationProtocol;

        // The address of the remote service or application, who will be
        // authenticating the client application.  In this context, "address"
        // can be any protocol-specific identifier of a remote peer.
        // This includes addresses such as DNS names, IPv4 and IPv6 addresses,
        // converted to text.
        // For example, "products.redmond.corp.microsoft.com" or "192.168.1.1"
        // or any other protocol-specific identifier of a remote principal.
        public char[]! in ExHeap ServiceAddress;

        // The security protocol that the client wishes to use.
        // For example, "ntlm" or "kerberos" or "spnego".
        public char[]! in ExHeap AuthenticationProtocol;

        // The name of the remote security realm.  For NTLM, this is a domain name,
        // e.g. "redmond".  For Kerberos, this is a domain name, e.g.
        // "redmond.corp.microsoft.com".
        public char[]! in ExHeap Realm;
    }

    public rep struct CredentialsId : ITracked
    {
        public char[]! in ExHeap CredentialsName;
        public char[]! in ExHeap Tag;
    }

    public rep struct ProtocolMapping : ITracked
    {
        public ProtocolTuple ProtocolTuple;
        public CredentialsId CredentialsId;
    }

    public contract CredentialsManagerContract : ServiceContract
    {
        public const string ServiceName = "CredentialsManager";
        public const string ChannelPath = "/service/credentials";

        public const string ProtocolFieldWildcard = "*";

        //
        // Adds the specified credentials to the credentials store.
        //
        // The tag value can be used to disambiguate different instances of the same credentials.
        // For example, the username ".\Administrator" might be used at three different machines,
        // each of which have different passwords.  If the tag value is null, it is treated as
        // an empty string.
        //
        in message AddCredentials(CredentialsId id, char[]! in ExHeap password, bool replace);

        //
        // Removes the specified credentials from the credentials store.  The username and tag
        // value must match exactly the values provided previously in a call to AddCredentials.
        // If the tag value is null, it is treated as an empty string.
        //
        in message DeleteCredentials(CredentialsId id);

        //
        // Deletes all credentials in the credentials store.
        //
        in message DeleteAllCredentials();

        //
        // Enumerates the list of all credentials in the credentials store.
        //
        in message EnumerateCredentials();
        out message CredentialsList(CredentialsId[]! in ExHeap list);

        //
        // Adds a new mapping of a protocol tuple to credentials.
        //
        // Some of the fields of the protocol mapping ID support wildcards.
        // To do so, the field should be set to "*".
        // This allows the protocol mapping to apply to all contexts that match.
        //
        in message AddProtocolMapping(ProtocolTuple tuple, CredentialsId credentials, bool replace);

        //
        // Deletes a specific protocol mapping.  The protocol mapping ID must match
        // exactly an entry previously added using the AddProtocolMapping request.
        // Wildcards (fields using "*") are not interpreted.
        //
        in message DeleteProtocolMapping(ProtocolTuple tuple);

        //
        // Deletes all protocol mappings.
        //
        in message DeleteAllProtocolMappings();

        //
        // Searches the set of all protocol mappings for an entry that best matches
        // a specific protocol mapping.
        //
        in message FindMatchingProtocolMapping(ProtocolTuple tuple, bool useWildcards);
        out message NoMatchingProtocolMapping();
        out message MatchingProtocolMapping(CredentialsId credentials);

        //
        // Queries the list of all protocol mappings.
        //
        in message EnumerateProtocolMappings();
        out message ProtocolMappings(ProtocolMapping[]! in ExHeap mappings);

        // This message requests that the credentials manager create an instance of a security
        // protocol (identified by name), using the endpoint provided by the import holder.
        // This allows the import holder to choose the channel contract, which allows a
        // single protocol implementation to support more than one channel contract.
        // In response to this request, the credentials manager creates an instance of the
        // protocol (if possible).
        in message CreateSupplicant(
            char[]! in ExHeap authenticationProtocol,
            CredentialsId credentials,
            ServiceContract.Exp:Start! exp);

        // This request is similar to CreateSupplicant, but it also performs a protocol
        // tuple look-up, since this is anticipated to be a common usage of the CM.
        in message CreateSupplicantForProtocol(
            ProtocolTuple protocol,
            ServiceContract.Exp:Start! exp);
        out message AckCreateSupplicantForProtocol(CredentialsId credentialsSelected);

        // Generic response messages.
        // These are used when there is no request-specific data to return.
        out message Ok();
        out message RequestFailed(CredError error);


        out message Success();

        override state Start : one
        {
            Success! -> Ready;
        }

        state Ready : one
        {
            AddCredentials? -> (Ok! or RequestFailed!) -> Ready;
            DeleteCredentials? -> (Ok! or RequestFailed!) -> Ready;
            DeleteAllCredentials? -> (Ok! or RequestFailed!) -> Ready;

            EnumerateCredentials? -> (CredentialsList! or RequestFailed!) -> Ready;
            EnumerateProtocolMappings? -> (ProtocolMappings! or RequestFailed!) -> Ready;

            FindMatchingProtocolMapping? -> (MatchingProtocolMapping! or RequestFailed!) -> Ready;

            AddProtocolMapping? -> (Ok! or RequestFailed!) -> Ready;
            DeleteProtocolMapping? -> (Ok! or RequestFailed!) -> Ready;
            DeleteAllProtocolMappings? -> (Ok! or RequestFailed!) -> Ready;

            CreateSupplicant? -> (Ok! or RequestFailed!) -> Ready;
            CreateSupplicantForProtocol? -> (AckCreateSupplicantForProtocol! or RequestFailed!) -> Ready;
        }
    }

    /// <summary>Strings that are appropriate for passing to CreateSupplicant.</summary>
    public sealed /* static */ class AuthenticationProtocolNames
    {
        public const string Ntlm = "ntlm";

        // not yet implemented
        public const string Kerberos = "kerberos";

        // not yet implemented
        public const string HttpMD5 = "http-md5";
    }


    /// <summary>Error codes for the requests of the CredentialsManagerContract.</summary>
    public enum CredError
    {
        NoError = 0,
        InternalError,
        NoMatchingCredentials,
        NoMatchingAuthenticationProtocol,
        NoEntryFound,
        ContractNotSupported,
        MatchingEntryExists,
        InvalidArguments,
        EvidenceTypeNotSupported,
    }
}