MSMQMessage.AttachCurrentSecurityContext2

Article
10/19/2016

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 AttachCurrentSecurityContext2 method of the MSMQMessage object caches an internal or external certificate and the corresponding private key in a security context structure along with the user's SID and additional security information needed to attach the certificate to a message when requesting authentication. The method also stores the handle to this structure in the object.

This method supersedes MSMQMessage.AttachCurrentSecurityContext.

Sub AttachCurrentSecurityContext2()

Parameters

This method has no parameters.

Return Values

This method has no return values.

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

The AttachCurrentSecurityContext2 method is used whenever possible to send large numbers of messages using the same certificate or when impersonating another user. This method provides an easy, efficient way to send a large number of messages that require authentication using the same certificate.

AttachCurrentSecurityContext2 creates a security context structure based on the certificate that is in the MSMQMessage.SenderCertificate property, the corresponding private key, and the user's SID. If MSMQMessage.SenderCertificate is not set before calling AttachCurrentSecurityContext2, the Message Queuing internal certificate for the user is used for the security context.

After this method has been called to create a security context structure and store a handle to the structure in the object, the same object can be used to send multiple messages with the same certificate by resetting the MSMQMessage.Body property and other applicable properties after each message is sent. The memory allocated for the security context structure is freed when the object is destroyed.

If, however, the sending application is using more than one certificate, it must call AttachCurrentSecurityContext2 on a different MSMQMessage object for each certificate it will use.

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

The hive of the impersonated user can be loaded manually using a tool such as RegEdt32.

The AttachCurrentSecurityContext2 method supersedes the MSMQMessage.AttachCurrentSecurityContext method. Both methods provide the same functionality, however AttachCurrentSecurityContext2 provides improved security.

In C++ COM applications, you must use a smart pointer to the IMSMQMessage3 interface to expose the AttachCurrentSecurityContext2 method.

Equivalent API Function

With API function calls, the equivalent function is MQGetSecurityContextEx.

For information on	See
What it means to authenticate a message: message integrity and sender authentication	Message Authentication
The process used to authenticate a messages	How Message Queuing Authenticates Messages
Using a security context structure	When to Use a Security Context Structure
Using a security context when impersonating another user	Impersonating a User

Requirements

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

Windows 95/98/Me: Unsupported.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib