- Article
There are different ways to create and use self-signed certificates for development and testing scenarios. This article covers using self-signed certificates with dotnet dev-certs, and other options like PowerShell and OpenSSL.
You can then validate that the certificate will load using an example such as an ASP.NET Core app hosted in a container.
Prerequisites
For dotnet dev-certs, be sure to have the appropriate version of .NET installed:
- Install .NET on Windows
- Install .NET on Linux
- Install .NET on macOS
This sample requires Docker 17.06 or later of the Docker client.
Prepare sample app
For this guide, you'll use a sample app and make changes where appropriate.
Check that the sample app Dockerfile is using .NET 8.
Depending on the host OS, you might need to update the ASP.NET runtime. For example, to target the appropriate Windows runtime, change mcr.microsoft.com/dotnet/aspnet:8.0-nanoservercore-2009 AS runtime to mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime in the Dockerfile.
For example, this will help with testing the certificates on Windows:
# https://hub.docker.com/_/microsoft-dotnetFROM mcr.microsoft.com/dotnet/sdk:8.0 AS buildWORKDIR /source# copy csproj and restore as distinct layersCOPY *.sln .COPY aspnetapp/*.csproj ./aspnetapp/RUN dotnet restore -r win-x64# copy everything else and build appCOPY aspnetapp/. ./aspnetapp/WORKDIR /source/aspnetappRUN dotnet publish -c release -o /app -r win-x64 --self-contained false --no-restore# final stage/imageFROM mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtimeWORKDIR /appCOPY --from=build /app ./ENTRYPOINT ["aspnetapp"]If you're testing the certificates on Linux, you can use the existing Dockerfile.
Make sure the aspnetapp.csproj includes the appropriate target framework:
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>net8.0</TargetFramework> <!--Other Properties--> </PropertyGroup></Project>Note
If you want to use dotnet publish parameters to trim the deployment, make sure that the appropriate dependencies are included for supporting SSL certificates. Update the dotnet-docker\samples\aspnetapp\aspnetapp.csproj file to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to support SSL certificates when using trimming for self-contained deployments.
Make sure you're pointing to the sample app.
cd .\dotnet-docker\samples\aspnetappBuild the container for testing locally.
docker build -t aspnetapp:my-sample -f Dockerfile .Create a self-signed certificate
You can create a self-signed certificate:
- With dotnet dev-certs
- With PowerShell
- With OpenSSL
With dotnet dev-certs
You can use dotnet dev-certs to work with self-signed certificates.
dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p crypticpassworddotnet dev-certs https --trustNote
The certificate name, in this case aspnetapp.pfx, must match the project assembly name. crypticpassword is used as a stand-in for a password of your own choosing. If console returns "A valid HTTPS certificate is already present.", a trusted certificate already exists in your store. It can be exported using MMC Console.
Configure application secrets, for the certificate:
dotnet user-secrets -p aspnetapp\aspnetapp.csproj initdotnet user-secrets -p aspnetapp\aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "crypticpassword"Note
Note: The password must match the password used for the certificate.
Run the container image with ASP.NET Core configured for HTTPS:
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -v $env:APPDATA\microsoft\UserSecrets\:C:\Users\ContainerUser\AppData\Roaming\microsoft\UserSecrets -v $env:USERPROFILE\.aspnet\https:C:\Users\ContainerUser\AppData\Roaming\ASP.NET\Https mcr.microsoft.com/dotnet/samples:aspnetappOnce the application starts, navigate to https://localhost:8001 in your web browser.
Clean up
If the secrets and certificates aren't in use, be sure to clean them up.
dotnet user-secrets remove "Kestrel:Certificates:Development:Password" -p aspnetapp\aspnetapp.csprojdotnet dev-certs https --cleanWith PowerShell
You can use PowerShell to generate self-signed certificates. The PKI Client can be used to generate a self-signed certificate.
$cert = New-SelfSignedCertificate -DnsName @("contoso.com", "www.contoso.com") -CertStoreLocation "cert:\LocalMachine\My"The certificate will be generated, but for the purposes of testing, should be placed in a cert store for testing in a browser.
$certKeyPath = "c:\certs\contoso.com.pfx"$password = ConvertTo-SecureString 'password' -AsPlainText -Force$cert | Export-PfxCertificate -FilePath $certKeyPath -Password $password$rootCert = $(Import-PfxCertificate -FilePath $certKeyPath -CertStoreLocation 'Cert:\LocalMachine\Root' -Password $password)At this point, the certificates should be viewable from an MMC snap-in.
You can run the sample container in Windows Subsystem for Linux (WSL):
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/contoso.com.pfx -v /c/certs:/https/ mcr.microsoft.com/dotnet/samples:aspnetappNote
Note that with the volume mount, the file path could be handled differently based on host. For example, in WSL you might replace /c/certs with /mnt/c/certs.
If you're using the container built earlier for Windows, the run command would look like the following:
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\contoso.com.pfx -v c:\certs:C:\https aspnetapp:my-sampleOnce the application is up, navigate to contoso.com:8001 in a browser.
Be sure that the host entries are updated for contoso.com to answer on the appropriate IP address (for example 127.0.0.1). If the certificate isn't recognized, make sure that the certificate that is loaded with the container is also trusted on the host, and that there's appropriate SAN / DNS entries for contoso.com.
Clean up
$cert | Remove-ItemGet-ChildItem $certKeyPath | Remove-Item$rootCert | Remove-itemWith OpenSSL
You can use OpenSSL to create self-signed certificates. This example uses WSL / Ubuntu and a bash shell with OpenSSL.
This command generates a .crt and a .key.
PARENT="contoso.com"openssl req \-x509 \-newkey rsa:4096 \-sha256 \-days 365 \-nodes \-keyout $PARENT.key \-out $PARENT.crt \-subj "/CN=${PARENT}" \-extensions v3_ca \-extensions v3_req \-config <( \ echo '[req]'; \ echo 'default_bits= 4096'; \ echo 'distinguished_name=req'; \ echo 'x509_extension = v3_ca'; \ echo 'req_extensions = v3_req'; \ echo '[v3_req]'; \ echo 'basicConstraints = CA:FALSE'; \ echo 'keyUsage = nonRepudiation, digitalSignature, keyEncipherment'; \ echo 'subjectAltName = @alt_names'; \ echo '[ alt_names ]'; \ echo "DNS.1 = www.${PARENT}"; \ echo "DNS.2 = ${PARENT}"; \ echo '[ v3_ca ]'; \ echo 'subjectKeyIdentifier=hash'; \ echo 'authorityKeyIdentifier=keyid:always,issuer'; \ echo 'basicConstraints = critical, CA:TRUE, pathlen:0'; \ echo 'keyUsage = critical, cRLSign, keyCertSign'; \ echo 'extendedKeyUsage = serverAuth, clientAuth')openssl x509 -noout -text -in $PARENT.crtTo get a .pfx, use the following command:
openssl pkcs12 -export -out $PARENT.pfx -inkey $PARENT.key -in $PARENT.crtNote
Starting in .NET 5, Kestrel can take .crt and PEM-encoded .key files in addition to .pfx files with a password.
Depending on the host OS, the certificate needs to be trusted. On a Linux host, 'trusting' the certificate is different and distro dependent.
For the purposes of this guide, here's an example in Windows using PowerShell:
Import-Certificate -FilePath $certKeyPath -CertStoreLocation 'Cert:\LocalMachine\Root'Run the sample using the following command in WSL:
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/contoso.com.crt -e ASPNETCORE_Kestrel__Certificates__Default__KeyPath=/https/contoso.com.key -v /c/path/to/certs:/https/ mcr.microsoft.com/dotnet/samples:aspnetappNote
In WSL, the volume mount path might change depending on the configuration.
Run the following command in PowerShell:
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\contoso.com.crt -e ASPNETCORE_Kestrel__Certificates__Default__KeyPath=c:\https\contoso.com.key -v c:\certs:C:\https aspnetapp:my-sampleOnce the application is up, navigate to contoso.com:8001 in a browser.
Be sure that the host entries are updated for contoso.com to answer on the appropriate IP address (for example 127.0.0.1). If the certificate isn't recognized, make sure that the certificate that is loaded with the container is also trusted on the host, and that there's appropriate SAN / DNS entries for contoso.com.
Clean up
Be sure to clean up the self-signed certificates once done testing.
Get-ChildItem $certKeyPath | Remove-ItemSee also
- dotnet dev-certs
