MQGetSecurityContextEx

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

(Introduced in Windows® 2000 Service Pack 2.) The MQGetSecurityContextEx function caches an internal certificate or an external certificate, the corresponding private key, the user's SID, and other information needed to attach the certificate and the sender identifier to a message when requesting authentication in a security context structure and returns the handle to this structure in an out parameter.

This function supersedes MQGetSecurityContext.

HRESULT APIENTRY MQGetSecurityContextEx(  
  LPVOID lpCertBuffer,        
  DWORD dwCertBufferLength,    
  HANDLE * phSecurityContext    
);  

Parameters

lpCertBuffer

[In] Pointer to the user certificate buffer. External certificates must be in ASN.1 DER encoded format. If this parameter is NULL, the internal certificate provided by Message Queuing is used.

dwCertBufferLength

[In] Length of the user certificate buffer pointed to by lpCertBuffer. For internal certificates, set this parameter to 0.

phSecurityContext

[Out] Pointer to a variable that receives a handle to the security context structure allocated by Message Queuing.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_CORRUPTED_SECURITY_DATA (0xC00E0030)

A cryptographic API function has failed.

MQ_ERROR_COULD_NOT_GET_USER_SID (0xC00E0036)

Message Queuing could not retrieve the user's SID from the thread access token.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

One of the input parameters supplied is not valid.

MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027)

There are not enough resources to complete operation (for example, not enough memory).

MQ_ERROR_INVALID_CERTIFICATE (0xC00E002C)

The certificate is not correctly placed in the Microsoft® Internet Explorer personal certificate store.

MQ_ERROR_NO_INTERNAL_USER_CERT (0xC00E002F)

No internal certificate is registered, or the registered certificate is corrupted.

Remarks

The MQGetSecurityContextEx function is used whenever possible to send large numbers of messages using the same certificate or when impersonating another user.

When sending authenticated messages (and not impersonating another user), the sending application must call MQGetSecurityContextEx and MQSendMessage in the same user context.

When an application sends authenticated messages, the call to MQGetSecurityContextEx retrieves the user's SID and the information that the Message Queuing runtime needs to attach the same certificate to each of several messages, caches the information in a security context structure together with the certificate and the corresponding private key, and returns the handle to this structure in an out parameter. The handle can be used to send multiple messages. This provides an easier, more efficient way to send a large number of messages that require authentication using the same certificate. When MQGetSecurityContextEx is used, the sending application is responsible only for passing the security context structure (PROPID_M_SECURITY_CONTEXT) to MQSendMessage.

If, however, the sending application is using more than one certificate, it must call MQGetSecurityContextEx for each certificate it uses.

When impersonating another user, the sending application must load the hive of the impersonated user, impersonate the user, and then call MQGetSecurityContextEx before it sends the messages of the impersonated user. Internally, MQGetSecurityContextEx uses the RegOpenCurrentUser function to access the user hive where the certificate of the impersonated user is stored. Once the security information for the impersonated user is retrieved, the sending application can revert to the original user and later use the impersonated security context information to send another message without needing to impersonate the user again.

The hive of the impersonated user can be loaded programmatically, or manually using a tool such as RegEdit32.

After the security context is no longer needed, free the memory allocated for the security context structure by calling MQFreeSecurityContext.

The MQGetSecurityContextEx function supersedes MQGetSecurityContext. Both functions provide the same functionality, however MQGetSecurityContextEx provides improved security.

Equivalent COM Method

When using COM components, you can retrieve security context information and create a security context structure by calling MSMQMessage.AttachCurrentSecurityContext2.

Requirements

Windows NT/2000/XP: Included in Windows 2000 SP2 and later.

Windows 95/98/Me: Unsupported.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.

See Also

Message Queuing Functions
MQFreeSecurityContext
MQGetSecurityContext
MQSendMessage
PROPID_M_SECURITY_CONTEXT