Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

SemaphoreSecurity Class

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

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

[ComVisibleAttribute(false)]
public sealed class SemaphoreSecurity : NativeObjectSecurity

The SemaphoreSecurity type exposes the following members.

  NameDescription
Public methodSemaphoreSecurity()Initializes a new instance of the SemaphoreSecurity class with default values.
Public methodSemaphoreSecurity(String, AccessControlSections)Initializes a new instance of the SemaphoreSecurity class with the specified sections of the access control security rules from the system semaphore with the specified name.
Top

  NameDescription
Public propertyAccessRightTypeGets the enumeration that the SemaphoreSecurity class uses to represent access rights. (Overrides ObjectSecurity.AccessRightType.)
Protected propertyAccessRulesModifiedGets or sets a Boolean value that specifies whether the access rules associated with this ObjectSecurity object have been modified. (Inherited from ObjectSecurity.)
Public propertyAccessRuleTypeGets the type that the SemaphoreSecurity class uses to represent access rules. (Overrides ObjectSecurity.AccessRuleType.)
Public propertyAreAccessRulesCanonicalGets a Boolean value that specifies whether the access rules associated with this ObjectSecurity object are in canonical order. (Inherited from ObjectSecurity.)
Public propertyAreAccessRulesProtectedGets a Boolean value that specifies whether the Discretionary Access Control List (DACL) associated with this ObjectSecurity object is protected. (Inherited from ObjectSecurity.)
Public propertyAreAuditRulesCanonicalGets a Boolean value that specifies whether the audit rules associated with this ObjectSecurity object are in canonical order. (Inherited from ObjectSecurity.)
Public propertyAreAuditRulesProtectedGets a Boolean value that specifies whether the System Access Control List (SACL) associated with this ObjectSecurity object is protected. (Inherited from ObjectSecurity.)
Protected propertyAuditRulesModifiedGets or sets a Boolean value that specifies whether the audit rules associated with this ObjectSecurity object have been modified. (Inherited from ObjectSecurity.)
Public propertyAuditRuleTypeGets the type that the SemaphoreSecurity class uses to represent audit rules. (Overrides ObjectSecurity.AuditRuleType.)
Protected propertyGroupModifiedGets or sets a Boolean value that specifies whether the group associated with the securable object has been modified. (Inherited from ObjectSecurity.)
Protected propertyIsContainerGets a Boolean value that specifies whether this ObjectSecurity object is a container object. (Inherited from ObjectSecurity.)
Protected propertyIsDSGets a Boolean value that specifies whether this ObjectSecurity object is a directory object. (Inherited from ObjectSecurity.)
Protected propertyOwnerModifiedGets or sets a Boolean value that specifies whether the owner of the securable object has been modified. (Inherited from ObjectSecurity.)
Top

  NameDescription
Public methodAccessRuleFactoryCreates a new access control rule for the specified user, with the specified access rights, access control, and flags. (Overrides ObjectSecurity.AccessRuleFactory(IdentityReference, Int32, Boolean, InheritanceFlags, PropagationFlags, AccessControlType).)
Protected methodAddAccessRule(AccessRule)Adds the specified access rule to the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodAddAccessRule(SemaphoreAccessRule)Searches for a matching rule with which the new rule can be merged. If none are found, adds the new rule.
Protected methodAddAuditRule(AuditRule)Adds the specified audit rule to the System Access Control List (SACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodAddAuditRule(SemaphoreAuditRule)Searches for an audit rule with which the new rule can be merged. If none are found, adds the new rule.
Public methodAuditRuleFactoryCreates a new audit rule, specifying the user the rule applies to, the access rights to audit, and the outcome that triggers the audit rule. (Overrides ObjectSecurity.AuditRuleFactory(IdentityReference, Int32, Boolean, InheritanceFlags, PropagationFlags, AuditFlags).)
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetAccessRulesGets a collection of the access rules associated with the specified security identifier. (Inherited from CommonObjectSecurity.)
Public methodGetAuditRulesGets a collection of the audit rules associated with the specified security identifier. (Inherited from CommonObjectSecurity.)
Public methodGetGroupGets the primary group associated with the specified owner. (Inherited from ObjectSecurity.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetOwnerGets the owner associated with the specified primary group. (Inherited from ObjectSecurity.)
Public methodGetSecurityDescriptorBinaryFormReturns an array of byte values that represents the security descriptor information for this ObjectSecurity object. (Inherited from ObjectSecurity.)
Public methodGetSecurityDescriptorSddlFormReturns the Security Descriptor Definition Language (SDDL) representation of the specified sections of the security descriptor associated with this ObjectSecurity object. (Inherited from ObjectSecurity.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodModifyAccessApplies the specified modification to the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodModifyAccessRuleApplies the specified modification to the Discretionary Access Control List (DACL) associated with this ObjectSecurity object. (Inherited from ObjectSecurity.)
Protected methodModifyAuditApplies the specified modification to the System Access Control List (SACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodModifyAuditRuleApplies the specified modification to the System Access Control List (SACL) associated with this ObjectSecurity object. (Inherited from ObjectSecurity.)
Protected methodPersist(SafeHandle, AccessControlSections)Saves the specified sections of the security descriptor associated with this NativeObjectSecurity object to permanent storage. We recommend that the values of the includeSections parameters passed to the constructor and persist methods be identical. For more information, see Remarks. (Inherited from NativeObjectSecurity.)
Protected methodPersist(String, AccessControlSections)Saves the specified sections of the security descriptor associated with this NativeObjectSecurity object to permanent storage. We recommend that the values of the includeSections parameters passed to the constructor and persist methods be identical. For more information, see Remarks. (Inherited from NativeObjectSecurity.)
Protected methodPersist(Boolean, String, AccessControlSections)Saves the specified sections of the security descriptor associated with this ObjectSecurity object to permanent storage. We recommend that the values of the includeSections parameters passed to the constructor and persist methods be identical. For more information, see Remarks. (Inherited from ObjectSecurity.)
Protected methodPersist(SafeHandle, AccessControlSections, Object)Saves the specified sections of the security descriptor associated with this NativeObjectSecurity object to permanent storage. We recommend that the values of the includeSections parameters passed to the constructor and persist methods be identical. For more information, see Remarks. (Inherited from NativeObjectSecurity.)
Protected methodPersist(String, AccessControlSections, Object)Saves the specified sections of the security descriptor associated with this NativeObjectSecurity object to permanent storage. We recommend that the values of the includeSections parameters passed to the constructor and persist methods be identical. For more information, see Remarks. (Inherited from NativeObjectSecurity.)
Public methodPurgeAccessRulesRemoves all access rules associated with the specified IdentityReference. (Inherited from ObjectSecurity.)
Public methodPurgeAuditRulesRemoves all audit rules associated with the specified IdentityReference. (Inherited from ObjectSecurity.)
Protected methodReadLockLocks this ObjectSecurity object for read access. (Inherited from ObjectSecurity.)
Protected methodReadUnlockUnlocks this ObjectSecurity object for read access. (Inherited from ObjectSecurity.)
Protected methodRemoveAccessRule(AccessRule)Removes access rules that contain the same security identifier and access mask as the specified access rule from the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodRemoveAccessRule(SemaphoreAccessRule)Searches for an access control rule with the same user and AccessControlType (allow or deny) as the specified rule, and with compatible inheritance and propagation flags; if such a rule is found, the rights contained in the specified access rule are removed from it.
Protected methodRemoveAccessRuleAll(AccessRule)Removes all access rules that have the same security identifier as the specified access rule from the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodRemoveAccessRuleAll(SemaphoreAccessRule)Searches for all access control rules with the same user and AccessControlType (allow or deny) as the specified rule and, if found, removes them.
Protected methodRemoveAccessRuleSpecific(AccessRule)Removes all access rules that exactly match the specified access rule from the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodRemoveAccessRuleSpecific(SemaphoreAccessRule)Searches for an access control rule that exactly matches the specified rule and, if found, removes it.
Protected methodRemoveAuditRule(AuditRule)Removes audit rules that contain the same security identifier and access mask as the specified audit rule from the System Access Control List (SACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodRemoveAuditRule(SemaphoreAuditRule)Searches for an audit control rule with the same user as the specified rule, and with compatible inheritance and propagation flags; if a compatible rule is found, the rights contained in the specified rule are removed from it.
Protected methodRemoveAuditRuleAll(AuditRule)Removes all audit rules that have the same security identifier as the specified audit rule from the System Access Control List (SACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodRemoveAuditRuleAll(SemaphoreAuditRule)Searches for all audit rules with the same user as the specified rule and, if found, removes them.
Protected methodRemoveAuditRuleSpecific(AuditRule)Removes all audit rules that exactly match the specified audit rule from the System Access Control List (SACL) associated with this CommonObjectSecurity object. (Inherited from CommonObjectSecurity.)
Public methodRemoveAuditRuleSpecific(SemaphoreAuditRule)Searches for an audit rule that exactly matches the specified rule and, if found, removes it.
Protected methodResetAccessRule(AccessRule)Removes all access rules in the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object and then adds the specified access rule. (Inherited from CommonObjectSecurity.)
Public methodResetAccessRule(SemaphoreAccessRule)Removes all access control rules with the same user as the specified rule, regardless of AccessControlType, and then adds the specified rule.
Protected methodSetAccessRule(AccessRule)Removes all access rules that contain the same security identifier and qualifier as the specified access rule in the Discretionary Access Control List (DACL) associated with this CommonObjectSecurity object and then adds the specified access rule. (Inherited from CommonObjectSecurity.)
Public methodSetAccessRule(SemaphoreAccessRule)Removes all access control rules with the same user and AccessControlType (allow or deny) as the specified rule, and then adds the specified rule.
Public methodSetAccessRuleProtectionSets or removes protection of the access rules associated with this ObjectSecurity object. Protected access rules cannot be modified by parent objects through inheritance. (Inherited from ObjectSecurity.)
Protected methodSetAuditRule(AuditRule)Removes all audit rules that contain the same security identifier and qualifier as the specified audit rule in the System Access Control List (SACL) associated with this CommonObjectSecurity object and then adds the specified audit rule. (Inherited from CommonObjectSecurity.)
Public methodSetAuditRule(SemaphoreAuditRule)Removes all audit rules with the same user as the specified rule, regardless of the AuditFlags value, and then adds the specified rule.
Public methodSetAuditRuleProtectionSets or removes protection of the audit rules associated with this ObjectSecurity object. Protected audit rules cannot be modified by parent objects through inheritance. (Inherited from ObjectSecurity.)
Public methodSetGroupSets the primary group for the security descriptor associated with this ObjectSecurity object. (Inherited from ObjectSecurity.)
Public methodSetOwnerSets the owner for the security descriptor associated with this ObjectSecurity object. (Inherited from ObjectSecurity.)
Public methodSetSecurityDescriptorBinaryForm(Byte[])Sets the security descriptor for this ObjectSecurity object from the specified array of byte values. (Inherited from ObjectSecurity.)
Public methodSetSecurityDescriptorBinaryForm(Byte[], AccessControlSections)Sets the specified sections of the security descriptor for this ObjectSecurity object from the specified array of byte values. (Inherited from ObjectSecurity.)
Public methodSetSecurityDescriptorSddlForm(String)Sets the security descriptor for this ObjectSecurity object from the specified Security Descriptor Definition Language (SDDL) string. (Inherited from ObjectSecurity.)
Public methodSetSecurityDescriptorSddlForm(String, AccessControlSections)Sets the specified sections of the security descriptor for this ObjectSecurity object from the specified Security Descriptor Definition Language (SDDL) string. (Inherited from ObjectSecurity.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Protected methodWriteLockLocks this ObjectSecurity object for write access. (Inherited from ObjectSecurity.)
Protected methodWriteUnlockUnlocks this ObjectSecurity object for write access. (Inherited from ObjectSecurity.)
Top

A SemaphoreSecurity object specifies access rights for a named system semaphore, and also specifies how access attempts are audited. Access rights to the semaphore are expressed as rules, with each access rule represented by a SemaphoreAccessRule object. Each auditing rule is represented by a SemaphoreAuditRule 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 SemaphoreAccessRule or SemaphoreAuditRule object might represent more than one ACE.

NoteNote

A Semaphore object can represent a local semaphore or a named system semaphore. Windows access control security is meaningful only for named system semaphores.

The SemaphoreSecurity, SemaphoreAccessRule, and SemaphoreAuditRule 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 SemaphoreSecurity 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. SemaphoreSecurity 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 semaphore, use the Semaphore.GetAccessControl method to get the SemaphoreSecurity object. Modify the security object by adding and removing rules, and then use the Semaphore.SetAccessControl method to reattach it.

Important noteImportant

Changes you make to a SemaphoreSecurity object do not affect the access levels of the named semaphore until you call the Semaphore.SetAccessControl method to assign the altered security object to the named semaphore.

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

Users with an investment in the security descriptor definition language (SDDL) can use the SetSecurityDescriptorSddlForm method to set access rules for a named semaphore, 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 SemaphoreSecurity 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 Semaphore object. Examples that attach security objects can be found in Semaphore.GetAccessControl and Semaphore.SetAccessControl.


using System;
using System.Threading;
using System.Security.AccessControl;
using System.Security.Principal;

public class Example
{
    public static void Main()
    {
        // Create a string representing the current user.
        string user = Environment.UserDomainName + "\\" + 
            Environment.UserName;

        // Create a security object that grants no access.
        SemaphoreSecurity mSec = new SemaphoreSecurity();

        // Add a rule that grants the current user the 
        // right to enter or release the semaphore.
        SemaphoreAccessRule rule = new SemaphoreAccessRule(user, 
            SemaphoreRights.Synchronize | SemaphoreRights.Modify, 
            AccessControlType.Allow);
        mSec.AddAccessRule(rule);

        // Add a rule that denies the current user the 
        // right to change permissions on the semaphore.
        rule = new SemaphoreAccessRule(user, 
            SemaphoreRights.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 semaphore. This rule
        // is merged with the existing Allow rule.
        rule = new SemaphoreAccessRule(user, 
            SemaphoreRights.ReadPermissions, 
            AccessControlType.Allow);
        mSec.AddAccessRule(rule);

        ShowSecurity(mSec);
    }

    private static void ShowSecurity(SemaphoreSecurity security)
    {
        Console.WriteLine("\r\nCurrent access rules:\r\n");

        foreach(SemaphoreAccessRule ar in 
            security.GetAccessRules(true, true, typeof(NTAccount)))
        {
            Console.WriteLine("        User: {0}", ar.IdentityReference);
            Console.WriteLine("        Type: {0}", ar.AccessControlType);
            Console.WriteLine("      Rights: {0}", ar.SemaphoreRights);
            Console.WriteLine();
        }
    }
}

/*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
 */


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

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

Community Additions

Show:
© 2014 Microsoft