Peer Channel Custom Authentication

Download sample

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

In this sample, all instances are self-hosted console applications; there is no concept of client and server.

Unlike other transport binding samples, this sample uses the IChat 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.

PeerChannel is a multiparty, peer-to-peer (P2P) communication technology in WCF. It enables secure, scalable, and reliable messaging. One common example of a multiparty application that can benefit from the peer channel is collaborative applications such as chat where a group of people chat with one other in a peer-to-peer manner without requiring servers. PeerChannel enables both consumer and enterprise scenarios around P2P collaboration, content distribution, load balancing, and distributed processing.

PeerChannel introduces the following new concepts:

• A mesh is a named collection (an interconnected graph) of peer nodes that can communicate among themselves and that are identified by a unique mesh ID.

  Note:
  Active nodes in the mesh publish their mesh name, so others can find them. A mesh has the following characteristics:  It automatically adjusts when nodes join and leave the mesh, ensuring that all nodes have good connectivity to the mesh, and that the connections are dynamically optimized based on the current traffic patterns.

• A peer node is an endpoint in a mesh. An application can have multiple peer nodes participating in different meshes.

• A peer resolver is responsible for resolving a mesh ID to the endpoint addresses of a few nodes in the mesh. A peer node uses these addresses to connect to other 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, in the NetPeerTcpBinding object, or by using PeerTransportBindingElement. 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 ServiceHost depending on the usage.

PeerChannel supports the following authentication modes in the PeerTransportCredentialType class:

1. Password. This is the default mode of authentication for PeerChannel. 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, application must specify a concrete implementation of X509Certificate2Validator in ClientCredentialSettings.Peer.PeerAuthentication that is added to the channel factory.

The binding is specified in the configuration file of the client. The binding type is specified in the endpoint element’s binding attribute as shown in the following sample.

<client>
  <!-- chat instance participating in the mesh -->
  <endpoint name="ChatEndpoint"
            address="net.p2p://SecurechatMesh/servicemodelsamples/chat"
            binding="netPeerTcpBinding"
            bindingConfiguration="MyBinding"
            contract="Microsoft.ServiceModel.Samples.IChat">
  </endpoint>
</client>

If you use the 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, authentication mode, message authentication, and timeouts (close, open, send, and receive).

Note: This sample uses the default peer resolver (PNRP), which is not available in Windows Server 2003. Therefore, to run this sample onWindows Server 2003, 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 chat instances. Note that if the sample is being run on multiple machines with different platforms, they should all use the same resolver.

This sample also demonstrates 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 fired when the peer node is connected to at least one other peer node in the mesh. An offline event is fired when a peer node is no longer connected to any other peer node in the mesh.

At this time, PeerChannel is not integrated with the Service Metadata Utility (Svcutil.exe).

When the sample is run, the client will display a message indicating it is ready to send messages. Messages sent by one client will appear on the console windows of all other clients joined to the same mesh. To terminate the client, press the Q key, then ENTER in the console windows of a client.

If you enable tracing or message logging, you can monitor message activity at a deeper level. The Procedures section 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 Setup 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 separate instances of the application.

6. If running this sample on a machine for the first time, run setup.bat to create a certificate issuing authority and two client certificates. The default name for the issuing authority is "TrustedPeerChannelIssuer" and "peer1" and "peer2" for the client certificates. Names may be optionally specified by passing arguments to setup.bat as follows: "setup.bat <peername> <issuername>", where <peername> is a prefix name of the clients and issuername is the name of the sample trusted issuer. (For example, entering "setup.bat peer fake_issuer" creates an trusted issuer called "fake_issuer" and client certificates named "peer1" and "peer2".) If running all instances of the sample on a single machine, please continue to step 7.

7. Additional Steps for a Multi-Machine Setup: To run the sample on different machines, certificate information must be copied from a single machine to all other machines running the sample, so that issuer information is consistent across all peers. This can be accomplished by exporting client certificates created using the trusted issuer (generated by setup.bat). The trusted issuer (TrustedPeerChannelIssuer.cer if the default name is used) must also be copied to all other client machines running the sample. Follow the following three steps:

   1. Transferring the Trusted Issuer: Copy the .cer file (generated by running setup.bat in the same folder) to the client machine. Right click the file and select "Install certificate." Press "next", and then select "Place all certificates in the following store." Press "Browse" and choose "Trusted People" as the destination for the certificate. Select "next" and "finish" to finish importing the certificate.

   2. Exporting Client Certificate: Start by running "certmgr.msc" on the machine used to generated the client certificates. Select the client certificate from the personal store (Under "Certificates - Current User" -> "Personal" -> "Certificates"). Right-click the certificate and select "All Tasks" -> "Export…" to start the Certificate Export Wizard. Press "Next", select "Yes, export the private key", and press "Next". Select "Next" again to choose the .PFX format and default values. Enter a password for the certificates and click "Next" again. Finally, choose a path and file name and click "Next" and "Finish" to complete the export process.

   3. Importing Client Certificate: Copy the .pfx file created by step (b) to the client machine. Right click the file and select "Install PFX." Press "next" twice, and then enter the password used to export the certificate. Press "Next" and "Finish" to place the certificate in the personal store.

   4. NOTE: Creating a trusted issuer and exporting it via file transfer may pose certain security risks if the file is distributed inappropriately. Be sure to clean sample certificates after running the sample (step 8).

8. Run as many instances of the application as desired. Messages sent by one instance are received by the others. Each instance will have the default name of "peer1". To distinguish between specific instances, change the value of the "member" key in appSettings in the application's config file, and create a client certificate with the same name.

9. Finally, run Cleanup.bat to remove certificates created by this sample. If non default names are used, run "Cleanup.bat <peername> <issuername>" with the same values used in step 6.

Send comments about this topic to Microsoft.
© Microsoft Corporation. All rights reserved.