| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Creates a localhost development certificate bundle. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | New-KrDevelopmentCertificate creates a localhost leaf certificate for Kestrun development and, |
| | | 6 | | when needed, also creates a CA root certificate that can sign the leaf. You can optionally |
| | | 7 | | trust the generated or supplied root certificate in the Windows CurrentUser Root store. |
| | | 8 | | .PARAMETER DnsNames |
| | | 9 | | The localhost names/IPs to include in the development leaf certificate SAN extension. |
| | | 10 | | .PARAMETER RootCertificate |
| | | 11 | | An optional CA root certificate used to sign the localhost leaf. If omitted, a new development |
| | | 12 | | root certificate is created. |
| | | 13 | | .PARAMETER RootName |
| | | 14 | | The subject common name to use when creating a new development root certificate. |
| | | 15 | | .PARAMETER RootValidDays |
| | | 16 | | The number of days a generated development root certificate is valid. |
| | | 17 | | .PARAMETER LeafValidDays |
| | | 18 | | The number of days the localhost leaf certificate is valid. |
| | | 19 | | .PARAMETER TrustRoot |
| | | 20 | | If specified on Windows, adds the development root certificate to the CurrentUser Root store. |
| | | 21 | | On non-Windows platforms, this cmdlet throws a terminating error before invoking the C# layer. |
| | | 22 | | .PARAMETER Exportable |
| | | 23 | | If specified, the generated certificates will use exportable private keys. |
| | | 24 | | .PARAMETER WhatIf |
| | | 25 | | When -TrustRoot is specified, shows the pending trust-store change and skips adding the |
| | | 26 | | development root to the Windows CurrentUser Root certificate store. |
| | | 27 | | .PARAMETER Confirm |
| | | 28 | | When -TrustRoot is specified, prompts for confirmation before adding the development root |
| | | 29 | | certificate to the Windows CurrentUser Root certificate store. |
| | | 30 | | .EXAMPLE |
| | | 31 | | $bundle = New-KrDevelopmentCertificate -TrustRoot |
| | | 32 | | |
| | | 33 | | Creates a development root CA, issues a localhost leaf certificate from it, trusts the root |
| | | 34 | | in the CurrentUser Root store on Windows, and returns the private root, public-only root, |
| | | 35 | | and leaf certificates. |
| | | 36 | | .EXAMPLE |
| | | 37 | | $root = Import-KrCertificate -FilePath './certs/dev-root.pfx' -Password $password |
| | | 38 | | $bundle = New-KrDevelopmentCertificate -RootCertificate $root -DnsNames 'localhost','127.0.0.1','::1' |
| | | 39 | | |
| | | 40 | | Reuses an existing development root certificate to issue a new localhost leaf certificate. |
| | | 41 | | .EXAMPLE |
| | | 42 | | $password = ConvertTo-SecureString 'p@ssw0rd!' -AsPlainText -Force |
| | | 43 | | $bundle = New-KrDevelopmentCertificate -Exportable |
| | | 44 | | |
| | | 45 | | Export-KrCertificate -Certificate $bundle.RootCertificate -FilePath './certs/dev-root' -Format Pfx -Password $pa |
| | | 46 | | Export-KrCertificate -Certificate $bundle.LeafCertificate -FilePath './certs/localhost' -Format Pfx -Password $p |
| | | 47 | | |
| | | 48 | | Exports the generated root and localhost leaf certificates to PFX files so they can be reused in later sessions. |
| | | 49 | | .OUTPUTS |
| | | 50 | | Kestrun.Certificates.DevelopmentCertificateResult. |
| | | 51 | | #> |
| | | 52 | | function New-KrDevelopmentCertificate { |
| | | 53 | | [KestrunRuntimeApi('Everywhere')] |
| | | 54 | | [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')] |
| | | 55 | | [OutputType([Kestrun.Certificates.DevelopmentCertificateResult])] |
| | | 56 | | param( |
| | | 57 | | [Parameter()] |
| | 1 | 58 | | [string[]]$DnsNames = @('localhost', '127.0.0.1', '::1'), |
| | | 59 | | |
| | | 60 | | [Parameter()] |
| | | 61 | | [System.Security.Cryptography.X509Certificates.X509Certificate2]$RootCertificate, |
| | | 62 | | |
| | | 63 | | [Parameter()] |
| | | 64 | | [string]$RootName = 'Kestrun Development Root CA', |
| | | 65 | | |
| | | 66 | | [Parameter()] |
| | | 67 | | [ValidateRange(1, 36500)] |
| | | 68 | | [int]$RootValidDays = 3650, |
| | | 69 | | |
| | | 70 | | [Parameter()] |
| | | 71 | | [ValidateRange(1, 3650)] |
| | | 72 | | [int]$LeafValidDays = 30, |
| | | 73 | | |
| | | 74 | | [Parameter()] |
| | | 75 | | [switch]$TrustRoot, |
| | | 76 | | |
| | | 77 | | [Parameter()] |
| | | 78 | | [switch]$Exportable |
| | | 79 | | ) |
| | | 80 | | |
| | 1 | 81 | | if ($TrustRoot.IsPresent -and -not $IsWindows) { |
| | 1 | 82 | | $message = 'The -TrustRoot parameter is only supported on Windows. Create the development certificate without -T |
| | 1 | 83 | | $exception = [System.PlatformNotSupportedException]::new($message) |
| | 1 | 84 | | $errorRecord = [System.Management.Automation.ErrorRecord]::new( |
| | | 85 | | $exception, |
| | | 86 | | 'TrustRootRequiresWindows', |
| | | 87 | | [System.Management.Automation.ErrorCategory]::NotImplemented, |
| | | 88 | | 'TrustRoot') |
| | | 89 | | |
| | 1 | 90 | | $PSCmdlet.ThrowTerminatingError($errorRecord) |
| | | 91 | | } |
| | | 92 | | |
| | 1 | 93 | | $trustRoot = $TrustRoot.IsPresent |
| | 1 | 94 | | if ($trustRoot) { |
| | 0 | 95 | | $trustTarget = if ($PSBoundParameters.ContainsKey('RootCertificate') -and $null -ne $RootCertificate) { |
| | 0 | 96 | | $RootCertificate.Subject |
| | | 97 | | } else { |
| | 0 | 98 | | "development root certificate '$RootName'" |
| | | 99 | | } |
| | | 100 | | |
| | 0 | 101 | | if (-not $PSCmdlet.ShouldProcess($trustTarget, 'Trust in Windows CurrentUser Root certificate store')) { |
| | 0 | 102 | | $trustRoot = $false |
| | | 103 | | } |
| | | 104 | | } |
| | | 105 | | |
| | 1 | 106 | | $options = [Kestrun.Certificates.DevelopmentCertificateOptions]::new( |
| | | 107 | | $DnsNames, |
| | | 108 | | $RootCertificate, |
| | | 109 | | $RootName, |
| | | 110 | | $RootValidDays, |
| | | 111 | | $LeafValidDays, |
| | | 112 | | $trustRoot, |
| | | 113 | | $Exportable.IsPresent) |
| | | 114 | | |
| | 1 | 115 | | return [Kestrun.Certificates.CertificateManager]::NewDevelopmentCertificate($options) |
| | | 116 | | } |