The MQGetSecurityContext function retrieves security information needed to authenticate messages.
VOID APIENTRY MQGetSecurityContext(
LPVOID lpCertBuffer,
DWORD dwCertBufferLength,
HANDLE *hSecurityContext
);
The MQGetSecurityContext function retrieves the information MSMQ needs to authenticate messages from the supplied certificate. It provides a way to send messages that require authentication in a more efficient way. MQGetSecurityContext should be used when the same certificate is used to send multiple messages and when impersonating another user.
Although the security information in the certificate can be retrieved directly by the sending application, this function retrieves and caches the needed information using a single function call. When MQGetSecurityContext is used, the sending application is only responsible for passing the security context buffer (PROPID_M_SECURITY_CONTEXT) to MQSendMessage.
When authenticating messages, MSMQ must track which sender certificate is associated with which message. Consequently, calling MQSendMessage must be done in the same user context as the call to MQGetSecurityContext. If MQGetSecurityContext is not called before the message is sent (or PROPID_M_SECURITY_CONTEXT is not passed to MQSendMessage) the security context of the user who originally ran the process is used.
When more than one certificate is used, MQGetSecurityContext must be called for each certificate the sending application wants to use.
When impersonating another user, MQGetSecurityContext must be called before a message is sent. 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 to send the message without the need to impersonate the user again.
To retrieve the security information of an impersonated user, HKEY_CURRENT_USER must point to the registry of the impersonated user. To do this, call the Win32 API function RegLoadKey() to load the impersonated user's registry hive. Call RegCloseKey (HKEY_CURRENT_USER) to close the current user registry, then call ImpersonateLoggedOnUser() and MQGetSecurityContext to access the impersonated user registry and retrieve information about the impersonated user. The calls to RegCloseKey(), ImpersonateLoggedOnUser (), MQGetSecurityContext, and any other calls that may access the registry under HKEY_CURRENT_USER must be protected by the same critical section object.
Note For information on RegLoadKey(), RegCloseKey(), ImpersonateLoggedOnUser(), and critical section objects, see the Microsoft Platform SDK.
After the security certificate is no longer needed, free the memory allocated for the security context buffer by calling MQFreeSecurityContext.
The security context of a certificate cannot be retrieved if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers (working offline), and MSMQ routing servers (FRS). (For information on offline operations, see MSMQ Offline Support.)
Windows 95-based applications cannot retrieve the security context of the certificate when operating on an independent client computer running offline. For information on offline operations, see MSMQ Offline Support.
Windows NT: Requires version 4.0 SP3 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in mq.h.
Import Library: Use mqrt.lib.
Unicode: Defined only as Unicode.
MQFreeSecurityContext, MQSendMessage, PROPID_M_SECURITY_CONTEXT