DOCUMENT:Q280391  22-MAR-2002  [crossnet]
TITLE   :HOWTO: Send Digitally Signed Messages By Using CDOSYS/CDOEX
PRODUCT :Windows for Workgroups and Windows NT Networking Issues
PROD/VER::2000
OPER/SYS:
KEYWORDS:kbenv kbtool kbActMsg kbCDO kbMsg kbGrpDSMsg kbDSupport

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Exchange 2000 Server 
 - Microsoft Windows XP Professional 
 - Microsoft Windows XP Home Edition 
 - Microsoft Windows 2000 Server 
 - Microsoft Windows 2000 Professional 
-------------------------------------------------------------------------------

SUMMARY
=======

Microsoft Collaboration Data Objects for Windows 2000 (CDOSYS) and Microsoft
Collaboration Data Objects for Exchange 2000 (CDOEX) do not directly provide a
way to digitally sign or encrypt a message. The application programming
interface (API) does not expose any functionality to generate a valid signature.
However, you can use the Cryptography API in combination with CDOSYS or CDOEX to
digitally sign and/or encrypt a message.

MORE INFORMATION
================

You can use the COM version of the Cryptography API (CAPICOM) to easily sign
and/or encrypt CDOSYS or CDOEX messages. You can obtain the CAPICOM DLL from the
following Microsoft "Platform SDK Redistributable: CAPICOM 1.0A" Web site:

   http://www.microsoft.com/downloads/release.asp?releaseid=30316

Digitally Signing a Message
---------------------------

1. Start with a CDOSYS or CDOEX IMessage object. Configure this message with
   sender, recipient, subject, body, attachments, and any other necessary items.

2. Create a new IMessage object. Open the existing message from step 1 by using
   this new message's IDatasource::OpenObject method.

3. Get the new IMessage object's IBodyPart root, and then set the following
   properties:

   oBodyPart.ContentMediaType = "application/pkcs7-mime;smime-type=signed-data;name=""smime.p7m"""
   oBodyPart.ContentTransferEncoding = "base64"
   oBodyPart.Fields("urn:schemas:mailheader:content-disposition") = "attachment;FileName=""smime.p7m"""
   oBodyPart.Fields.Update

4. Use the CAPICOM Signer object and the sender's certificate to sign the
   content of the new IMessage object.

5. Send the new message, and then discard the original message.

Encrypting a Message
--------------------

1. Start with a CDOSYS or CDOEX IMessage object. Configure this message with
   sender, recipient, subject, body, attachments, and any other necessary items.

2. Create a new IMessage object. Open the existing message from step 1 by using
   this new message's IDatasource::OpenObject method.

3. Get the new IMessage object's IBodyPart root, and then set the following
   properties:

   oBodyPart.ContentMediaType = "application/pkcs7-mime;smime-type=enveloped-data;name=smime.p7m;"
   oBodyPart.ContentTransferEncoding = "base64"
   oBodyPart.Fields("urn:schemas:mailheader:content-disposition") = "attachment;FileName=""smime.p7m"""
   oBodyPart.Fields.Update

4. Use the CAPICOM EnvelopedData object and the recipient's certificate to
   encrypt the content of the new IMessage object.

5. Send the new message, and discard the original.

Digitally Signing and Encrypting a Message
------------------------------------------

The steps are the same, but the order is important. You must first sign the
message, and then encrypt the message.

Sample Code
-----------

Notes About the Sample Code:

 - The sample calls two non-existent functions, GetCertForSignature and
   GetCertForEnvelope. The programmer must obtain the appropriate certificate.
 - The sample code requires references to the CAPICOM 1.0 Type Library, the
   Microsoft ActiveX Data Objects 2.5 Library, and the appropriate CDO Library.

   '******************************************************************
   '
   ' SignMessage
   '
   ' Takes oMsg as input (non-secure message) and returns a new
   ' message that is digitally signed.
   '
   '******************************************************************
   Public Function SignMessage(oMsg As CDO.Message) As CDO.Message
       Dim oSecMsg As New CDO.Message
       Dim oBodyPart As CDO.IBodyPart
       Dim oSignedData As New CAPICOM.SignedData
       Dim strData As String
       Dim strContent As String
       Dim oStream As ADODB.Stream
       Dim oSigner As New CAPICOM.Signer
       Dim oCert As CAPICOM.Certificate
       Dim oAttr As New CAPICOM.Attribute
       Dim byteData() As Byte
       
       On Error GoTo handle_error
       
       ' Copy input into output message
       oSecMsg.DataSource.OpenObject oMsg, cdoIMessage
       
       ' Set up main bodypart
       Set oBodyPart = oSecMsg.BodyPart
       oBodyPart.ContentMediaType = "application/pkcs7-mime;smime-type=signed-data;name=""smime.p7m"""
       oBodyPart.ContentTransferEncoding = "base64"
       oBodyPart.Fields("urn:schemas:mailheader:content-disposition") = "attachment;FileName=""smime.p7m"""
       oBodyPart.Fields.Update
               
       ' Get certificate
       Set oCert = GetCertForSignature(oSecMsg.From)
       
       ' If no cert, throw an error and exit
       If oCert Is Nothing Then
           MsgBox "No valid certificate found for sender.", , "Error"
           Set SignMessage = Nothing
       End If
       
       ' Add cert to signer object
       oSigner.Certificate = oCert
       
       ' Add signing time attribute to signer object
       oAttr.Name = CAPICOM_AUTHENTICATED_ATTRIBUTE_SIGNING_TIME
       oAttr.Value = Now
       oSigner.AuthenticatedAttributes.Add oAttr

       ' Sign the content (root bodypart)
       strContent = oMsg.BodyPart.GetStream.ReadText
       oSignedData.Content = StrConv(strContent, vbFromUnicode)

       strData = oSignedData.Sign(oSigner, False, CAPICOM_ENCODE_BINARY)

       ' Write the cms blob into the main bodypart
       ' let CDO do the base64 encoding
       Set oStream = oSecMsg.BodyPart.GetDecodedContentStream
       
       oStream.Type = adTypeBinary

       ' Get the string data as a byte array
       byteData = strData
       
       ' Write the data to the stream and flush it
       oStream.Write byteData
       oStream.Flush
       
       GoTo cleanup
       
       ' Report error
   handle_error:
       MsgBox Err.Number & ": " & Err.Description, , "Error:"
       Set oSecMsg = Nothing
       
       ' Clean up memory
   cleanup:
       Set oBodyPart = Nothing
       Set oSignedData = Nothing
       Set oStream = Nothing
       Set oSigner = Nothing
       Set oCert = Nothing
       Set oAttr = Nothing
       
       ' Return new message
       Set SignMessage = oSecMsg
   End Function

   '******************************************************************
   '
   ' EnvelopeMessage
   '
   ' Takes oMsg as input (non-secure message) and returns a new
   ' message that is enveloped.
   '
   '******************************************************************
   Public Function EnvelopeMessage(oMsg As CDO.Message, iCertStore As Integer, Optional strQuery As String) As CDO.Message
       Dim oSecMsg As New CDO.Message
       Dim oBodyPart As CDO.IBodyPart
       Dim oEnvelopedData As New CAPICOM.EnvelopedData
       Dim oCert As CAPICOM.Certificate
       Dim oStream As ADODB.Stream
       Dim strData As String
       Dim strContent As String
       Dim byteData() As Byte
       
       ' Copy input into output message
       oSecMsg.DataSource.OpenObject oMsg, cdoIMessage
       
       ' Set up main bodypart
       Set oBodyPart = oSecMsg.BodyPart
       oBodyPart.ContentMediaType = "application/pkcs7-mime;smime-type=enveloped-data;name=smime.p7m;"
       oBodyPart.ContentTransferEncoding = "base64"
       oBodyPart.Fields("urn:schemas:mailheader:content-disposition") = "attachment;FileName=""smime.p7m"""
       oBodyPart.Fields.Update
       
       ' Get recipient's cert
       If strQuery = "" Then
           Set oCert = GetCertForEnvelope(oSecMsg.To, iCertStore)
       Else
           Set oCert = GetCertForEnvelope(oSecMsg.To, iCertStore, strQuery)
       End If
       
       oEnvelopedData.Recipients.Add oCert
       
       ' Encrypt content
       strContent = oMsg.BodyPart.GetStream.ReadText
       oEnvelopedData.Content = StrConv(strContent, vbFromUnicode)
       strData = oEnvelopedData.Encrypt(CAPICOM_ENCODE_BINARY)
       
       ' Write the CMS blob into the main bodypart
       ' let CDO do the base64 encoding
       Set oStream = oSecMsg.BodyPart.GetDecodedContentStream
       
       oStream.Type = adTypeBinary
       
       ' Get the string data as a byte array
       byteData = strData
       
       ' Write the data to the stream and flush it
       oStream.Write byteData
       oStream.Flush
       
       GoTo cleanup
       
   handle_error:
       MsgBox Err.Number & ": " & Err.Description, , "Error:"
       Set oSecMsg = Nothing
       
       ' Clean up memory
   cleanup:
       Set oBodyPart = Nothing
       Set oEnvelopedData = Nothing
       Set oStream = Nothing
       Set oCert = Nothing
       
       ' Return new message
       Set EnvelopeMessage = oSecMsg
   End Function

Additional query words:

======================================================================
Keywords          : kbenv kbtool kbActMsg kbCDO kbMsg kbGrpDSMsg kbDSupport 
Technology        : kbOSWin2000 kbOSWinSearch kbExchangeSearch kbOSWinXP kbExchange2000Search kbExchange2000Serv kbOSWinXPSearch
Version           : :2000
Issue type        : kbhowto

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 2002.