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.

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.

Example Code

The following code examples are included in Using Message Queuing.

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