PROPID_M_DEST_SYMM_KEY

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_DEST_SYMM_KEY property specifies the symmetric key used to encrypt the message.

Property ID

PROPID_M_DEST_SYMM_KEY

Type Indicator

VT_VECTOR | VT_UI1

MQPROPVARIANT Field

caub

Property Value

Encrypted symmetric key

Remarks

PROPID_M_DEST_SYMM_KEY is required when you send application-encrypted messages, or when you send encrypted messages to a foreign queue. In both cases, this property contains an encrypted version of the symmetric key that the sending application used to encrypt the body of the message.

When sending an application-encrypted message, the sending application must encrypt the symmetric key that it used to encrypt the message body using the public key of the destination queue manager. The destination queue manager uses the decrypted symmetric key to decrypt the message before placing it in its destination queue.

Messages sent to a foreign queue are first received by the appropriate connector application and then passed on to the foreign queue. When the connector application receives an application-encrypted message, it can decrypt the message body itself or forward the encrypted message body with the attached symmetric key on to the foreign queue. If the connector application does not decrypt the message, it is the responsibility of the receiving application to decrypt the symmetric key and the body of the message.

To send the symmetric key with a message, specify PROPID_M_DEST_SYMM_KEY and PROPID_M_CONNECTOR_TYPE in the MQMSGPROPS structure and call MQSendMessage. PROPID_M_CONNECTOR_TYPE must be set to tell Message Queuing to use the symmetric key provided by the sending application.

To retrieve the symmetric key from a message, specify PROPID_M_DEST_SYMM_KEY and PROPID_M_DEST_SYMM_KEY_LEN in the MQMSGPROPS structure (the length property is used to verify that the symmetric key was sent). Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values.

If MQReceiveMessage or MQReceiveMessageByLookupId fails, returning an MQ_ERROR_SYMM_KEY_BUFFER_TOO_SMALL error, use the returned value of PROPID_M_DEST_SYMM_KEY_LEN to reallocate the symmetric key buffer and call the applicable function again.

Before using the returned symmetric key, always check the length property PROPID_M_DEST_SYMM_KEY_LEN to see if a symmetric key was sent. If the returned value of the length property is 0, no key was sent. If the returned value is nopn-0, PROPID_M_DEST_SYMM_KEY contains the symmetric key.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving the destination symmetric key is MSMQMessage.DestinationSymmetricKey.

Example Code

The following code fragments show how PROPID_M_DEST_SYMM_KEY is specified in arrays that can be used to initialize an MQMSGPROPS structure when sending and retrieving the symmetric key.

To Send the Destination Symmetric Key

aMsgPropId[i] = PROPID_M_DEST_SYMM_KEY;     // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;     // Type indicator  
aMsgPropVar[i].caub.pElems = DestSymmetricKey;  
aMsgPropVar[i].caub.cElems = sizeof(DestSymmetricKey);  
i++;  
  
aMsgPropId[i] = PROPID_M_CONNECTOR_TYPE;            // Property ID  
aMsgPropVar[i].vt = VT_CLSID;                       // Type indicator  
aMsgPropVar[i].puuid = &guidConnectorType;  
i++;  
To Retrieve the Destination Symmetric Key  
aMsgPropId[i] = PROPID_M_DEST_SYMM_KEY_LEN;         // Property ID  
aMsgPropVar[i].vt = VT_NULL;                        // Type indicator  
i++;  
  
ULONG ulKeyBufferSize = 1024;  
UCHAR * pucKeyBuffer = NULL;  
pucKeyBuffer = (UCHAR *)malloc(ulKeyBufferSize);  
if (pucKeyBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucKeyBuffer, 0, ulKeyBufferSize);  
aMsgPropId[i] = PROPID_M_DEST_SYMM_KEY;             // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;             // Type indicator  
aMsgPropVar[i].caub.pElems = pucKeyBuffer;  
aMsgPropVar[i].caub.cElems = ulKeyBufferSize;  
i++;  
  
// Reallocate memory for the symmetric key buffer if necessary.  
ulKeyBufferSize = aMsgPropVar[0].ulVal*sizeof(UCHAR);  
pucKeyBuffer = (UCHAR*)realloc(pucKeyBuffer, ulKeyBufferSize);  
if (pucKeyBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucKeyBuffer, 0, ulKeyBufferSize);  
aMsgPropVar[1].caub.pElems = (UCHAR*)pucKeyBuffer;  // Pointer to the new buffer  
aMsgPropVar[1].caub.cElems = ulKeySize;             // New buffer size  

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_DEST_SYMM_KEY_LEN
MSMQMessage.DestinationSymmetricKey