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. No connection with the Site Controller server. Cannot access the MQIS.

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 ReqCloseKey(HKEY_CURRENT_USER) to close the current user registry, then call ImpersonateLoggedOnUser() and MQGetSecurityContext to access the impersonated user registry to retrieve information about the impersonated user. The calls to RegCloseKey(), ImpersonateLoggedOnUser, MQGetSecurityContext, plus 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 Platform SDK.

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

Windows 95 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.

See Also

MQFreeSecurityContext, MQSendMessage, PROPID_M_SECURITY_CONTEXT

© 1997 by Microsoft Corporation. All rights reserved.