MQGetSecurityContext

The MQGetSecurityContext function retrieves security information needed to authenticate messages.

VOID APIENTRY MQGetSecurityContext(
  LPVOID lpCertBuffer,      
  DWORD dwCertBufferLength,  
  HANDLE *hSecurityContext  
);
 

Parameters

lpCertBuffer
[In] Pointer to the security certificate buffer. External certificates must be in ASN.1 DER encoded format. If this parameter is NULL, the internal security certificate provided by MSMQ is used.
dwCertBufferLength
[In] Length of the security certificate buffer pointed to by lpCertBuffer. For internal certificates, set to 0.
hSecurityContext
[Out] Handle to the security context buffer allocated by MSMQ.

Return Values

MQ_OK
Indicates success.
MQ_ERROR_COULD_NOT_GET_USER_SID
MSMQ could not get the specified sender identifier.
MQ_ERROR_NO_DS
Only Windows 95. Cannot access Active Directory.
MQ_ERROR_INVALID_PARAMETER
One of the IN parameters supplied by the operation is not valid.
MQ_ERROR_INSUFFICIENT_RESOURCES
Insufficient resources to complete operation (for example, not enough memory). Operation failed.
MQ_ERROR_INVALID_CERTIFICATE
Security certificate specified by PROPID_M_SENDER_CERT is invalid, or the certificate is not correctly placed in the Microsoft® Internet Explorer personal certificate store.
MQ_ERROR_CORRUPTED_INTERNAL_CERTIFICATE
MSMQ-supplied internal certificate is corrupted.
MQ_ERROR_CORRUPTED_SECURITY_DATA
Cryptographic function (CryptoAPI) has failed.

Remarks

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.

QuickInfo

  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.

See Also

MQFreeSecurityContext, MQSendMessage, PROPID_M_SECURITY_CONTEXT