PROPID_M_SENDER_CERT

 

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

The PROPID_M_SENDER_CERT property specifies the user certificate used to authenticate messages.

Property ID

PROPID_M_SENDER_CERT

Type Indicator

VT_VECTOR | VT_UI1

MQPROPVARIANT Field

caub

Property Value

User certificate (the default is the internal certificate provided by Message Queuing).

Remarks

Use PROPID_M_SENDER_CERT when you want to authenticate a small number of messages with the same certificate.

Note

When sending a large number of messages using the same certificate, use a security context structure to attach the certificate. A security context structure is created by calling MQGetSecurityContext.

Sending the Sender Certificate

To attach a certificate to a message, specify PROPID_M_SENDER_CERT in the MQMSGPROPS structure and call MQSendMessage. (When using an internal certificate, Message Queuing includes the internal certificate in this property and attaches the property to the message for you.)

Message Queuing uses the certificate to authenticate the message. However, the receiving application can also use the information in an external certificate to verify who sent the message. (When an internal certificate is used, the information in the certificate is not useful to the receiving application.)

Retrieving the Sender Certificate

The receiving application should retrieve PROPID_M_SENDER_CERT only when an external certificate was sent with the message. After retrieving the certificate, use the CryptoAPI functions to validate the information in the certificate. (If you don't know whether an external or internal certificate was sent, retrieve the certificate and look at its locality attribute. If the locality attribute was set by Message Queuing, then the certificate is a Message Queuing internal certificate.)

To retrieve the sender certificate, specify PROPID_M_SENDER_CERT and PROPID_M_SENDER_CERT_LEN in the MQMSGPROPS structure (the length property is used to verify that the sender certificate was sent). Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values.

If MQReceiveMessage or MQReceiveMessageByLookupId fails, returning an MQ_ERROR_SENDER_CERT_BUFFER_TOO_SMALL error, use the returned value of PROPID_M_SENDER_CERT_LEN to reallocate the sender certificate buffer and call the applicable function again.

Before using the returned sender certificate, always check the length property PROPID_M_SENDER_CERT_LEN to see if the sender certificate was sent with the message. If the returned value of PROPID_M_SENDER_CERT_LEN is 0, no certificate was sent with the message. If the returned value is non-0, PROPID_M_SENDER_CERT contains the certificate used when sending the message.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving the sender certificate attached to a message is MSMQMessage.SenderCertificate.

For information on	See
What it means to authenticate a message	Message Authentication
Registering internal and external certificates	Registering a Certificate
How messages are authenticated	Message Authentication
Using a security context structure	When to Use a Security Context Structure

Example Code

The following code fragments show how PROPID_M_SENDER_CERT is specified in arrays that can be used to initialize an MQMSGPROPS structure for setting and retrieving the sender certificate.

To Send the Sender Certificate

aMsgPropId[i] = PROPID_M_SENDER_CERT;                       // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;                     // Type indicator  
aMsgPropVar[i].caub.pElems = SenderCertificate;  
aMsgPropVar[i].caub.cElems = sizeof(SenderCertificate);  
i++;  

To Retrieve the Sender Certificate

ULONG ulSenderCertBufferSize = 4096;  
UCHAR * pucSenderCertBuffer = NULL;  
pucSenderCertBuffer = (UCHAR *)malloc(ulSenderCertBufferSize);  
if (pucSenderCertBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucSenderCertBuffer, 0, ulSenderCertBufferSize);  
aMsgPropId[i] = PROPID_M_SENDER_CERT;                       // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;                     // Type indicator  
aMsgPropVar[i].caub.pElems = (UCHAR*)pucSenderCertBuffer;  
aMsgPropVar[i].caub.cElems = ulSenderCertBufferSize;  
i++;  
  
aMsgPropId[i] = PROPID_M_SENDER_CERT_LEN;                   // Property ID  
aMsgPropVar[i].vt = VT_NULL;                                // Type indicator  
i++;  
  
// Reallocate memory for the sender certificate buffer if necessary.  
ulSenderCertBufferSize = aMsgPropVar[1].ulVal*sizeof(UCHAR);  
pucSenderCertBuffer = (UCHAR*)realloc(pucSenderCertBuffer, ulSenderCertBufferSize);  
if (pucSenderCertBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucSenderCertBuffer, 0, ulSenderCertBufferSize);  
aMsgPropVar[0].caub.pElems = (UCHAR*)pucSenderCertBuffer;  // Pointer to the new buffer  
aMsgPropVar[0].caub.cElems = ulSenderCertBufferSize;       // New buffer size  

See Also

Message Properties
MQMSGPROPS
MQGetSecurityContext
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_SENDER_CERT_LEN