This documentation is archived and is not being maintained.

MutexSecurity Class

Represents the Windows access control security for a named mutex. This class cannot be inherited.

Namespace:  System.Security.AccessControl
Assembly:  mscorlib (in mscorlib.dll)

'Declaration
Public NotInheritable Class MutexSecurity _
	Inherits NativeObjectSecurity
'Usage
Dim instance As MutexSecurity

A MutexSecurity object specifies access rights for a named system mutex, and also specifies how access attempts are audited. Access rights to the mutex are expressed as rules, with each access rule represented by a MutexAccessRule object. Each auditing rule is represented by a MutexAuditRule object.

This mirrors the underlying Windows security system, in which each securable object has at most one discretionary access control list (DACL) that controls access to the secured object, and at most one system access control list (SACL) that specifies which access attempts are audited. The DACL and SACL are ordered lists of access control entries (ACE) that specify access and auditing for users and groups. A MutexAccessRule or MutexAuditRule object might represent more than one ACE.

NoteNote:

A Mutex object can represent a local mutex or a named system mutex. Windows access control security is meaningful only for named system mutexes.

The MutexSecurity, MutexAccessRule, and MutexAuditRule classes hide the implementation details of ACLs and ACEs. They allow you to ignore the seventeen different ACE types and the complexity of correctly maintaining inheritance and propagation of access rights. These objects are also designed to prevent the following common access control errors:

  • Creating a security descriptor with a null DACL. A null reference to a DACL allows any user to add access rules to an object, potentially creating a denial-of-service attack. A new MutexSecurity object always starts with an empty DACL, which denies all access for all users.

  • Violating the canonical ordering of ACEs. If the ACE list in the DACL is not kept in the canonical order, users might inadvertently be given access to the secured object. For example, denied access rights must always appear before allowed access rights. MutexSecurity objects maintain the correct order internally.

  • Manipulating security descriptor flags, which should be under resource manager control only.

  • Creating invalid combinations of ACE flags.

  • Manipulating inherited ACEs. Inheritance and propagation are handled by the resource manager, in response to changes you make to access and audit rules.

  • Inserting meaningless ACEs into ACLs.

The only capabilities not supported by the .NET security objects are dangerous activities that should be avoided by the majority of application developers, such as the following:

  • Low-level tasks that are normally performed by the resource manager.

  • Adding or removing access control entries in ways that do not maintain the canonical ordering.

To modify Windows access control security for a named mutex, use the Mutex.GetAccessControl method to get the MutexSecurity object. Modify the security object by adding and removing rules, and then use the Mutex.SetAccessControl method to reattach it.

Important noteImportant Note:

Changes you make to a MutexSecurity object do not affect the access levels of the named mutex until you call the Mutex.SetAccessControl method to assign the altered security object to the named mutex.

To copy access control security from one mutex to another, use the Mutex.GetAccessControl method to get a MutexSecurity object representing the access and audit rules for the first mutex, and then use the Mutex.SetAccessControl method, or a constructor that accepts a MutexSecurity object, to assign those rules to the second mutex.

Users with an investment in the security descriptor definition language (SDDL) can use the SetSecurityDescriptorSddlForm method to set access rules for a named mutex, and the GetSecurityDescriptorSddlForm method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development.

NoteNote:

Security on synchronization objects is not supported for Windows 98 or Windows Millennium Edition.

The following code example demonstrates the separation between Allow rules and Deny rules, and shows the combination of rights in compatible rules. The example creates a MutexSecurity object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing Allow rule.

NoteNote:

This example does not attach the security object to a Mutex object. Examples that attach security objects can be found in Mutex.GetAccessControl and Mutex.SetAccessControl.

Imports System
Imports System.Threading
Imports System.Security.AccessControl
Imports System.Security.Principal

Public Class Example

    Public Shared Sub Main()

        ' Create a string representing the current user. 
        Dim user As String = Environment.UserDomainName _ 
            & "\" & Environment.UserName

        ' Create a security object that grants no access. 
        Dim mSec As New MutexSecurity()

        ' Add a rule that grants the current user the  
        ' right to enter or release the mutex. 
        Dim rule As New MutexAccessRule(user, _
            MutexRights.Synchronize _
            Or MutexRights.Modify, _
            AccessControlType.Allow)
        mSec.AddAccessRule(rule)

        ' Add a rule that denies the current user the  
        ' right to change permissions on the mutex.
        rule = New MutexAccessRule(user, _
            MutexRights.ChangePermissions, _
            AccessControlType.Deny)
        mSec.AddAccessRule(rule)

        ' Display the rules in the security object.
        ShowSecurity(mSec)

        ' Add a rule that allows the current user the  
        ' right to read permissions on the mutex. This rule 
        ' is merged with the existing Allow rule.
        rule = New MutexAccessRule(user, _
            MutexRights.ReadPermissions, _
            AccessControlType.Allow)
        mSec.AddAccessRule(rule)

        ShowSecurity(mSec)

    End Sub  

    Private Shared Sub ShowSecurity(ByVal security As MutexSecurity)
        Console.WriteLine(vbCrLf & "Current access rules:" & vbCrLf)

        For Each ar As MutexAccessRule In _
            security.GetAccessRules(True, True, GetType(NTAccount))

            Console.WriteLine("        User: {0}", ar.IdentityReference)
            Console.WriteLine("        Type: {0}", ar.AccessControlType)
            Console.WriteLine("      Rights: {0}", ar.MutexRights)
            Console.WriteLine()
        Next 

    End Sub 
End Class  

'This code example produces output similar to following: 

'Current access rules: 

'        User: TestDomain\TestUser 
'        Type: Deny 
'      Rights: ChangePermissions 

'        User: TestDomain\TestUser 
'        Type: Allow 
'      Rights: Modify, Synchronize 


'Current access rules: 

'        User: TestDomain\TestUser 
'        Type: Deny 
'      Rights: ChangePermissions 

'        User: TestDomain\TestUser 
'        Type: Allow 
'      Rights: Modify, ReadPermissions, Synchronize

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0
Show: