Sam.cs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System.Collections.Generic;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Security.AccessControl;
using System.Security.Principal;

using Microsoft.PowerShell.Commands;
using System.Management.Automation.SecurityAccountsManager.Extensions;
using System.Management.Automation.SecurityAccountsManager.Native;
using System.Management.Automation.SecurityAccountsManager.Native.NtSam;
using System.Text;

using Microsoft.PowerShell.LocalAccounts;
using System.Diagnostics.CodeAnalysis;

[module: SuppressMessage("Microsoft.Design", "CA1014:MarkAssembliesWithClsCompliant")]

namespace System.Management.Automation.SecurityAccountsManager
{
    /// <summary>
    /// Defines enumeration constants for enabling and disabling something.
    /// </summary>
    internal enum Enabling
    {
        Disable = 0,
        Enable
    }

    /// <summary>
    /// Managed version of the SAM_RID_ENUMERATION native structure,
    /// to be returned from the EnumerateLocalUsers method of Sam.
    /// Contains the original structure's members along with additional
    /// members of use.
    /// </summary>
    internal class SamRidEnumeration
    {
#region Original struct members
        public string Name;
        public UInt32 RelativeId;
#endregion Original struct members

#region Additional members
        public IntPtr domainHandle;     // The domain handle used to acquire the data.
#endregion Additional members
    }

    /// <summary>
    /// Provides methods for manipulating local Users and Groups.
    /// </summary>
    internal class Sam : IDisposable
    {
#region Enums
        [Flags]
        private enum GroupProperties
        {
            Name        = 0x0001,   // NOT changeable through Set-LocalGroup
            Description = 0x0002,

            AllSetable  = Description,
            AllReadable = AllSetable | Name
        }

        /// <summary>
        /// Defines a set of flags, each corresponding to a member of LocalUser,
        /// which indicate fields to be updated.
        /// </summary>
        /// <remarks>
        /// Although password can be set through Create-LocalUser and Set-LocalUser,
        /// it is not a member of LocalUser so does not appear in this enumeration.
        /// </remarks>
        [Flags]
        private enum UserProperties
        {
            None                    = 0x0000,   // not actually a LocalUser member
            Name                    = 0x0001,   // NOT changeable through Set-LocalUser
            AccountExpires          = 0x0002,
            Description             = 0x0004,
            Enabled                 = 0x0008,   // NOT changeable through Set-LocalUser
            FullName                = 0x0010,
            PasswordChangeableDate  = 0x0020,
            PasswordExpires         = 0x0040,
            PasswordNeverExpires    = 0x0080,
            UserMayChangePassword   = 0x0100,
            PasswordRequired        = 0x0200,
            PasswordLastSet         = 0x0400,   // CANNOT be set by cmdlet
            LastLogon               = 0x0800,   // CANNOT be set by cmdlet

            // All properties that can be set through Set-LocalUser
            AllSetable              = AccountExpires
                                        | Description
                                        | FullName
                                        | PasswordChangeableDate
                                        | PasswordExpires
                                        | PasswordNeverExpires
                                        | UserMayChangePassword
                                        | PasswordRequired,

            // Properties that can be set by Create-LocalUser
            AllCreateable           = AllSetable | Name | Enabled,

            // Properties that can be read by e.g., Get-LocalUser
            AllReadable             = AllCreateable | PasswordLastSet | LastLogon
        }

        private enum PasswordExpiredState
        {
            Unchanged = -1,
            NotExpired = 0,
            Expired = 1
        }

        [Flags]
        internal enum ObjectAccess : uint
        {
            AliasRead   = Win32.STANDARD_RIGHTS_READ
                            | ALIAS_LIST_MEMBERS,
            ALiasWrite  = Win32.STANDARD_RIGHTS_WRITE
                            | ALIAS_WRITE_ACCOUNT
                            | ALIAS_ADD_MEMBER
                            | ALIAS_REMOVE_MEMBER,

            UserAllAccess   = Win32.STANDARD_RIGHTS_REQUIRED
                                | USER_READ_PREFERENCES
                                | USER_READ_LOGON
                                | USER_LIST_GROUPS
                                | USER_READ_GROUP_INFORMATION
                                | USER_WRITE_PREFERENCES
                                | USER_CHANGE_PASSWORD
                                | USER_FORCE_PASSWORD_CHANGE
                                | USER_READ_GENERAL
                                | USER_READ_ACCOUNT
                                | USER_WRITE_ACCOUNT
                                | USER_WRITE_GROUP_INFORMATION,
            UserRead        = Win32.STANDARD_RIGHTS_READ
                                | USER_READ_GENERAL             // not in original USER_READ
                                | USER_READ_PREFERENCES
                                | USER_READ_LOGON
                                | USER_READ_ACCOUNT
                                | USER_LIST_GROUPS
                                | USER_READ_GROUP_INFORMATION,
            UserWrite       = Win32.STANDARD_RIGHTS_WRITE
                                | USER_WRITE_PREFERENCES
                                | USER_CHANGE_PASSWORD
        }

        [Flags]
        internal enum DomainAccess : uint
        {
            AllAccess   = Win32.STANDARD_RIGHTS_REQUIRED
                            | DOMAIN_READ_OTHER_PARAMETERS
                            | DOMAIN_WRITE_OTHER_PARAMETERS
                            | DOMAIN_WRITE_PASSWORD_PARAMS
                            | DOMAIN_CREATE_USER
                            | DOMAIN_CREATE_GROUP
                            | DOMAIN_CREATE_ALIAS
                            | DOMAIN_GET_ALIAS_MEMBERSHIP
                            | DOMAIN_LIST_ACCOUNTS
                            | DOMAIN_READ_PASSWORD_PARAMETERS
                            | DOMAIN_LOOKUP
                            | DOMAIN_ADMINISTER_SERVER,

            Read        = Win32.STANDARD_RIGHTS_READ
                            | DOMAIN_LIST_ACCOUNTS
                            | DOMAIN_GET_ALIAS_MEMBERSHIP
                            | DOMAIN_READ_OTHER_PARAMETERS,

            Write       = Win32.STANDARD_RIGHTS_WRITE
                            | DOMAIN_WRITE_OTHER_PARAMETERS
                            | DOMAIN_WRITE_PASSWORD_PARAMS
                            | DOMAIN_CREATE_USER
                            | DOMAIN_CREATE_GROUP
                            | DOMAIN_CREATE_ALIAS
                            | DOMAIN_ADMINISTER_SERVER,

            Max         = Win32.MAXIMUM_ALLOWED
        }

        /// <summary>
        /// The operation under way. Used in the <see cref="Context"/> class.
        /// </summary>
        private enum ContextOperation
        {
            New = 1,
            Enable,
            Disable,
            Get,
            Remove,
            Rename,
            Set,
            AddMember,
            GetMember,
            RemoveMember
        }

        /// <summary>
        /// The type of object currently operating with.
        /// used in the <see cref="Context"/> class.
        /// </summary>
        private enum ContextObjectType
        {
            User = 1,
            Group
        }
#endregion Enums

#region Internal Classes
        /// <summary>
        /// Holds information about the underway operation.
        /// </summary>
        /// <remarks>
        /// Used primarily by the private ThrowOnFailure method when building
        /// Exception objects to throw.
        /// </remarks>
        private sealed class Context
        {
            public ContextOperation operation;
            public ContextObjectType type;
            public object target;
            public string objectId;
            public string memberId;

            /// <summary>
            /// Initialize a new Context object.
            /// </summary>
            /// <param name="operation">
            /// One of the <see cref="ContextOperation"/> enumerations indicating
            /// the type of operation under way.
            /// </param>
            /// <param name="objectType">
            /// One of the <see cref="ContextObjectType"/> enumerations indicating
            /// the type of object (user or group) being used.
            /// </param>
            /// <param name="objectIdentifier">
            /// A string containing the name of the object. This may be either a
            /// user/group name or a string representation of a SID.
            /// </param>
            /// <param name="target">
            /// The target being operated on.
            /// </param>
            /// <param name="memberIdentifier">
            /// A string containing the name of the member being added or removed
            /// from a group. Used only in such cases.
            /// </param>
            public Context(ContextOperation operation,
                           ContextObjectType objectType,
                           string objectIdentifier,
                           object target,
                           string memberIdentifier = null)
            {
                this.operation = operation;
                this.type = objectType;
                this.objectId = objectIdentifier;
                this.target = target;
                this.memberId = memberIdentifier;
            }

            /// <summary>
            /// Default constructor.
            /// </summary>
            public Context()
            {
            }
            /// <summary>
            /// Gets a string containing the type of operation under way.
            /// </summary>
            [SuppressMessage("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")]
            public string OperationName
            {
                get { return operation.ToString(); }
            }

            /// <summary>
            /// Gets a string containing the type of object ("User" or "Group")
            /// being used.
            /// </summary>
            [SuppressMessage("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")]
            public string TypeNamne
            {
                get { return type.ToString(); }
            }

            /// <summary>
            /// Gets a string containing the name of the object being used.
            /// </summary>
            public string ObjectName
            {
                get { return objectId; }
            }

            /// <summary>
            /// Gets a string containing the name of the member being added to
            /// or removed from a group. Returns null if the operation does not
            /// involve group members.
            /// </summary>
            public string MemberName
            {
                get { return memberId; }
            }
        }

        /// <summary>
        /// Contains basic information about an Account.
        /// </summary>
        /// <remarks>
        /// AccountInfo is the return type from the private
        /// LookupAccountInfo method.
        /// </remarks>
        private sealed class AccountInfo
        {
            public string AccountName;
            public string DomainName;
            public SecurityIdentifier Sid;
            public Native.SID_NAME_USE Use;

            public override string ToString()
            {
                if (!string.IsNullOrEmpty(DomainName))
                    return DomainName + '\\' + AccountName;
                else
                    return AccountName;
            }
        }
#endregion Internal Classes

#region Constants
        //
        // Access rights
        //
        private const UInt32 ALIAS_ADD_MEMBER       = 0x0001;
        private const UInt32 ALIAS_REMOVE_MEMBER    = 0x0002;
        private const UInt32 ALIAS_LIST_MEMBERS     = 0x0004;
        private const UInt32 ALIAS_READ_INFORMATION = 0x0008;
        private const UInt32 ALIAS_WRITE_ACCOUNT    = 0x0010;

        private const UInt32 USER_READ_GENERAL              = 0x0001;
        private const UInt32 USER_READ_PREFERENCES          = 0x0002;
        private const UInt32 USER_WRITE_PREFERENCES         = 0x0004;
        private const UInt32 USER_READ_LOGON                = 0x0008;
        private const UInt32 USER_READ_ACCOUNT              = 0x0010;
        private const UInt32 USER_WRITE_ACCOUNT             = 0x0020;
        private const UInt32 USER_CHANGE_PASSWORD           = 0x0040;
        private const UInt32 USER_FORCE_PASSWORD_CHANGE     = 0x0080;
        private const UInt32 USER_LIST_GROUPS               = 0x0100;
        private const UInt32 USER_READ_GROUP_INFORMATION    = 0x0200;
        private const UInt32 USER_WRITE_GROUP_INFORMATION   = 0x0400;

        private const UInt32 DOMAIN_READ_PASSWORD_PARAMETERS = 0x0001;
        private const UInt32 DOMAIN_WRITE_PASSWORD_PARAMS    = 0x0002;
        private const UInt32 DOMAIN_READ_OTHER_PARAMETERS    = 0x0004;
        private const UInt32 DOMAIN_WRITE_OTHER_PARAMETERS   = 0x0008;
        private const UInt32 DOMAIN_CREATE_USER              = 0x0010;
        private const UInt32 DOMAIN_CREATE_GROUP             = 0x0020;
        private const UInt32 DOMAIN_CREATE_ALIAS             = 0x0040;
        private const UInt32 DOMAIN_GET_ALIAS_MEMBERSHIP     = 0x0080;
        private const UInt32 DOMAIN_LIST_ACCOUNTS            = 0x0100;
        private const UInt32 DOMAIN_LOOKUP                   = 0x0200;
        private const UInt32 DOMAIN_ADMINISTER_SERVER        = 0x0400;
#endregion Constants

#region Static Data
        private static SecurityIdentifier worldSid = new SecurityIdentifier(WellKnownSidType.WorldSid, null);
#endregion Static Data

#region Instance Data
        private IntPtr samHandle = IntPtr.Zero;
        private IntPtr localDomainHandle = IntPtr.Zero;
        private IntPtr builtinDomainHandle = IntPtr.Zero;
        private Context context = null;
        private string machineName = string.Empty;
#endregion Instance Data

#region Construction
        internal Sam()
        {
            OpenHandles();

            // CoreCLR does not have Environment.MachineName,
            // so we'll use this instead.
            machineName = System.Net.Dns.GetHostName();
        }
#endregion Construction

#region Public (Internal) Methods
        public string StripMachineName(string name)
        {
            var mn = machineName + '\\';

            if (name.StartsWith(mn, StringComparison.CurrentCultureIgnoreCase))
                return name.Substring(mn.Length);

            return name;
        }
#region Local Groups
        /// <summary>
        /// Retrieve a named local group.
        /// </summary>
        /// <param name="groupName">Name of the desired local group.</param>
        /// <returns>
        /// A <see cref="LocalGroup"/> object containing information about
        /// the local group.
        /// </returns>
        /// <exception cref="GroupNotFoundException">
        /// Thrown when the named group cannot be found.
        /// </exception>
        internal LocalGroup GetLocalGroup(string groupName)
        {
            context = new Context(ContextOperation.Get, ContextObjectType.Group, groupName, groupName);

            foreach (var sre in EnumerateGroups())
                if (sre.Name.Equals(groupName, StringComparison.CurrentCultureIgnoreCase))
                    return MakeLocalGroupObject(sre);   // return a populated group

            throw new GroupNotFoundException(groupName, context.target);
        }

        /// <summary>
        /// Retrieve a local group by SID.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> object identifying the desired group.
        /// </param>
        /// <returns>
        /// A <see cref="LocalGroup"/> object containing information about
        /// the local group.
        /// </returns>
        /// <exception cref="GroupNotFoundException">
        /// Thrown when the specified group cannot be found.
        /// </exception>
        internal LocalGroup GetLocalGroup(SecurityIdentifier sid)
        {
            context = new Context(ContextOperation.Get, ContextObjectType.Group, sid.ToString(), sid);

            foreach (var sre in EnumerateGroups())
                if (RidToSid(sre.domainHandle, sre.RelativeId) == sid)
                    return MakeLocalGroupObject(sre);   // return a populated group

            throw new GroupNotFoundException(sid.ToString(), context.target);
        }

        /// <summary>
        /// Create a local group.
        /// </summary>
        /// <param name="group">A <see cref="LocalGroup"/> object containing
        /// information about the local group to be created.
        /// </param>
        /// <returns>
        /// A new LocalGroup object containing information about the newly
        /// created local group.
        /// </returns>
        /// <exception cref="GroupExistsException">
        /// Thrown when an attempt is made to create a local group that already
        /// exists.
        /// </exception>
        internal LocalGroup CreateLocalGroup(LocalGroup group)
        {
            context = new Context(ContextOperation.New, ContextObjectType.Group, group.Name, group.Name);

            return CreateGroup(group, localDomainHandle);
        }

        /// <summary>
        /// Update a local group with new property values.
        /// </summary>
        /// <param name="group">
        /// A <see cref="LocalGroup"/> object representing the group to be updated.
        /// </param>
        /// <param name="changed">
        /// A LocalGroup object containing the desired changes.
        /// </param>
        /// <remarks>
        /// Currently, a group's description is the only changeable property.
        /// </remarks>
        internal void UpdateLocalGroup(LocalGroup group, LocalGroup changed)
        {
            context = new Context(ContextOperation.Set, ContextObjectType.Group, group.Name, group);

            UpdateGroup(group, changed);
        }

        /// <summary>
        /// Remove a local group.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> object identifying the
        /// local group to be removed.
        /// </param>
        /// <exception cref="GroupNotFoundException">
        /// Thrown when the specified group cannot be found.
        /// </exception>
        internal void RemoveLocalGroup(SecurityIdentifier sid)
        {
            context = new Context(ContextOperation.Remove, ContextObjectType.Group, sid.ToString(), sid);

            RemoveGroup(sid);
        }

        /// <summary>
        /// Remove a local group.
        /// </summary>
        /// <param name="group">
        /// A <see cref="LocalGroup"/> object containing
        /// information about the local group to be removed.
        /// </param>
        /// <exception cref="GroupNotFoundException">
        /// Thrown when the specified group cannot be found.
        /// </exception>
        internal void RemoveLocalGroup(LocalGroup group)
        {
            context = new Context(ContextOperation.Remove, ContextObjectType.Group, group.Name, group);

            if (group.SID == null)
                context.target = group = GetLocalGroup(group.Name);

            RemoveGroup(group.SID);
        }

        /// <summary>
        /// Rename a local group.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> object identifying
        /// the local group to be renamed.
        /// </param>
        /// <param name="newName">
        /// A string containing the new name for the local group.
        /// </param>
        /// <exception cref="GroupNotFoundException">
        /// Thrown when the specified group cannot be found.
        /// </exception>
        internal void RenameLocalGroup(SecurityIdentifier sid, string newName)
        {
            context = new Context(ContextOperation.Rename, ContextObjectType.Group, sid.ToString(), sid);

            RenameGroup(sid, newName);
        }

        /// <summary>
        /// Rename a local group.
        /// </summary>
        /// <param name="group">
        /// A <see cref="LocalGroup"/> object containing
        /// information about the local group to be renamed.
        /// </param>
        /// <param name="newName">
        /// A string containing the new name for the local group.
        /// </param>
        /// <exception cref="GroupNotFoundException">
        /// Thrown when the specified group cannot be found.
        /// </exception>
        internal void RenameLocalGroup(LocalGroup group, string newName)
        {
            context = new Context(ContextOperation.Rename, ContextObjectType.Group, group.Name, group);

            if (group.SID == null)
                context.target = group = GetLocalGroup(group.Name);

            RenameGroup(group.SID, newName);
        }

        /// <summary>
        /// Get all local groups whose names satisfy the specified predicate.
        /// </summary>
        /// <param name="pred">
        /// Predicate that determines whether a group satisfies the conditions.
        /// </param>
        /// <returns>
        /// An <see cref="IEnumerable{LocalGroup}"/> object containing LocalGroup
        /// objects that satisfy the predicate condition.
        /// </returns>
        internal IEnumerable<LocalGroup> GetMatchingLocalGroups(Predicate<string> pred)
        {
            context = new Context(ContextOperation.Get, ContextObjectType.Group, string.Empty, null);

            foreach (var sre in EnumerateGroups())
            {

                if (pred(sre.Name))
                {
                    context.target = sre.Name;
                    yield return MakeLocalGroupObject(sre);
                }
            }
        }

        /// <summary>
        /// Get all local groups.
        /// </summary>
        /// <returns>
        /// An <see cref="IEnumerable{LocalGroup}"/> object containing a
        /// LocalGroup object for each local group.
        /// </returns>
        internal IEnumerable<LocalGroup> GetAllLocalGroups()
        {
            context = new Context(ContextOperation.Get, ContextObjectType.Group, string.Empty, null);

            foreach (var sre in EnumerateGroups())
            {
                context.target = sre.Name;
                yield return MakeLocalGroupObject(sre);
            }
        }

        /// <summary>
        /// Add members to a local group.
        /// </summary>
        /// <param name="group">
        /// A <see cref="LocalGroup"/> object identifying the group to
        /// which to add members.
        /// </param>
        /// <param name="member">
        /// An object of type <see cref="LocalPrincipal"/> identifying
        /// the member to be added.
        /// </param>
        /// <returns>
        /// An Exception object indicating any errors encountered.
        /// </returns>
        /// <exception cref="GroupNotFoundException">
        /// Thrown if the group could not be found.
        /// </exception>
        internal Exception AddLocalGroupMember(LocalGroup group, LocalPrincipal member)
        {
            context = new Context(ContextOperation.AddMember, ContextObjectType.Group, group.Name, group);
            if (group.SID == null)
                context.target = group = GetLocalGroup(group.Name);

            return AddGroupMember(group.SID, member);
        }

        /// <summary>
        /// Add members to a local group.
        /// </summary>
        /// <param name="groupSid">
        /// A <see cref="SecurityIdentifier"/> object identifying the group to
        /// which to add members.
        /// </param>
        /// <param name="member">
        /// An object of type <see cref="LocalPrincipal"/> identifying
        /// the member to be added.
        /// </param>
        /// <returns>
        /// An Exception object indicating any errors encountered.
        /// </returns>
        /// <exception cref="GroupNotFoundException">
        /// Thrown if the group could not be found.
        /// </exception>
        internal Exception AddLocalGroupMember(SecurityIdentifier groupSid, LocalPrincipal member)
        {
            context = new Context(ContextOperation.AddMember, ContextObjectType.Group, groupSid.ToString(), groupSid);

            return AddGroupMember(groupSid, member);
        }

        /// <summary>
        /// Retrieve members of a Local group.
        /// </summary>
        /// <param name="group">
        /// A <see cref="LocalGroup"/> object identifying the group whose members
        /// are requested.
        /// </param>
        /// <returns>
        /// An IEnumerable of <see cref="LocalPrincipal"/> objects containing the group's
        /// members.
        /// </returns>
        internal IEnumerable<LocalPrincipal> GetLocalGroupMembers(LocalGroup group)
        {
            context = new Context(ContextOperation.GetMember, ContextObjectType.Group, group.Name, group);

            if (group.SID == null)
                context.target = group = GetLocalGroup(group.Name);

            return GetGroupMembers(group.SID);
        }

        /// <summary>
        /// Retrieve members of a Local group.
        /// </summary>
        /// <param name="groupSid">
        /// A <see cref="SecurityIdentifier"/> object identifying the group whose members
        /// are requested.
        /// </param>
        /// <returns>
        /// An IEnumerable of <see cref="LocalPrincipal"/> objects containing the group's
        /// members.
        /// </returns>
        internal IEnumerable<LocalPrincipal> GetLocalGroupMembers(SecurityIdentifier groupSid)
        {
            context = new Context(ContextOperation.GetMember, ContextObjectType.Group, groupSid.ToString(), groupSid);

            return GetGroupMembers(groupSid);
        }

        /// <summary>
        /// Remove members from a local group.
        /// </summary>
        /// <param name="group">
        /// A <see cref="LocalGroup"/> object identifying the group from
        /// which to remove members
        /// </param>
        /// <param name="member">
        /// An object of type <see cref="LocalPrincipal"/> identifying
        /// the member to be removed.
        /// </param>
        /// <returns>
        /// An Exception object indicating any errors encountered.
        /// </returns>
        /// <exception cref="GroupNotFoundException">
        /// Thrown if the group could not be found.
        /// </exception>
        internal Exception RemoveLocalGroupMember(LocalGroup group, LocalPrincipal member)
        {
            context = new Context(ContextOperation.RemoveMember, ContextObjectType.Group, group.Name, group);

            if (group.SID == null)
                context.target = group = GetLocalGroup(group.Name);

            return RemoveGroupMember(group.SID, member);
        }

        /// <summary>
        /// Remove members from a local group.
        /// </summary>
        /// <param name="groupSid">
        /// A <see cref="SecurityIdentifier"/> object identifying the group from
        /// which to remove members
        /// </param>
        /// <param name="member">
        /// An Object of type <see cref="LocalPrincipal"/> identifying
        /// the member to be removed.
        /// </param>
        /// <returns>
        /// An Exception object indicating any errors encountered.
        /// </returns>
        /// <exception cref="GroupNotFoundException">
        /// Thrown if the group could not be found.
        /// </exception>
        internal Exception RemoveLocalGroupMember(SecurityIdentifier groupSid, LocalPrincipal member)
        {
            context = new Context(ContextOperation.RemoveMember, ContextObjectType.Group, groupSid.ToString(), groupSid);

            return RemoveGroupMember(groupSid, member);
        }
#endregion Local Groups

#region Local Users
        /// <summary>
        /// Retrieve a named local user.
        /// </summary>
        /// <param name="userName">Name of the desired local user.</param>
        /// <returns>
        /// A <see cref="LocalUser"/> object containing information about
        /// the local user.
        /// </returns>
        /// <exception cref="UserNotFoundException">
        /// Thrown when the named user cannot be found.
        /// </exception>
        internal LocalUser GetLocalUser(string userName)
        {
            context = new Context(ContextOperation.Get, ContextObjectType.User, userName, userName);

            foreach (var sre in EnumerateUsers())
                if (sre.Name.Equals(userName, StringComparison.CurrentCultureIgnoreCase))
                    return MakeLocalUserObject(sre);

            throw new UserNotFoundException(userName, userName);
        }

        /// <summary>
        /// Retrieve a local user by SID.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> object identifying the desired user.
        /// </param>
        /// <returns>
        /// A <see cref="LocalUser"/> object containing information about
        /// the local user.
        /// </returns>
        /// <exception cref="UserNotFoundException">
        /// Thrown when the specified user cannot be found.
        /// </exception>
        internal LocalUser GetLocalUser(SecurityIdentifier sid)
        {
            context = new Context(ContextOperation.Get, ContextObjectType.User, sid.ToString(), sid);

            foreach (var sre in EnumerateUsers())
                if (RidToSid(sre.domainHandle, sre.RelativeId) == sid)
                    return MakeLocalUserObject(sre);    // return a populated user

            throw new UserNotFoundException(sid.ToString(), sid);
        }

        /// <summary>
        /// Create a local user.
        /// </summary>
        /// <param name="user">A <see cref="LocalUser"/> object containing
        /// information about the local user to be created.
        /// </param>
        /// <param name="password">A <see cref="System.Security.SecureString"/> containing
        /// the initial password to be set for the new local user. If this parameter is null,
        /// no password is set.
        /// </param>
        /// <param name="setPasswordNeverExpires">
        /// Indicates whether PasswordNeverExpires was specified
        /// </param>
        /// <returns>
        /// A new LocalGroup object containing information about the newly
        /// created local user.
        /// </returns>
        /// <exception cref="UserExistsException">
        /// Thrown when an attempt is made to create a local user that already
        /// exists.
        /// </exception>
        internal LocalUser CreateLocalUser(LocalUser user, System.Security.SecureString password, bool setPasswordNeverExpires)
        {
            context = new Context(ContextOperation.New, ContextObjectType.User, user.Name, user);

            return CreateUser(user, password, localDomainHandle, setPasswordNeverExpires);
        }

        /// <summary>
        /// Remove a local user.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> object identifying
        /// the local user to be removed.
        /// </param>
        /// <exception cref="UserNotFoundException">
        /// Thrown when the specified user cannot be found.
        /// </exception>
        internal void RemoveLocalUser(SecurityIdentifier sid)
        {
            context = new Context(ContextOperation.Remove, ContextObjectType.User, sid.ToString(), sid);

            RemoveUser(sid);
        }

        /// <summary>
        /// Remove a local user.
        /// </summary>
        /// <param name="user">
        /// A <see cref="LocalUser"/> object containing
        /// information about the local user to be removed.
        /// </param>
        /// <exception cref="UserNotFoundException">
        /// Thrown when the specified user cannot be found.
        /// </exception>
        internal void RemoveLocalUser(LocalUser user)
        {
            context = new Context(ContextOperation.Remove, ContextObjectType.User, user.Name, user);

            if (user.SID == null)
                context.target = user = GetLocalUser(user.Name);

            RemoveUser(user.SID);
        }

        /// <summary>
        /// Rename a local user.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> objects identifying
        /// the local user to be renamed.
        /// </param>
        /// <param name="newName">
        /// A string containing the new name for the local user.
        /// </param>
        /// <exception cref="UserNotFoundException">
        /// Thrown when the specified user cannot be found.
        /// </exception>
        internal void RenameLocalUser(SecurityIdentifier sid, string newName)
        {
            context = new Context(ContextOperation.Rename, ContextObjectType.User, sid.ToString(), sid);

            RenameUser(sid, newName);
        }

        /// <summary>
        /// Rename a local user.
        /// </summary>
        /// <param name="user">
        /// A <see cref="LocalUser"/> objects containing
        /// information about the local user to be renamed.
        /// </param>
        /// <param name="newName">
        /// A string containing the new name for the local user.
        /// </param>
        /// <exception cref="UserNotFoundException">
        /// Thrown when the specified user cannot be found.
        /// </exception>
        internal void RenameLocalUser(LocalUser user, string newName)
        {
            context = new Context(ContextOperation.Rename, ContextObjectType.User, user.Name, user);

            if (user.SID == null)
                context.target = user = GetLocalUser(user.Name);

            RenameUser(user.SID, newName);
        }

        /// <summary>
        /// Enable or disable a Local User.
        /// </summary>
        /// <param name="sid">
        /// A <see cref="SecurityIdentifier"/> object identifying the user to enable or disable.
        /// </param>
        /// <param name="enable">
        /// One of the <see cref="Enabling"/> enumeration values, indicating whether to
        /// enable or disable the user.
        /// </param>
        internal void EnableLocalUser(SecurityIdentifier sid, Enabling enable)
        {
            context = new Context(enable == Enabling.Enable ? ContextOperation.Enable
                                                            : ContextOperation.Disable,
                                  ContextObjectType.User, sid.ToString(),
                                  sid);

            EnableUser(sid, enable);
        }

        /// <summary>
        /// Enable or disable a Local User.
        /// </summary>
        /// <param name="user">
        /// A <see cref="LocalUser"/> object representing the user to enable or disable.
        /// </param>
        /// <param name="enable">
        /// One of the <see cref="Enabling"/> enumeration values, indicating whether to
        /// enable or disable the user.
        /// </param>
        internal void EnableLocalUser(LocalUser user, Enabling enable)
        {
            context = new Context(enable == Enabling.Enable ? ContextOperation.Enable
                                                            : ContextOperation.Disable,
                                  ContextObjectType.User, user.Name,
                                  user);

            if (user.SID == null)
                context.target = user = GetLocalUser(user.Name);

            EnableUser(user.SID, enable);
        }

        /// <summary>
        /// Update a local user with new properties.
        /// </summary>
        /// <param name="user">
        /// A <see cref="LocalUser"/> object representing the user to be updated.
        /// </param>
        /// <param name="changed">
        /// A LocalUser object containing the desired changes.
        /// </param>
        /// <param name="password">A <see cref="System.Security.SecureString"/>
        /// object containing the new password. A null value in this parameter
        /// indicates that the password is not to be changed.
        /// </param>
        /// <param name="setPasswordNeverExpires">
        /// Specifies whether the PasswordNeverExpires parameter was set.
        /// </param>
        /// <remarks>
        /// Call this overload when intending to leave the password-expired
        /// marker in its current state. To set the password and the
        /// password-expired state, call the overload with a boolean as the
        /// fourth parameter
        /// </remarks>
        internal void UpdateLocalUser(LocalUser user, LocalUser changed, System.Security.SecureString password, bool? setPasswordNeverExpires)
        {
            context = new Context(ContextOperation.Set, ContextObjectType.User, user.Name, user);

            UpdateUser(user, changed, password, PasswordExpiredState.Unchanged, setPasswordNeverExpires);
        }

        /// <summary>
        /// Get all local users whose names satisfy the specified predicate.
        /// </summary>
        /// <param name="pred">
        /// Predicate that determines whether a user satisfies the conditions.
        /// </param>
        /// <returns>
        /// An <see cref="IEnumerable{LocalUser}"/> object containing LocalUser
        /// objects that satisfy the predicate condition.
        /// </returns>
        internal IEnumerable<LocalUser> GetMatchingLocalUsers(Predicate<string> pred)
        {
            context = new Context(ContextOperation.Get, ContextObjectType.User, string.Empty, null);

            foreach (var sre in EnumerateUsers())
            {
                if (pred(sre.Name))
                {
                    context.target = sre.Name;
                    yield return MakeLocalUserObject(sre);
                }
            }
        }

        /// <summary>
        /// Get all local users.
        /// </summary>