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.