Add documentation for getting started with the sample server-client a…

…pp (#3985)

Co-authored-by: Pooja Trivedi <poojatrivedi@microsoft.com>

README.md

@@ -60,6 +60,7 @@ MsQuic has several features that differentiates it from other QUIC implementatio
   * For building the library, see the [Build docs](./docs/BUILD.md).
   * For testing the library, see the [Testing docs](./docs/TEST.md).
   * For using the API, see the [API docs](./docs/API.md) or the [Sample](./src/tools/sample/sample.c).
+  * For running a sample server and client app, see the [Quick Start Guide](./docs/Sample.md).
   * For deploying QUIC, see the [Deployment docs](./docs/Deployment.md).
   * For diagnosing issues, see the [Diagnostics docs](./docs/Diagnostics.md) and the [Trouble Shooting Guide](./docs/TSG.md).
   * For other frequently asked questions, see the [FAQs](./docs/FAQ.md).

docs/Sample.md

@@ -0,0 +1,73 @@
+# Running Sample MsQuic Server and Client
+
+[Sample](../src/tools/sample/sample.c) provides a very simple MsQuic API sample server and client application.
+
+## Generate Self Signed Certificate
+A certificate needs to be available for the server to function. To generate a self-signed certificate, run
+
+### On Windows
+```Powershell
+New-SelfSignedCertificate -DnsName $env:computername,localhost -FriendlyName MsQuic-Test -KeyUsageProperty Sign -KeyUsage DigitalSignature -CertStoreLocation cert:\CurrentUser\My -HashAlgorithm SHA256 -Provider "Microsoft Software Key Storage Provider" -KeyExportPolicy Exportable
+```
+This works for both Schannel and OpenSSL TLS providers, assuming the KeyExportPolicy parameter is set to Exportable. The Thumbprint received from the command is then passed to the sample server at startup. Copy the thumbprint received.
+
+### On Linux
+```Powershell
+openssl req  -nodes -new -x509  -keyout server.key -out server.cert
+```
+This works with OpenSSL TLS Provider. It can also be used for Windows OpenSSL, however we recommend the certificate store method above for ease of use. Currently key files with password protections are not supported. With these files, they can be passed to the sample server with `-cert_file:path/to/server.cert` and `-key_file path/to/server.key` parameters.
+
+
+## Start the server
+Locate the quicsample.exe under your `artifacts/bin` directory under repo root. Start the server providing the thumbrint obtained in the previous step.
+
+```Powershell
+quicsample.exe -server -cert_hash:FAF9B176D64930D67C372CB456BAD38E7E5689F7
+```
+By default, the server listens on port 4567.
+
+## Start the client
+Start the client providing the IP address for the server. Here 127.0.0.1 is used as an example.
+
+```Powershell
+quicsample.exe -client -unsecure -target:{127.0.0.1}
+```
+
+## Console Output
+
+Here is what the console output looks like on the server and client sides after connection is established and data flows:
+
+### Server side
+```
+[conn][000001C32C29CC10] Connected
+[strm][000001C32C261000] Peer started
+[strm][000001C32C261000] Data received
+[strm][000001C32C261000] Peer shut down
+[strm][000001C32C261000] Sending data...
+[strm][000001C32C261000] Data sent
+[strm][000001C32C261000] All done
+[conn][000001C32C29CC10] Successfully shut down on idle.
+[conn][000001C32C29CC10] All done
+```
+
+### Client side
+```
+[conn][000001BE9F0C7000] Connecting...
+[conn][000001BE9F0C7000] Connected
+[strm][000001BE9F0CADF0] Starting...
+[strm][000001BE9F0CADF0] Sending data...
+[strm][000001BE9F0CADF0] Data sent
+[conn][000001BE9F0C7000] Resumption ticket received (56 bytes):
+01000000013100010243E8030245C00404810000000504800100000604800100000704800100000801010E0104C0000000FF03DE1A027E80
+[strm][000001BE9F0CADF0] Data received
+[strm][000001BE9F0CADF0] Peer shut down
+[strm][000001BE9F0CADF0] All done
+[conn][000001BE9F0C7000] Successfully shut down on idle.
+[conn][000001BE9F0C7000] All done
+```
+
+## Description
+
+The quicsample app implements a simple protocol (ALPN "sample") where the client connects to the server, opens a single bidirectional stream, sends some data and shuts down the stream in the send direction. On the server side all connections, streams and data are accepted. After the stream is shut down, the server then sends its own data and shuts down its send direction. The connection only shuts down when the 1 second idle timeout triggers.
+
+