Share via


MQSetQueueSecurity

 

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQSetQueueSecurity function sets security information in the security descriptor of a queue.

HRESULT APIENTRY MQSetQueueSecurity(  
  LPCWSTR lpwcsFormatName,                      
  SECURITY_INFORMATION SecurityInformation,    
  PSECURITY_DESCRIPTOR pSecurityDescriptor    
);  

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue to be secured. A public or private format name can be used. You can only use a direct format name to set the security of a local private queue.

SecurityInformation

[in] Specifies a SECURITY_INFORMATION value identifying the items of security information being set using the security descriptor buffer pointed to by the pSecurityDescriptor parameter. The following SECURITY_INFORMATION bit flags or a combination of these bit flags can be used to identify the components of security information being set.

DACL_SECURITY_INFORMATION

Indicates that the discretionary access control list (DACL) is being set.

GROUP_SECURITY_INFORMATION

Indicates that the primary group security identifier is being set.

OWNER_SECURITY_INFORMATION

Indicates that the owner's security identifier (SID) is being set.

SACL_SECURITY_INFORMATION

Indicates that the system access control list (SACL) is being set.

Message Queuing does not support the use of the following bit flags in this parameter:

PROTECTED_DACL_SECURITY_INFORMATION

PROTECTED_SACL_SECURITY_INFORMATION

UNPROTECTED_DACL_SECURITY_INFORMATION

UNPROTECTED_SACL_SECURITY_INFORMATION

pSecurityDescriptor

[in] Pointer to a SECURITY_DESCRIPTOR structure containing the new information. Components of the queue's security information that are not specified in this structure are set to the default values. This parameter can be set to a NULL pointer; see the default values in the following Remarks section.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The access rights for setting the queue security information are not allowed for the process owner. The following access rights may be required:

MQSEC_CHANGE_QUEUE_PERMISSIONS

MQSEC_TAKE_QUEUE_OWNERSHIP

If access is denied, contact someone who has rights to modify the security descriptor.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

An invalid or unsupported flag was specified in SecurityInformation.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_PRIVILEGE_NOT_HELD (0xC00E0026)

The process owner does not have the proper privilege to set the queue's system access control list.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

The format name specified in the lpwcsFormatName parameter cannot be used. You cannot reference a public queue or a remote private queue in a call to this function using a direct format name, nor can you set the security rights of a journal, dead-letter, or connector queue.

MQ_INFORMATION_OWNER_IGNORED (0x400E000B)

MQSetQueueSecurity did not set the owner of the queue; however, it did set the other elements identified in the SECURITY_INFORMATION structure.

Note

Apart from generic Message Queuing error codes, this function may return ADSI and LDAP error codes. For example, LDAP_BUSY (0x8007200E) is returned when the directory service server is busy.

Remarks

The following access rights and privileges are required to change the security descriptor of a queue.

  • MQSEC_TAKE_QUEUE_OWNERSHIP:

Required to change the owner of the queue. This access right is equivalent to WRITE_OWNER as defined by the Win32® header files.

  • SE_TAKE_OWNERSHIP_NAME:

Required to change the owner of the queue. This privilege can be used instead of having the MQSEC_TAKE_QUEUE_OWNERSHIP access on the queue. If a user has this privilege on the server, the user can change the owner of any public queue in the enterprise. If the user has this privilege on the local computer, the user can change the owner of any private queue.

  • MQSEC_CHANGE_QUEUE_PERMISSIONS:

Required to change the queue's discretionary access control list (DACL) if the process is not the owner of the queue. This access right is equivalent to WRITE_DAC as defined by the Win32 header files.

  • SE_SECURITY_NAME:

Required to change the queue's system ACL (SACL); this privilege must be enabled for the calling process on the directory service for public queues and on the local computer for private queues.

Queues can be referenced using a public or private format name. Direct format names can be used only to reference a local private queue. Message Queuing must be able to access the directory service for public queues, or the local computer for private queues. If the format name of the queue is unknown, see Obtaining Format Names.

The security descriptors of journal and dead-letter queues cannot be set. Access to these queues is controlled by the security descriptor of the Message Queuing Configuration object of the computer that owns these queues. You can set the security descriptor of a foreign queue, but the send, receive, and peek permissions are ignored by Message Queuing. You cannot directly set the security descriptor of a connector queue. To control receive and peek access to this queue, you must change the security descriptor of the appropriate foreign site and grant the "Open Connector Queue" permission to the desired accounts.

A public queue's access security cannot be set if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS). (For information on offline operations, see Message Queuing Offline Support.)

Setting the Access Mask of an Access Control Entry

The following flags can be used to grant or deny permissions in the access mask of an access control entry (ACE) in the security descriptor.

  • MQSEC_DELETE_MESSAGE

  • MQSEC_PEEK_MESSAGE

  • MQSEC_WRITE_MESSAGE

  • MQSEC_DELETE_JOURNAL_MESSAGE

  • MQSEC_SET_QUEUE_PROPERTIES

  • MQSEC_GET_QUEUE_PROPERTIES

  • MQSEC_DELETE_QUEUE

  • MQSEC_GET_QUEUE_PERMISSONS

  • MQSEC_CHANGE_QUEUE_PERMISSIONS

  • MQSEC_TAKE_QUEUE_OWNERSHIP

  • MQSEC_RECEIVE_MESSAGE

    (MQSEC_DELETE_MESSAGE | MQSEC_PEEK_MESSAGE)

  • MQSEC_RECEIVE_JOURNAL_MESSAGE

    (MQSEC_DELETE_JOURNAL_MESSAGE |

    MQSEC_PEEK_MESSAGE)

  • MQSEC_QUEUE_GENERIC_READ

    (MQSEC_GET_QUEUE_PROPERTIES | \

    MQSEC_GET_QUEUE_PERMISSIONS | \

    MQSEC_GET_RECEIVE_MESSAGE | \

    MQSEC_GET_RECEIVE_JOURNAL_MESSAGE)

  • MQSEC_QUEUE_GENERIC_WRITE

    (MQSEC_GET_QUEUE_PROPERTIES | \

    MQSEC_GET_QUEUE_PERMISSIONS | \

    MQSEC_GET_WRITE_MESSAGE)

  • MQSEC_QUEUE_GENERIC_ALL

    (MQSEC_RECEIVE_MESSAGE | \

    MQSEC_RECEIVE_MESSAGE_JOURNAL | \

    MQSEC_WRITE_MESSAGE | \

    MQSEC_SET_QUEUE_PROPERTIES | \

    MQSEC_GET_QUEUE_PROPERTIES | \

    MQSEC_GET_DELETE_QUEUE | \

    MQSEC_GET_QUEUE_PERMISSIONS | \

    MQSEC_GET_CHANGE_QUEUE_PERMISSIONS | \

    MQSEC_TAKE_QUEUE_OWNERSHIP)

Default Security Descriptor Values

Following are the default values for the components of a queue's security descriptor.

Component Default Value
Owner The security identifier (SID) of the queue's creator.
Group The security identifier (SID) of the primary group corresponding to the queue's creator.
DACL Full control for the queue's creator. All other users (processes) can get queue properties, get queue security, and send messages to the queue. In MSMQ 3.0, anonymous users can only send messages to the queue, and the Computer_Name$ account of the computer that belongs to a domain and hosts the queue can only get the properties and security of the queue.
SACL None.

Example Code

The following code examples are included in Using Message Queuing.

For an example of See
Changing the security settings of a queue to allow all members of the Everyone group to receive messages from a queue C/C++ Code Example: Granting Additional Access Rights
Creating a security descriptor that gives a specified trusted user full control over a queue C/C++ Code Example: Creating a Security Descriptor

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.

See Also

Message Queuing Functions
MQGetQueueSecurity