MQGetSecurityContext

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 MQGetSecurityContext function caches an internal certificate or an external certificate, the corresponding private key, the user's SID, and other security information needed to attach the certificate and 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 is superseded by MQGetSecurityContextEx in Windows® 2000 Service Pack 2 and later.

HRESULT APIENTRY MQGetSecurityContext(  
  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, it is set 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_INTERNAL_CERTIFICATE (0xC00E002D)

(MSMQ 1.0 only) The Message Queuing-supplied internal certificate is corrupted.

MQ_ERROR_CORRUPTED_SECURITY_DATA (0xC00E0030)

Cryptographic function (CryptoAPI) 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 IN parameters supplied by the operation is not valid.

MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027)

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

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 MQGetSecurityContext function is obsolete. Use MQGetSecurityContextEx whenever possible. Both functions provide the same functionality, however MQGetSecurityContextEx provides more security when impersonating another user.

When you are sending authenticated messages, MQGetSecurityContext retrieves the user's SID and the information that the Message Queuing runtime needs to attach a certificate to a message, 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 MQGetSecurityContext is used, the sending application is only responsible for passing the security context structure (PROPID_M_SECURITY_CONTEXT) to MQSendMessage.

When using more than one certificate, the sending application must call MQGetSecurityContextEx for each certificate that is used.

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

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
MQFreeSecurityContext
MQSendMessage
PROPID_M_SECURITY_CONTEXT
PROPID_M_SENDER_CERT