Peer Channel Message Authentication

  • Article

Download sample

This sample demonstrates using the NetPeerTcpBinding binding with message-based authentication, which provides multiparty communication using peer channel. This sample is a variation of the Getting Started Sample. Refer to Getting Started Sample for an overview of Windows Communication Foundation (WCF).

Note

The WCF samples may already be installed on your machine. Check this (default) directory before continuing: <InstallDrive>:\Samples\WCFWFCardspaceIf this directory doesn’t exist, click the download sample link at the top of this page. Note that this will download and install all of the WF, WCF, and CardSpace samples, you will only have to do this once. The sample is located in the following directory <InstallDrive>:\Samples\WCFWFCardSpace\WCF\Basic\Binding\Net\PeerTcp\Security\MessageAuthentication.

In this sample, the application instances are self-hosted console applications.

Unlike other transport binding samples, this sample uses the IQuoteChange contract interface for the purpose of illustrating multiparty communication. All instances implement this contract to receive messages and create proxies of the same contract to send messages to the mesh. This is demonstrated by creating a duplex channel to the mesh.

Note

The setup procedure and build instructions for this sample are located at the end of this topic.

Understanding the binding configuration process in the sample involves the following peer channel concepts:

  • The peer resolver is responsible for resolving a mesh ID to the endpoint addresses of a few nodes in the mesh.

  • A mesh is a named collection of peer nodes identified by the mesh ID.

  • A peer node is an instance of an application that participates in the mesh.

  • Mesh IDs identify the host portion of the address of an endpoint in the mesh. Examples of these addresses are "net.p2p://chatMesh/servicemodelsamples/chat" or "net.p2p://broadcastMesh/servicemodelsamples/announcements". chatMesh and broadcastMesh are the mesh IDs.

  • All clients that participate in a mesh use the same mesh ID, but can potentially use different paths and services. A message addressed to a specific endpoint address is delivered to all clients using that address.

When a peer node is opened, it uses a peer resolver to resolve the mesh ID to a list of addresses of other peer nodes in the mesh. This enables messages to be propagated throughout the mesh.

PeerTransportCredentialType specifies how peers in the mesh are authenticated with each other. This property can be specified either in the binding configuration, a NetPeerTcpBinding object or by using a PeerTransportBindingElement binding element. A ClientCredentialSettings (or ServiceCredentialSettings) instance with appropriate credentials specified on the Peer property must be added to the behavior collection on the channel factory or service host depending on the usage.

Peer channel supports the following authentication modes in the PeerTransportCredentialType class:

  1. Password. This is the default mode of authentication for peer channel. In this mode, all participants in the mesh are expected to prove knowledge of a secret password. This is accomplished by establishing a secure connection between neighbors and exchanging a transformation of this password. When Password is specified, the ClientCredentialSettings.Peer property must carry a valid password and optionally an X509Certificate2 instance (using SetSelfCertificate).

  2. Certificate. In this mode, application-specific authentication is performed when establishing peer connections. When this mode is specified, applications must specify a concrete implementation of X509Certificate2Validator in ClientCredentialSettings.Peer.PeerAuthentication that is added to the channel factory.

Applications can sign outgoing messages and validate incoming messages when the NetPeerTcpBinding.Security.Mode property is set to SecurityMode.Message or SecurityMode.TransportWithMessageCredential.

Signing of outgoing messages uses an instance of X509Certificate2 specified with ClientCredentialSettings.Peer.SetSelfCertificate().

Message signing is performed using an instance of X509Certificate2. For signing outgoing messages (in case of OutputChannel of DuplexChannel), application must specify the credential to use for signing using PeerCredential.SetSelfCertificate().

For verifying incoming messages (InputChannel or DuplexChannel), applications must specify a concrete implementation of X509Certificate2Validator that validates the source of the messages and is specified using ServiceCredentialSettings.Peer.MessageSenderAuthentication().

The binding is specified in the configuration files of the sender and the receivers. The binding type is specified in the endpoint element’s binding attribute as shown in the following sample.

<services>
    <service name="Microsoft.ServiceModel.Samples.BroadcastReceiver">
        <!-- use base address provided by the host -->
        <endpoint address="Stocks"
            binding="netPeerTcpBinding"
            bindingConfiguration="Binding1" 
            contract="Microsoft.ServiceModel.Samples.IQuoteChange" />
    </service>
</services>

If you use NetPeerTcpBinding binding with the default behavior, password-based security is enabled. The binding element provides attributes for setting port, listen IP address, resolver type, maximum message size, maximum buffer pool size, reader quotas, peer node authentication mode, message authentication, and timeouts (for close, open, send, and receive).

Note

This sample uses the default peer resolver (PNRP), which is not available in WCF. Therefore, to run this sample on WCF, you must use a custom peer resolver. Please refer to Peer Channel Chat for a sample that uses a custom peer resolver, for example.

<netPeerTcpBinding>
    <binding configurationName="Binding1"> 
        <resolver mode="Custom">
            <customResolver type=
                  "MyAppNameSpace.MyCustomPeerResolver, myApp"/>
        </resolver>
    </binding>
</netPeerTcpBinding>

The file that contains MyCustomPeerResolver must be compiled with the sender and the receivers. Note that if the sample is being run on multiple machines with different platforms, they should all use the same resolver.

The receiver and sender implementations also demonstrate how to retrieve the peer node associated with the receiver or sender instance and to register for its online and offline events. An online event is initiated when the peer node is connected to at least one other peer node in the mesh. An offline event is initiated when a peer node is no longer connected to any other peer node in the mesh.

At this time, the peer channel does not integrate with the Service Model Metadata Utility Tool (Svcutil.exe). For this reason, Svcutil.exe cannot be utilized to generate a typed channel for the sender.

When you run the sample, the sender displays a message that indicates it is ready to send messages. Enter values followed by ENTER to send the current stock value to the receiver clients. Updates are displayed in the other client console windows. To terminate the client, enter a blank value in the console windows of the sender (or press ENTER for a receiver client).

If you enable tracing or message logging, you can monitor the sender and receiver activity at a deeper level. The following procedure describes how to enable tracing and message logging.

Note

It is important to note that the sample currently does not handle all possible exceptions that the infrastructure may throw. If you are using these samples in a commercial/production environment, please follow the correct exception handling best practices.

To set up, build, and run the sample

  1. Ensure that you have performed the One-Time Set Up Procedure for the Windows Communication Foundation Samples.

  2. To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.

  3. To run the sample in a single machine configuration, follow the instructions in Running the Windows Communication Foundation Samples.

  4. To install PNRP on Windows XP SP2 (one-time setup):

    1. In the Control Panel, double-click Add or Remove Programs.

    2. In the Add or Remove Programs dialog box, click Add/Remove Windows Components.

    3. In the Windows Components Wizard, select the Networking Services check box and click Details.

    4. Check the Peer-to-Peer check box and click OK.

    5. Click Next in the Windows Components Wizard.

    6. When the installation completes, click Finish.

    7. From a command shell prompt, start the PNRP service with the following command: net start pnrpsvc.

  5. Wherever step 3 refers to client and service, those steps apply to sender and receiver.

  6. If running this sample for the first time, run Setup.bat to create and register certificates used by the sample. If using the sample across multiple machines, run Setup.bat on one machine only and export the generated certificate to all other machines being used. This is due to the fact that Setup.bat creates a random certificate, thus different runs of Setup.bat generate and register a unique certificate.

  7. Start the receiver (or multiple receivers) and the sender. When the instances connect, enter values in the console of the sender application to send updates to the receiver(s). Chat messages sent by sender are received by all receivers.

  8. Run Cleanup.bat to remove certificates created by this sample.

© 2007 Microsoft Corporation. All rights reserved.