PROPID_M_SIGNATURE

 

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_SIGNATURE property specifies the MSMQ 1.0 signature or application-generated signature that is attached to the message.

Property ID

PROPID_M_SIGNATURE

Type Indicator

VT_VECTOR | VT_UI1

MQPROPVARIANT Field

caub

Property Value

Digital signature.

Remarks

In most cases, this property is set by the Message Queuing runtime when the sending application requests authentication. This property can also be set by connector applications sending messages to Message Queuing. In these cases, the receiving application can use this property to retrieve the MSMQ 1.0 or application-generated signature attached to the message.

Note

This property contains an MSMQ 1.0 signature only if the sending application specified an MSMQ 1.0 signature when requesting authentication.

Connector applications may also set this property when they call MQSendMessage. However, when a connector application sets this property, Message Queuing does not generate a digital signature for this property. The connector application must generate the digital signature itself based on the certificate of the user sending the message.

When connector applications set PROPID_M_SIGNATURE, the PROPID_M_CONNECTOR_TYPE property must also be set so that Message Queuing does not generate a digital signature. PROPID_M_SIGNATURE is ignored if PROPID_M_CONNECTOR_TYPE is not also set when the message is sent.

Setting the Digital Signature

To set the digital signature, the connector application must specify PROPID_M_SIGNATURE and PROPID_M_SIGNATURE_LEN in the MQMSGPROPS structure and call MQSendMessage.

Retrieving the Digital Signature

To retrieve the digital signature, specify PROPID_M_SIGNATURE and PROPID_M_SIGNATURE_LEN in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned value.

If MQReceiveMessage or MQReceiveMessageByLookupId fails, returning an MQ_ERROR_SIGNATURE_BUFFER_OVERFLOW error, use the returned value of PROPID_M_SIGNATURE_LEN to reallocate the message body buffer and call the applicable function again.

Before using the retrieved digital signature, always check the length property PROPID_M_SIGNATURE_LEN to see whether the digital signature was sent in this property with the message. If the returned value of PROPID_M_SIGNATURE_LEN is 0, no signature was sent in this property with the message. If the returned value is non-0, PROPID_M_SIGNATURE contains a digital signature.

Note

If the sending application sent an MSMQ 2.0 signature, but did not attach an MSMQ 1.0 signature, this property will contain a buffer of 4 zeroed bytes.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving the MSMQ 1.0 or application-generated signature attached to the message is MSMQMessage.Signature.

For information on	See
How Message Queuing creates digital signatures	How Message Queuing Authenticates Messages
MSMQ 1.0 signatures	Digital Signatures
Authenticating messages sent by a connector application	Connector Application Security

Example Code

The following code fragments show how PROPID_M_SIGNATURE and PROPID_M_SIGNATURE_LEN are specified in arrays that can be used to initialize an MQMSGPROPS structure for attaching and retrieving a digital signature.

To Attach the Digital Signature

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

To Retrieve the Digital Signature

ULONG ulSignatureBufferSize = 1024;  
UCHAR * pucSignatureBuffer = NULL;  
pucSignatureBuffer = (UCHAR *)malloc(ulSignatureBufferSize);  
if (pucSignatureBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucSignatureBuffer, 0, ulSignatureBufferSize);  
aMsgPropID[i] = PROPID_M_SIGNATURE;                       // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;                   // Type indicator  
aMsgPropVar[i].caub.pElems = (UCHAR*)pucSignatureBuffer;  
aMsgPropVar[i].caub.cElems = ulSignatureBufferSize;  
i++  
  
aMsgPropId[i] = PROPID_M_SIGNATURE_LEN;                   // Property ID  
aMsgPropVar[i].vt = VT_UI4;                               // Type indicator  
i++;  
  
// Reallocate memory for the Signature buffer if necessary.  
ulSignatureBufferSize = aMsgPropVar[1].ulVal*sizeof(UCHAR);  
pucSignatureBuffer = (UCHAR*)realloc(pucSignatureBuffer, ulSignatureBufferSize);  
if (pucSignatureBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucSignatureBuffer, 0, ulSignatureBufferSize);  
aMsgPropVar[0].caub.pElems = (UCHAR*)pucSignatureBuffer;  // Pointer to the new buffer  
aMsgPropVar[0].caub.cElems = ulSignatureBufferSize;       // New buffer size  

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
MSMQMessage.Signature
PROPID_M_CONNECTOR_TYPE
PROPID_M_SIGNATURE_LEN