Add Orleans Transport Layer Security (TLS) documentation

docs/orleans/host/snippets/transport-layer-security/.gitignore

@@ -0,0 +1,2 @@
+bin/
+obj/

docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/ClientExample.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Orleans.Client" Version="9.2.1" />
+    <PackageReference Include="Microsoft.Orleans.Connections.Security" Version="9.2.1" />
+  </ItemGroup>
+
+</Project>

docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs

@@ -0,0 +1,89 @@
+using System.Security.Authentication;
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Orleans.Connections.Security;
+using Orleans.Hosting;
+
+// <BasicClientTlsConfiguration>
+using IHost host = Host.CreateDefaultBuilder(args)
+    .UseOrleansClient(builder =>
+    {
+        builder
+            .UseLocalhostClustering()
+            .UseTls(StoreName.My, "my-certificate-subject", allowInvalid: false, StoreLocation.CurrentUser, options =>
+            {
+                options.OnAuthenticateAsServer = (connection, sslOptions) =>
+                {
+                    sslOptions.ClientCertificateRequired = true;
+                };
+            });
+    })
+    .ConfigureLogging(logging => logging.AddConsole())
+    .Build();
+
+await host.RunAsync();
+// </BasicClientTlsConfiguration>
+
+class ClientDevelopmentExample
+{
+    public static async Task ConfigureDevelopmentTls()
+    {
+        // <ClientDevelopmentTlsConfiguration>
+        var hostBuilder = Host.CreateDefaultBuilder();
+
+        using IHost host = hostBuilder
+            .UseOrleansClient((context, builder) =>
+            {
+                var isDevelopment = context.HostingEnvironment.IsDevelopment();
+
+                builder
+                    .UseLocalhostClustering()
+                    .UseTls(StoreName.My, "localhost", allowInvalid: isDevelopment, StoreLocation.CurrentUser, options =>
+                    {
+                        if (isDevelopment)
+                        {
+                            options.AllowAnyRemoteCertificate();
+                        }
+
+                        options.OnAuthenticateAsServer = (connection, sslOptions) =>
+                        {
+                            sslOptions.ClientCertificateRequired = true;
+                        };
+                    });
+            })
+            .ConfigureLogging(logging => logging.AddConsole())
+            .Build();
+
+        await host.RunAsync();
+        // </ClientDevelopmentTlsConfiguration>
+    }
+}
+
+class ClientCertificateExample
+{
+    public static async Task ConfigureTlsWithCertificate()
+    {
+        // <ClientCertificateTlsConfiguration>
+        using var cert = X509CertificateLoader.LoadPkcs12FromFile("path/to/certificate.pfx", "password");
+
+        using IHost host = Host.CreateDefaultBuilder()
+            .UseOrleansClient(builder =>
+            {
+                builder
+                    .UseLocalhostClustering()
+                    .UseTls(cert, options =>
+                    {
+                        options.OnAuthenticateAsServer = (connection, sslOptions) =>
+                        {
+                            sslOptions.ClientCertificateRequired = true;
+                        };
+                    });
+            })
+            .ConfigureLogging(logging => logging.AddConsole())
+            .Build();
+
+        await host.RunAsync();
+        // </ClientCertificateTlsConfiguration>
+    }
+}

docs/orleans/host/snippets/transport-layer-security/csharp/README.md

@@ -0,0 +1,27 @@
+# Transport Layer Security (TLS) Code Samples
+
+This directory contains code samples demonstrating how to configure Transport Layer Security (TLS) in Orleans applications.
+
+## Projects
+
+- **SiloExample**: Demonstrates TLS configuration for Orleans silos
+- **ClientExample**: Demonstrates TLS configuration for Orleans clients
+
+## Building the Samples
+
+To build all samples:
+
+```bash
+dotnet build transport-layer-security.sln
+```
+
+To build individual projects:
+
+```bash
+dotnet build SiloExample/SiloExample.csproj
+dotnet build ClientExample/ClientExample.csproj
+```
+
+## Note
+
+These samples are intended for documentation purposes and demonstrate various TLS configuration scenarios including basic setup, development environments, certificate files, and advanced configurations.

docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs

@@ -0,0 +1,137 @@
+using System.Net;
+using System.Net.Security;
+using System.Security.Authentication;
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Orleans.Connections.Security;
+using Orleans.Hosting;
+
+// <BasicTlsConfiguration>
+using IHost host = Host.CreateDefaultBuilder(args)
+    .UseOrleans(builder =>
+    {
+        builder
+            .UseLocalhostClustering()
+            .UseTls(StoreName.My, "my-certificate-subject", allowInvalid: false, StoreLocation.CurrentUser, options =>
+            {
+                options.OnAuthenticateAsClient = (connection, sslOptions) =>
+                {
+                    sslOptions.TargetHost = "my-certificate-subject";
+                };
+            });
+    })
+    .ConfigureLogging(logging => logging.AddConsole())
+    .Build();
+
+await host.RunAsync();
+// </BasicTlsConfiguration>
+
+class DevelopmentExample
+{
+    public static async Task ConfigureDevelopmentTls()
+    {
+        // <DevelopmentTlsConfiguration>
+        var hostBuilder = Host.CreateDefaultBuilder();
+
+        using IHost host = hostBuilder
+            .UseOrleans((context, builder) =>
+            {
+                var isDevelopment = context.HostingEnvironment.IsDevelopment();
+
+                builder
+                    .UseLocalhostClustering()
+                    .UseTls(StoreName.My, "localhost", allowInvalid: isDevelopment, StoreLocation.CurrentUser, options =>
+                    {
+                        options.OnAuthenticateAsClient = (connection, sslOptions) =>
+                        {
+                            sslOptions.TargetHost = "localhost";
+                        };
+
+                        if (isDevelopment)
+                        {
+                            options.AllowAnyRemoteCertificate();
+                        }
+                    });
+            })
+            .ConfigureLogging(logging => logging.AddConsole())
+            .Build();
+
+        await host.RunAsync();
+        // </DevelopmentTlsConfiguration>
+    }
+}
+
+class CertificateExample
+{
+    public static async Task ConfigureTlsWithCertificate()
+    {
+        // <CertificateTlsConfiguration>
+        using var cert = X509CertificateLoader.LoadPkcs12FromFile("path/to/certificate.pfx", "password");
+
+        using IHost host = Host.CreateDefaultBuilder()
+            .UseOrleans(builder =>
+            {
+                builder
+                    .UseLocalhostClustering()
+                    .UseTls(cert, options =>
+                    {
+                        options.OnAuthenticateAsClient = (connection, sslOptions) =>
+                        {
+                            sslOptions.TargetHost = cert.GetNameInfo(X509NameType.DnsName, false);
+                        };
+                    });
+            })
+            .ConfigureLogging(logging => logging.AddConsole())
+            .Build();
+
+        await host.RunAsync();
+        // </CertificateTlsConfiguration>
+    }
+}
+
+class AdvancedExample
+{
+    public static async Task ConfigureAdvancedTls()
+    {
+        // <AdvancedTlsConfiguration>
+        using IHost host = Host.CreateDefaultBuilder()
+            .UseOrleans(builder =>
+            {
+                builder
+                    .UseLocalhostClustering()
+                    .UseTls(StoreName.My, "my-certificate-subject", allowInvalid: false, StoreLocation.LocalMachine, options =>
+                    {
+                        options.LocalServerCertificateSelector = (sender, serverName) =>
+                        {
+                            using var store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
+                            store.Open(OpenFlags.ReadOnly);
+                            var certs = store.Certificates.Find(X509FindType.FindBySubjectName, serverName ?? "my-certificate-subject", validOnly: true);
+                            return certs.Count > 0 ? certs[0] : null;
+                        };
+
+                        options.RemoteCertificateValidation = (certificate, chain, sslPolicyErrors) =>
+                        {
+                            if (sslPolicyErrors == SslPolicyErrors.None)
+                            {
+                                return true;
+                            }
+
+                            return false;
+                        };
+
+                        options.OnAuthenticateAsClient = (connection, sslOptions) =>
+                        {
+                            sslOptions.TargetHost = "my-certificate-subject";
+                        };
+
+                        options.CheckCertificateRevocation = true;
+                    });
+            })
+            .ConfigureLogging(logging => logging.AddConsole())
+            .Build();
+
+        await host.RunAsync();
+        // </AdvancedTlsConfiguration>
+    }
+}

docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/SiloExample.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Orleans.Connections.Security" Version="9.2.1" />
+    <PackageReference Include="Microsoft.Orleans.Server" Version="9.2.1" />
+  </ItemGroup>
+
+</Project>

docs/orleans/host/snippets/transport-layer-security/csharp/transport-layer-security.sln

@@ -0,0 +1,48 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SiloExample", "SiloExample\SiloExample.csproj", "{FEC1D74E-6879-4473-8D45-A846339B8063}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ClientExample", "ClientExample\ClientExample.csproj", "{72192298-953F-4F4E-976D-A2C38A6175CC}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Debug|x64 = Debug|x64
+		Debug|x86 = Debug|x86
+		Release|Any CPU = Release|Any CPU
+		Release|x64 = Release|x64
+		Release|x86 = Release|x86
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x64.Build.0 = Debug|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x86.Build.0 = Debug|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Release|Any CPU.Build.0 = Release|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x64.ActiveCfg = Release|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x64.Build.0 = Release|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x86.ActiveCfg = Release|Any CPU
+		{FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x86.Build.0 = Release|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x64.Build.0 = Debug|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x86.Build.0 = Debug|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x64.ActiveCfg = Release|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x64.Build.0 = Release|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x86.ActiveCfg = Release|Any CPU
+		{72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x86.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal