| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Configures HTTPS options for a Kestrun server instance. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | This function allows administrators to set or modify the HTTPS connection adapter options for a Kestrun |
| | | 6 | | server instance, including SSL protocols, client certificate modes, and server certificates. |
| | | 7 | | .PARAMETER Server |
| | | 8 | | The Kestrun server instance to configure. This parameter is mandatory and must be a valid server object. |
| | | 9 | | .PARAMETER Options |
| | | 10 | | The HttpsConnectionAdapterOptions object containing the desired HTTPS configuration settings. |
| | | 11 | | .PARAMETER SslProtocols |
| | | 12 | | Specifies the SSL protocols to be used for HTTPS connections. This parameter is optional and can be set to a specifi |
| | | 13 | | .PARAMETER ClientCertificateMode |
| | | 14 | | Specifies the client certificate mode for HTTPS connections. This parameter is optional and can be set to a specific |
| | | 15 | | .PARAMETER ClientCertificateValidation |
| | | 16 | | A .NET delegate invoked by Kestrel during the TLS handshake to validate the presented client certificate. |
| | | 17 | | The delegate signature is: |
| | | 18 | | Func[X509Certificate2, X509Chain, SslPolicyErrors, bool]. |
| | | 19 | | Note: This delegate runs on Kestrel TLS threads (no PowerShell runspace), so it must be pure .NET, fast, and thread- |
| | | 20 | | .PARAMETER ClientCertificateValidationCode |
| | | 21 | | A C# or VB.NET method-body snippet that will be compiled with Roslyn into the TLS client certificate validation dele |
| | | 22 | | The generated method signature is: |
| | | 23 | | bool Validate(X509Certificate2 certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors) |
| | | 24 | | .PARAMETER ClientCertificateValidationCodePath |
| | | 25 | | Path to a .cs/.csx or .vb file containing a method-body snippet that will be compiled with Roslyn into the TLS clien |
| | | 26 | | The language is inferred from the file extension. |
| | | 27 | | .PARAMETER ClientCertificateValidationLanguage |
| | | 28 | | The language used for -ClientCertificateValidationCode. Valid values are CSharp and VBNet. |
| | | 29 | | .PARAMETER CheckCertificateRevocation |
| | | 30 | | If specified, enables certificate revocation checking for HTTPS connections. This parameter is optional and can be l |
| | | 31 | | .PARAMETER ServerCertificate |
| | | 32 | | Specifies the server certificate to be used for HTTPS connections. This parameter is optional and can be left unset |
| | | 33 | | .PARAMETER ServerCertificateChain |
| | | 34 | | Specifies the server certificate chain to be used for HTTPS connections. This parameter is optional and can be left |
| | | 35 | | .PARAMETER HandshakeTimeout |
| | | 36 | | Specifies the handshake timeout duration in seconds for HTTPS connections. This parameter is optional and can be lef |
| | | 37 | | .PARAMETER PassThru |
| | | 38 | | If specified, the cmdlet will return the modified server instance after applying the HTTPS options. |
| | | 39 | | .OUTPUTS |
| | | 40 | | [Kestrun.Hosting.KestrunHost] |
| | | 41 | | The modified Kestrun server instance with the applied HTTPS options. |
| | | 42 | | .EXAMPLE |
| | | 43 | | Set-KrServerHttpsOptions -Server $server -SslProtocols Tls12 |
| | | 44 | | This command sets the SSL protocols for the specified Kestrun server instance to use TLS 1.2. |
| | | 45 | | .EXAMPLE |
| | | 46 | | Set-KrServerHttpsOptions -Server $server -ClientCertificateMode RequireCertificate |
| | | 47 | | This command sets the client certificate mode for the specified Kestrun server instance to require a client certific |
| | | 48 | | .EXAMPLE |
| | | 49 | | Set-KrServerHttpsOptions -Server $server -CheckCertificateRevocation |
| | | 50 | | This command enables certificate revocation checking for the specified Kestrun server instance. |
| | | 51 | | .EXAMPLE |
| | | 52 | | Set-KrServerHttpsOptions -Server $server -ServerCertificate $cert |
| | | 53 | | This command sets the server certificate for the specified Kestrun server instance. |
| | | 54 | | .EXAMPLE |
| | | 55 | | Set-KrServerHttpsOptions -Server $server -HandshakeTimeout 30 |
| | | 56 | | This command sets the handshake timeout for the specified Kestrun server instance to 30 seconds. |
| | | 57 | | .NOTES |
| | | 58 | | This function is designed to be used in the context of a Kestrun server setup and allows for flexible configuration |
| | | 59 | | TLS callbacks (like client certificate validation) execute during the TLS handshake and must not rely on PowerShell |
| | | 60 | | #> |
| | | 61 | | function Set-KrServerHttpsOptions { |
| | | 62 | | [KestrunRuntimeApi('Definition')] |
| | | 63 | | [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')] |
| | | 64 | | [CmdletBinding(defaultParameterSetName = 'Items')] |
| | | 65 | | param( |
| | | 66 | | [Parameter(Mandatory = $false, ValueFromPipeline = $true)] |
| | | 67 | | [Kestrun.Hosting.KestrunHost]$Server, |
| | | 68 | | [Parameter(Mandatory = $true, ParameterSetName = 'Options')] |
| | | 69 | | [Microsoft.AspNetCore.Server.Kestrel.Https.HttpsConnectionAdapterOptions]$Options, |
| | | 70 | | [Parameter( ParameterSetName = 'Items')] |
| | | 71 | | [System.Security.Authentication.SslProtocols]$SslProtocols, |
| | | 72 | | |
| | | 73 | | [Parameter(ParameterSetName = 'Items')] |
| | | 74 | | [ValidateNotNullOrEmpty()] |
| | | 75 | | [string]$ClientCertificateValidationCode, |
| | | 76 | | |
| | | 77 | | [Parameter(ParameterSetName = 'Items')] |
| | | 78 | | [ValidateNotNullOrEmpty()] |
| | | 79 | | [string]$ClientCertificateValidationCodePath, |
| | | 80 | | |
| | | 81 | | [Parameter(ParameterSetName = 'Items')] |
| | | 82 | | [ValidateNotNullOrEmpty()] |
| | | 83 | | [ValidateSet('CSharp', 'VBNet')] |
| | | 84 | | [string]$ClientCertificateValidationLanguage = 'CSharp', |
| | | 85 | | [Parameter( ParameterSetName = 'Items')] |
| | | 86 | | [Microsoft.AspNetCore.Server.Kestrel.Https.ClientCertificateMode]$ClientCertificateMode, |
| | | 87 | | [Parameter( ParameterSetName = 'Items')] |
| | | 88 | | [System.Func[ |
| | | 89 | | System.Security.Cryptography.X509Certificates.X509Certificate2, |
| | | 90 | | System.Security.Cryptography.X509Certificates.X509Chain, |
| | | 91 | | System.Net.Security.SslPolicyErrors, |
| | | 92 | | bool |
| | | 93 | | ]]$ClientCertificateValidation, |
| | | 94 | | [Parameter( ParameterSetName = 'Items')] |
| | | 95 | | [switch]$CheckCertificateRevocation, |
| | | 96 | | [Parameter( ParameterSetName = 'Items')] |
| | | 97 | | [System.Security.Cryptography.X509Certificates.X509Certificate2]$ServerCertificate, |
| | | 98 | | [Parameter( ParameterSetName = 'Items')] |
| | | 99 | | [System.Security.Cryptography.X509Certificates.X509Certificate2Collection]$ServerCertificateChain, |
| | | 100 | | [Parameter( ParameterSetName = 'Items')] |
| | | 101 | | [int]$HandshakeTimeout, |
| | | 102 | | [Parameter()] |
| | | 103 | | [switch]$PassThru |
| | | 104 | | ) |
| | | 105 | | begin { |
| | | 106 | | # Ensure the server instance is resolved |
| | 1 | 107 | | $Server = Resolve-KestrunServer -Server $Server |
| | | 108 | | } |
| | | 109 | | process { |
| | | 110 | | |
| | 1 | 111 | | if ($PSBoundParameters.ContainsKey('ClientCertificateValidation') -and |
| | 1 | 112 | | ($PSBoundParameters.ContainsKey('ClientCertificateValidationCode') -or $PSBoundParameters.ContainsKey('Clien |
| | 1 | 113 | | throw 'Provide either -ClientCertificateValidation (delegate) or -ClientCertificateValidationCode/-ClientCer |
| | | 114 | | } |
| | | 115 | | |
| | 1 | 116 | | if ($PSBoundParameters.ContainsKey('ClientCertificateValidationCode') -and $PSBoundParameters.ContainsKey('Clien |
| | 1 | 117 | | throw 'Provide either -ClientCertificateValidationCode or -ClientCertificateValidationCodePath, not both.' |
| | | 118 | | } |
| | | 119 | | |
| | 1 | 120 | | if ($PSBoundParameters.ContainsKey('ClientCertificateValidationCodePath') -and $PSBoundParameters.ContainsKey('C |
| | 1 | 121 | | throw 'Do not specify -ClientCertificateValidationLanguage when using -ClientCertificateValidationCodePath. |
| | | 122 | | } |
| | | 123 | | |
| | 1 | 124 | | if ($PSCmdlet.ParameterSetName -eq 'Items') { |
| | | 125 | | |
| | 1 | 126 | | $Options = [Microsoft.AspNetCore.Server.Kestrel.Https.HttpsConnectionAdapterOptions]::new() |
| | 1 | 127 | | if ($null -ne $SslProtocols) { |
| | 0 | 128 | | $options.SslProtocols = $SslProtocols |
| | | 129 | | } |
| | 1 | 130 | | if ($null -ne $ClientCertificateMode) { |
| | 1 | 131 | | $options.ClientCertificateMode = $ClientCertificateMode |
| | | 132 | | } |
| | | 133 | | |
| | 1 | 134 | | if ($PSBoundParameters.ContainsKey('ClientCertificateValidationCode')) { |
| | 1 | 135 | | $lang = [Kestrun.Scripting.ScriptLanguage]::$ClientCertificateValidationLanguage |
| | 1 | 136 | | $ClientCertificateValidation = [Kestrun.Certificates.ClientCertificateValidationCompiler]::Compile($Serv |
| | | 137 | | } |
| | | 138 | | |
| | 1 | 139 | | if ($PSBoundParameters.ContainsKey('ClientCertificateValidationCodePath')) { |
| | 1 | 140 | | $resolvedPath = Resolve-Path -LiteralPath $ClientCertificateValidationCodePath -ErrorAction Stop |
| | 1 | 141 | | $codeFromFile = Get-Content -LiteralPath $resolvedPath.Path -Raw -ErrorAction Stop |
| | 1 | 142 | | $lang = Resolve-KrCodeLanguageFromPath -Path $resolvedPath.Path |
| | 1 | 143 | | $ClientCertificateValidation = [Kestrun.Certificates.ClientCertificateValidationCompiler]::Compile($Serv |
| | | 144 | | } |
| | | 145 | | |
| | 1 | 146 | | if ($null -ne $ClientCertificateValidation) { |
| | 1 | 147 | | $options.ClientCertificateValidation = $ClientCertificateValidation |
| | | 148 | | } |
| | 1 | 149 | | if ($null -ne $ServerCertificate) { |
| | 0 | 150 | | $Options.ServerCertificate = $ServerCertificate |
| | | 151 | | } |
| | 1 | 152 | | if ($null -ne $ServerCertificateChain) { |
| | 0 | 153 | | $Options.ServerCertificateChain = $ServerCertificateChain |
| | | 154 | | } |
| | 1 | 155 | | if ($HandshakeTimeout -gt 0) { |
| | 0 | 156 | | $Options.HandshakeTimeout = [System.TimeSpan]::FromSeconds($HandshakeTimeout) |
| | | 157 | | } |
| | 1 | 158 | | $Options.CheckCertificateRevocation = $CheckCertificateRevocation.IsPresent |
| | | 159 | | } |
| | | 160 | | |
| | 1 | 161 | | $Server.Options.HttpsConnectionAdapter = $Options |
| | | 162 | | |
| | 1 | 163 | | if ($PassThru.IsPresent) { |
| | | 164 | | # if the PassThru switch is specified, return the modified server instance |
| | 0 | 165 | | return $Server |
| | | 166 | | } |
| | | 167 | | } |
| | | 168 | | } |