When to Use a Security Context Structure

 

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

When an application sends an authenticated message, in addition to attaching the user's SID (the sender identifier), the Message Queuing runtime automatically attaches the internal certificate for the user to the message, by default, or the sending application can attach an external certificate. Alternatively, the sending application can request Message Queuing to cache a specific internal or external certificate, the corresponding private key, the user's SID, and other security information in a security context structure, which can then be used to attach the same SID and certificate to any number of messages.

Use a security context structure when you are sending a large number of messages using the same certificate or when you are impersonating a user.

When a security context structure is specified in the message, the Message Queuing runtime uses the private key stored in it to sign the messages. The user's SID, the digital signature, and the certificate are attached to the messages without having to retrieve the private key, fetch the certificate from the certificate store, or extract the other information each time a message is sent.

Note

The information stored in a security context structure is used only by the sender. It is used to attach a certificate to a message and is not available to the receiving application.

To create a security context structure for a specific external certificate or the internal certificate provided by Message Queuing, the sending application must call the API function MQGetSecurityContextEx or the COM method MSMQMessage.AttachCurrentSecurityContext2.

To use the default security context (the internal certificate for the user), simply send the authenticated message without specifying a certificate and without specifying a security context. The default security context is initialized when you open the queue to send messages.

Note

MQGetSecurityContextEx does not associate the cached information with a specific message. It places the information in a security context structure and returns a handle to the structure in an out parameter. Consequently, in C/C++ applications, you must specify the handle to this security context structure in the security context property (PROPID_M_SECURITY_CONTEXT) of each message before you send it. After the security context structure is no longer needed, the memory allocated for the security context structure must be freed by calling MQFreeSecurityContext.

When the MSMQMessage.AttachCurrentSecurityContext2 COM method is used, you can call it once on a single MSMQMessage object whose MSMQMessage.SenderCertificate property has been set using the applicable certificate. This method creates a security context structure containing the certificate in MSMQMessage.SenderCertificate and stores a handle to the structure in the object. Then you can use this object repeatedly to send numerous messages by resetting the MSMQMessage.Body property, as well as other properties, as required, to create each message. The memory allocated for the security context structure is freed when the object is destroyed.

When you use a security context structure, do not attach a certificate to message; the Message Queuing runtime will do this for you. Security context information is ignored if the sender certificate property of the message (PROPID_M_SENDER_CERT or MSMQMessage.SenderCertificate) contains a different certificate.

When impersonating another user, the sending application must call MQGetSecurityContextExMQGetSecurityContextExor MSMQMessage.AttachCurrentSecurityContext2 before it sends a message. When the COM method is used, it uses MQGetSecurityContextEx internally 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 to send another message without needing to impersonate the user again.

More Information

For information on	See
Message integrity and sender authentication	Message Authentication
The process of authenticating messages	How Message Queuing Authenticates Messages
How to retrieve the security context of another user	Impersonating a User