Create a Self‑Signed Certificate

Generate a development certificate for localhost and bind it to an HTTPS listener.

Prerequisites: see Introduction.

Full source

<#
    Create a self-signed development certificate and start HTTPS listener.
    FileName: 6.1-Cert-SelfSigned.ps1
#>
param(
    [int]$Port = 5000,
    [IPAddress]$IPAddress = [IPAddress]::Loopback
)

# Initialize Kestrun root directory
Initialize-KrRoot -Path $PSScriptRoot

# Configure default logging
New-KrLogger |
    Set-KrLoggerLevel -Value Debug |
    Add-KrSinkConsole |
    Register-KrLogger -Name 'myLogger' -SetAsDefault

# Create a self-signed cert for localhost (RSA 2048 by default)
$cert = New-KrSelfSignedCertificate -DnsNames localhost, 127.0.0.1 -Exportable -ValidDays 30

# Show EKUs
Get-KrCertificatePurpose -Certificate $cert | Out-Host

# Configure HTTPS listener with the certificate
New-KrServer -Name "HTTPS Demo"
Add-KrEndpoint -Port $Port -IPAddress $IPAddress -X509Certificate $cert -Protocols Http1

# Minimal route to verify HTTPS works

Enable-KrConfiguration
Add-KrMapRoute -Verbs Get -Pattern "/hello" -ScriptBlock { Write-KrTextResponse "hello https" }

Start-KrServer

# Clean up and close all the loggers when the server stops
Close-KrLogger

Step-by-step

1. Initialize root: Initialize-KrRoot -Path $PSScriptRoot so relative paths resolve predictably.
2. Logging: create and register a default console logger at Debug (helps trace setup and requests).
3. Create a development certificate with New-KrSelfSignedCertificate:
   • Dns: -DnsNames 'localhost'[, '127.0.0.1'] (or your machine DNS).
   • Key: -KeyType Rsa|Ecdsa and -KeyLength (e.g., 2048 for RSA).
   • Subject (optional): -Country, -Org, -CommonName.
   • Other (optional): -Exportable, -ValidDays 30 for dev convenience.
4. Inspect EKU (optional): Get-KrCertificatePurpose -Certificate $cert to verify usages like ServerAuth.
5. Create server: New-KrServer.
6. Bind HTTPS listener: Add-KrEndpoint -Port 5001 -IPAddress Loopback -X509Certificate $cert.
   • Optionally keep HTTP on 5000 for plaintext testing.
   • You can restrict protocols, e.g., -Protocols Http1.
7. Apply config: Enable-KrConfiguration.
8. Map a minimal route (e.g., GET /hello) returning JSON so you can verify TLS termination.
9. Start the server: Start-KrServer.
10. Client notes:
    • For self‑signed certs, use curl -k or Invoke-WebRequest -SkipCertificateCheck during development.
    • Prefer trusting the certificate locally for clean validation when possible.

Try it

Save the sample locally so it’s easy to run. Copy the contents of pwsh/tutorial/examples/6.1-Cert-SelfSigned.ps1 into a new file in an empty working folder (for example, cert-https.ps1), then run:

# From your working folder
pwsh .\cert-https.ps1
curl -k https://127.0.0.1:5001/hello
Invoke-WebRequest -SkipCertificateCheck -Uri 'https://127.0.0.1:5001/hello' | Select-Object -ExpandProperty Content

Note: -k/SkipCertificateCheck is used because this is a self‑signed development cert.

Troubleshooting

Symptom	Cause	Fix
Browser shows certificate warning	Self‑signed not trusted	Trust the certificate locally or use curl -k for quick tests
Listener fails to start on 5001	Port in use	Pick another port or stop the conflicting process
TLS handshake errors	Wrong IP/DNS in certificate	Include correct -DnsNames (e.g., ‘localhost’)
JSON route still on HTTP only	Mapped on 5000 instead of 5001	Verify listener and test URL use https://127.0.0.1:5001

References

• New-KrSelfSignedCertificate
• Get-KrCertificatePurpose
• Add-KrEndpoint
• New-KrServer
• Enable-KrConfiguration
• Add-KrMapRoute
• Start-KrServer

---

Previous / Next

Go back to Logging or continue to Generate a CSR.