Earned ASP.NET Core developer certificates working in both WSL and Windows (2023)

I recently reinstalled my development machine for various reasons and as part of that I decided to use Visual Studio Code and thatRemote - WSLExtension to do my development on Linux for a while.

Warning:For some reason the code in this post no longer works. It did while I was writing the post, but when I tried to use it recently it failed. I'm not sure if there were some changes in .NET 5 or something. But it doesn't work for me. Because of this, I would recommend reading my updated post on the subject. It is available at"Setting up ASP.NET Core developer certificates for WSL and Windows"!

Why? Well, it has some advantages... And also... Because!

I could probably get on with it in the Windows world without too much trouble, and I probably will for some stuff. But having worked with Windows all my life and supporting .NET Core Linux, I thought it was time to broaden my horizons a bit. I find that the challenge of trying new things pushes me not only to give me a better understanding of things, but also to open my eyes to new ways of doing things. Maybe Windows isn't the best solution for everything...

However, I quickly encountered a few problems. Certificate issues to be more specific…

Developer certificates on WSL

If you want to build an ASP.NET Core application and use HTTPS, you "need" a self-signed development certificate. This is pretty easy to set up with thedotnet dev-certsTool. And to be honest, when I set up my new application in WSL, I didn't even have to do that. It just magically worked. Kestrel somehow managed to find an SSL certificate in Linux and used that for my application. However, this certificate is not trusted by Windows (or Linux), so my browser gave a warning when I navigated to this web app.

This is pretty easy to fix by simply having Windows trust the SSL certificate. And it's covered in a number of other blog posts and SO questions around the interwebs. However, this doesn't solve some other problems that surfaced half an hour later...

Dev Certificate Trust WSL

My real problems started when I decided to create two applications that needed to communicate with each other over TLS/SSL... I needed to create an IdP with Identity Server and have a web application trust it.

Boot up the IdP withrun dotnetin WSL worked fine and I was able to access it from Windows without any problems. However, when I launched my second application within the WSL, which relied on the IdP, I faced this

...---> System.Net.Http.HttpRequestException: The SSL connection could not be established, see inner exception.---> System.Security.Authentication.AuthenticationException: The remote certificate is invalid due to errors in the certificate Chain: UntrustedRoot at System.Net.Security.SslStream.SendAuthResetSignal(ProtocolToken message, ExceptionDispatchInfo exception) ...

The reason for this is actually quite simple... The SSL certificate that is used by default for the ASP.NET applications is not trusted by the system, even if it is a self-signed certificate from the local computer. So when the relying party web application tries to communicate with the IdP, it gets an SSL certificate that it doesn't trust. And so it fails.

There are a couple of ways to resolve this. The easiest and probably least recommended method is to ignore the certificate issue by adding something like this

...#if DEBUGwar Handler = Neu HttpClientHandler();Handler.ServerCertificateCustomValidationCallback = (message, zert, Chain, Mistake) => { return true; };#endif...#if DEBUGoptions.BackchannelHttpHandler = Handler;#endif...

This will add an http handler that completely ignores certificate validation, which is obviously not a good idea. Even if this code is only used during debug builds.

Sure it works, but it's a poor solution that requires code changes for each project. And if for some reason you release a debug build to the world, a lot of your security just went out the window...

The better solution would be to trust the certificate.

Trust dev certificates on Linux (Ubuntu).

There doesn't seem to be a standard way to trust certificates on Linux, but on Ubuntu you can trust a certificate by including the public key/usr/local/share/ca-certificatesand then callsudo update-ca certificates. However… this doesn't quite work with the certificates generated by thedotnet dev-certsTool.

Why? Well, there seems to be a bug in OpenSSL that is causing some problems. It has to do with Linux requiring some X509v3 attributes that Windows doesn't have and so on. It's a very technical topic, to be honest, and a bit boring... But if you're interested, you can read more about it at https://github.com/dotnet/aspnetcore/issues/7246.

Instead, we need to manually generate a certificate and use that instead. This is also covered in a few places on the web, but I'd like to expand on it a little. I want to make sure I can use the same certificate in both Windows and WSL. For two reasons. Firstly because it should be possible... And secondly if you use separate certs you can't mix applications in WSL and Windows because the WSL certs wouldn't trust Windows' cert unless you have that cert Added Confidence as Good. And it would be much nicer to have a single trusted certificate used in both environments.

This got me down a bit of a rabbit hole that took me some time to figure out. Being not the best at OpenSSL and being fairly new to Linux and not knowing what .NET Core considers a valid developer certificate, things were a bit more complicated than I honestly expected. But that's what I came up with.

Creating an X509 certificate

The first thing we need to do is create a new X509 certificate. A task I was hoping I could do with PowerShell andNew self-signed certificate. But that didn't work... Why? For .NET Core to recognize a certificate as a developer certificate, it must contain a specific X509 extension, which I couldn't add using the PowerShell command. Instead I had to use OpenSSL in WSL to create it.

The first thing I needed to create a new certificate was a configuration file that defined the certificate requirements. So I created a file namedlocalhost.confin my home directory and added the following

[req]distinguished_name = req_distinguished_namereq_extensions = req_extx509_extensions = v3_ca[req_distinguished_name]commonName = Allgemeiner Name (z. B. Server-FQDN oder IHR Name)commonName_default = localhostcommonName_max = 64[req_ext]subjectAltName = @alt_names1.3.6.1.4.1.311.84.1=ASN:84.1 UTF8String:Something[v3_ca]subjectAltName = @alt_namesbasicConstraints = kritisch, CA:falsekeyUsage = keyCertSign, cRLSign, digitalSignature,keyEncipherment[alt_names]DNS.1 = localhostDNS.2 = 127.0.0.1

This creates a new certificate with a 2048-bit key, including the necessary key usages.

Note:Linux apparently requires self-signed certificates to be both a certificate and a CA, so it needs to be assigned the use of certificate signing.

In addition to the correct key usages, it adds a custom extension with the id1.3.6.1.4.1.311.84.1.1. This is used by ASP.NET Core to verify that it really is a valid developer certificate. It was also what PowerShell couldn't add for me...

Once the configuration is in place, it can be used to create a public/private key pair with the following command

openssl-Anf-x509 -Node -Take365-new keyrsa:2048-key off~/localhost.key-out~/localhost.crt-config~/localhost.conf

Note:Just press Enter when promptedcommon namesas it is by defaultpremises Hostwhat you want

Just to check if the public key is not already trusted we can run it

>verify openssl ~/localhost.crtCN=localhosterror 18 at 0-deep-first-search: self-signed certificate error /home/zerokoll/localhost.crt: verification failed

The next step is to ensure that Ubuntu trusts the certificate. To do this, the public key must be copied/usr/local/share/ca-certificatesand then trusted by running as a certificate authorityupdate-ca certificates. Like this

sudo cp ~/localhost.crt /usr/local/share/ca-certificatessudo update-ca-certificates

Now we can try again to verify that the certificate is trusted by running itverify openssl

Verify openssl ~/localhost.crt/home/zerokoll/localhost.crt: OK

Ok, now the Linux part trusts the certificate. The next step is to get Windows to do the same.

Windows requires a PFX version of the certificate that contains both the private and public keys. The reason both are needed is because not only do we trust it, but we will be using it as our SSL certificate on this site. So the first step is to create a PFX from the public/private key pair. Like this

openssl pkcs12-Export -out~/localhost.pfx- Ink~/localhost.key-in~/localhost.crt

This will ask you for a password and you should make sure you add a strong password as it could be dangerous if someone nefarious gets their hands on it. Remember, it's a CA certificate and you trust it. So if someone got their hands on it and used it to generate a new certificate, you would automatically trust that certificate...

Next, the PFX needs to be moved to Windows. Actually, it could stay in Linux as well, but moving it to Windows makes it easy to use from Windows and copy to other Linux distributions if needed.

Moving the file to Windows looks like this

mkdir -p/c/Benutzer/<BENUTZERNAME>/.aspnet/.sslmv~/localhost.pfx /c/Users/<BENUTZERNAME>/.aspnet/https

Where [USERNAME] is the name of your Windows user.

Note:I mount my Windows drives in the root of my WSL. If not, you need to change the path/mnt/c/Users/<BENUTZERNAME>/.aspnet/https

Once this is done the public/private keys etc can be deleted as they are no longer needed

rm -rf./localhost.*

The final step in setting up mutual trust is to import the newly created certificate as a dev-cert and trust itdotnet dev-certs. I used PowerShell to do it like this

dotnet dev-certs https--to clean --import (join path$env:user profile".aspnet/https/localhost.pfx") -p<PASSWORT> dotnet dev-certs https--to trust

That's it! Both systems should now use and trust the same certificate.

On the Windows side, Kestrel should fetch the certificate automatically since it is available in the person store of the current user certificate.

Unfortunately, the WSL side of things isn't quite as nice... Some configuration needs to be done to ensure the correct certificate is used by default.

Configure Kestrel in WSL to use the correct SSL certificate

Kestrel can be configured to use an X509 certificate by using theASPNETCORE_Kestrel:certificates:default:pathandASPNETCORE_Kestrel:Certificates:Default:Passwordconfiguration values. This can be done in several ways.

One way would be to set up the configuration in the appSettings or user secrets. But it would be required for every project you've worked on, which feels tedious and annoying.

Another option is to set up environment variables that define these values. This would be automatically taken as the default by any application running in WSL.

In my case I usee.glike my shell, so I opened up~/.zshrcand added

export ASPNETCORE_Kestrel__Certificates__Default__Password="<KENNWORT>"export ASPNETCORE_Kestrel__Certificates__Default__Path="/c/Users/<USERNAME>/.aspnet/https/localhost.pfx"

Note:If you set configuration values ​​as environment variables, you must replace:with a double underscore.

This ensures that these environment variables are set up whenever this shell is used.

I then reloaded the variables by runningQuelle ~/.zshrc.

Comment:For example, if you use bash, you can add it~/.profileinstead of this.

It should be! Well... I...

Attention... IIS Express

There's a problem with this solution... Unfortunately, IIS Express doesn't play well. The previous solution will set it up for Kestrel to find the new certificate, but IIS Express still wants to use its own self-signed certificate. So if you want to use IIS Express for your development, you need to tell it to use your certificate.

Note:It's not really IIS Express. It's actually HTTP.SYS that binds the ports and certificates etc. And then IIS Express sits on top of it...

By default, IIS Express (or maybe Visual Studio, not sure) seems to bind ports 44300 through 44399 to its own self-signed certificate. This causes some problems if you want

to use your own certificate. Or if you delete the IIS Express self-signed certificate. Don't ask me how I know that...

You can view the current SSL port bindings by running

netsh http shows sslcert

And if you look through this list, you'll probably notice that all of the previously mentioned ports are preemptively bound to the same IIS Express developer certificate, even though they're not actually in use yet.

So if you want to use your own certificate for one of these ports instead, you have to do two things.

First you need to add your own self-signed certificate to the local computer certificate store in the Personal > Certificates folder. Or run the following commands in an elevated PowerShell terminal

$ mypwd =Get-Credential-Username 'Enter password below' -News 'Enter password below'Import pfx certificate-File path<PATH_TO_PFX>-CertStoreLocationCertificate:\LocalMachine\Mj-Password $ mypwd.Password

Next, you need to bind your new certificate to the port in question. This isn't that hard as long as you have the thumbprint of the certificate. Something you can easily get from the Certificates MMC snap-in, or by running a PowerShell command that looks something like this

Write-Host(Get-ChildItem-AwayCertificate:\LocalMachine\My | where object{$_.Theme-to suit "CN=premises Host"}).thumbprint

Tip:If you get more than one thumbprint, chances are you have both your own self-signed certificate and one from IIS Express in it.

Once you have the fingerprint, you'll need to bind the port you want to use with itNet. It looks like this

netsh http update sslcert ipport=0.0.0.0:<PORT> appid='{<APPID>}' certhash=<CERT_HASH>

From wherePORTis the port you want to use,APPIDis any GUID you want andCERT_HASHis the fingerprint you just retrieved.

Another option is to useIisExpressAdminCmd.exeto get the job done. This is a little nicer since it doesn't care about GUIDs. All you have to do is navigateC:\Programme (x86)\IIS Expressand runIisExpressAdminCmd.exe. Like this

CD "C:\PProgram files (x86)\IIS-Express".\IisExpressAdminCmd.exe setupsslUrl-URL:https://localhost:<PORT>/-CertHash:<THUMBPRINT>

From whereTHUMBPRINTis the fingerprint for your certificate andPORTis the port used for your application.

Both options end up with exactly the same result. And you can check if the result is what you want by running it

netsh http shows sslcertexport=0.0.0.0:<PORT>

This should show you that the certificate you are trying to use is now bound to this port.

Unfortunately this has to be done for any applications you want to run through IIS Express, which is a bit of a hassle.

So if you want to make sure you get the same experience as you normally would, ie. H. that you boot up visual studio, start a new project, press F5 and the certificate just works, you can run the following.

For($i=0; $i - Die99; $i++) {.\IisExpressAdminCmd.exe setupsslUrl-URL:"https://localhost:443$($i.ToString().PadLinks(2,"0"))/" -CertHash:<THUMBPRINT>}

This loops through all the pre-bound ports (44300 -> 44399) and rebinds them all to your own certificate. This should make everything "just work" so you can transparently use your new self-signed certificate in IIS Express.

Note:Personally, I prefer to run the application from the terminal window instead, as it allows me to easily view the log output. Despite this, IIS Express is still a very valid option!

Conclusion

Running applications in WSL should now default to our custom certificate for SSL. So should any application using either Kestrel or IIS Express in Windows. Additionally, the certificate should be trusted by both WSL/Linux and Windows, enabling trusted server-to-server communication between applications running on WSL and between apps running on WSL and Windows. And since Windows trusts the certificate, it should also allow you to navigate to your HTTPS-enabled applications and establish an approved, secure connection to applications running on both WSL and Windows.

It was a bit of a hassle to figure this out, but now that it's up and running it should be done and dusted and I shouldn't have to worry about it anymore!

If you have any comments or questions, please contact@ZeroKoll!