SecureSign(X509Certificate2,X509IncludeOption,DigestAlgorithm,Boolean,Boolean) Method

Sign the MailMessage using S/MIME encoding.

Syntax

Visual Basic (Declaration)
Visual Basic (Usage)
C#
Managed Extensions for C++
C++/CLI

Public Overloads Function SecureSign( _
   ByVal signingCertificate As X509Certificate2, _
   ByVal includeOption As X509IncludeOption, _
   ByVal digestAlgorithm As DigestAlgorithm, _
   ByVal detached As Boolean, _
   ByVal includeHeaders As Boolean _
) As X509Certificate2Collection

Dim instance As MailMessage
Dim signingCertificate As X509Certificate2
Dim includeOption As X509IncludeOption
Dim digestAlgorithm As DigestAlgorithm
Dim detached As Boolean
Dim includeHeaders As Boolean
Dim value As X509Certificate2Collection
 
value = instance.SecureSign(signingCertificate, includeOption, digestAlgorithm, detached, includeHeaders)

public X509Certificate2Collection SecureSign( 
   X509Certificate2 signingCertificate,
   X509IncludeOption includeOption,
   DigestAlgorithm digestAlgorithm,
   bool detached,
   bool includeHeaders
)

public: X509Certificate2Collection* SecureSign( 
   X509Certificate2* signingCertificate,
   X509IncludeOption includeOption,
   DigestAlgorithm digestAlgorithm,
   bool detached,
   bool includeHeaders
)

public:
X509Certificate2Collection^ SecureSign( 
   X509Certificate2^ signingCertificate,
   X509IncludeOption includeOption,
   DigestAlgorithm digestAlgorithm,
   bool detached,
   bool includeHeaders
)

Parameters

signingCertificate: Certificate to use to sign the MailMessage. If null, From is used to get a certificate from the "MY" certificate store.
includeOption: Specifies what certificates in the certificate chain should be included.
digestAlgorithm: DigestAlgorithm to use to verify the message has not been changed.
detached: If true, creates a "multipart/signed" message using a detached digital signature; otherwise an "application/pkcs7-mime" message is created using signed-data.
includeHeaders: If true and detached is false, message header fields are protected by moving them into the signed payload.

Return Value

System.Security.Cryptography.X509Certificates.X509Certificate2Collection containing the certificates included within the signed message.

Exceptions

Exception	Description
System.InvalidOperationException	Signing certificate matching From address not found.

Remarks

Recipients of a signed message will typically add the signing certificate to its "AddressBook" certificate store so it can be subsequently used to perform S/MIME encryption on messages sent to that address. Signing certificates contain the public key necessary for encryption.

If detached is true, then the message contents are provided in the clear as the first part (Parts[0]), and the digital signature is provided as the second part (Parts[1] of type Attachment). In a multipart message, a multipart MIME entity is used to aggregate the parts as Parts[0] (this occurs automatically). Most non-S/MIME readers will therefore be able to display the content, while S/MIME readers will be able to use the digital signature to check for message tampering. If detached is false, then the message contents is combined with the digital signature into a single part (Parts[0]) which cannot be displayed by non-S/MIME readers. Typically, if only signing is used then detached signing is preferred for compatibility. If standard signing AND encryption is desired, then first use this method with detached false and then use SecureEncrypt.

If includeHeaders is false, the content is encrypted and the message headers are unchanged except for ContentType. If true, the entire message is encrypted and will be restored by the reader during decryption (this was introduced in version 3.1 and is not backwards compatible). In this case, sensitive header fields like Subject:, To:, From: and CC: may be removed after signing. Note, however, that mail addresses MUST be included in Smtp.Send() if they are removed them from the message.

Complies with S/MIME version 3.2 RFCs (5751, 5652, 5035 and 2634) that are generally backwards compatible with version 2, 3,0 and 3.1.

Example

This example demonstrates signing a message with the sender's digitial signature.

using System.Security.Cryptography.X509Certificates;

private MailMessage getSignedMessage(MailMessage message)
{
    //Find the signing certificate in the "CurrentUser/My" certificate store
    //The following code results in the same signed message as "message.SecureSign();"
    X509Store myPersonalStore = new X509Store(StoreName.My, StoreLocation.CurrentUser);
    myPersonalStore.Open(OpenFlags.ReadOnly);
    foreach (X509Certificate2 certificate in myPersonalStore.Certificates)
    {
        if (certificate.Subject.Contains("E=" + message.From.ToString()))
        {
            //Sign the message
            message.SecureSign(certificate, X509IncludeOption.ExcludeRoot, DigestAlgorithm.Sha1, true, false);
            return message;
        }
    }
    return null;
}

Visual Basic

Imports System.Security.Cryptography.X509Certificates

Private Function getSignedMessage(ByVal message As MailMessage) As MailMessage
    'Find the signing certificate in the "CurrentUser/My" certificate store
    'The following code results in the same signed message as "message.SecureSign();"
    Dim myPersonalStore As New X509Store(StoreName.My, StoreLocation.CurrentUser)
    myPersonalStore.Open(OpenFlags.ReadOnly)
    For Each certificate As X509Certificate2 In myPersonalStore.Certificates
        If certificate.Subject.Contains("E=" & message.From.ToString()) Then
            'Sign the message
            message.SecureSign(certificate, X509IncludeOption.ExcludeRoot, DigestAlgorithm.Sha1, True, False)
            Return message
        End If
    Next certificate
    Return Nothing
End Function

Reference

MailMessage Class
MailMessage Members
Overload List