Gerar certificados autoassinados com a CLI do .NET

Há diferentes maneiras de criar e usar certificados autoassinados para cenários de desenvolvimento e teste. Este artigo aborda o uso de certificados autoassinados com dotnet dev-certs, e outras opções como PowerShell e OpenSSL.

Em seguida, você pode validar que o certificado será carregado usando um exemplo como um aplicativo ASP.NET Core hospedado em um contêiner.

Pré-requisitos

Para dotnet dev-certs, certifique-se de ter a versão apropriada do .NET instalada:

• Instalar o .NET no Windows
• Instalar o .NET no Linux
• Instalar o .NET no macOS

Esse exemplo instala o Docker 17.06 ou posterior do cliente do Docker.

Preparar aplicativo de exemplo

Neste guia, você usará um aplicativo de exemplo e fará alterações quando apropriado.

Verifique se o aplicativo de amostra Dockerfile está usando o .NET 8.

Dependendo do sistema operacional do host, talvez seja necessário atualizar o runtime do ASP.NET. Por exemplo, para direcionar o runtime apropriado do Windows, altere mcr.microsoft.com/dotnet/aspnet:8.0-nanoservercore-2009 AS runtime para mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime no Dockerfile.

Por exemplo, isso ajudará a testar os certificados no Windows:

# https://hub.docker.com/_/microsoft-dotnet
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /source

# copy csproj and restore as distinct layers
COPY *.sln .
COPY aspnetapp/*.csproj ./aspnetapp/
RUN dotnet restore -r win-x64

# copy everything else and build app
COPY aspnetapp/. ./aspnetapp/
WORKDIR /source/aspnetapp
RUN dotnet publish -c release -o /app -r win-x64 --self-contained false --no-restore

# final stage/image
FROM mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime
WORKDIR /app
COPY --from=build /app ./
ENTRYPOINT ["aspnetapp"]

Se você estiver testando os certificados no Linux, poderá usar o Dockerfile existente.

Verifique se a estrutura de destino aspnetapp.csproj inclui a estrutura de destino apropriada:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <!--Other Properties-->
  </PropertyGroup>

</Project>

Observação

Se você quiser usar parâmetros dotnet publish para cortar a implantação, verifique se as dependências apropriadas estão incluídas para dar suporte a certificados SSL. Atualize o arquivo dotnet-docker\samples\aspnetapp\aspnetapp.csproj para garantir que os assemblies apropriados sejam incluídos no contêiner. Para referência, verifique como atualizar o arquivo .csproj para suportar certificados SSL ao usar a restrição para implementações autônomas.

Verifique se você está apontando para o aplicativo de exemplo.

cd .\dotnet-docker\samples\aspnetapp

Crie o contêiner para testar localmente.

docker build -t aspnetapp:my-sample -f Dockerfile .

Criará um certificado autoassinado

Você pode criar um certificado autoassinado:

• Com dotnet dev-certs
• Com o PowerShell
• With OpenSSL

Com dotnet dev-certs

Você pode usar dotnet dev-certs para trabalhar com certificados autoassinados.

dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p crypticpassword
dotnet dev-certs https --trust

Observação

O nome do certificado, nesse caso aspnetapp.pfx, deve corresponder ao nome do assembly do projeto. crypticpassword é usado como um stand-in para uma senha de sua própria escolha. Se o console retornar "Um certificado HTTPS válido já está presente.", já existe um certificado confiável em seu repositório. Ele pode ser exportado usando o Console do MMC.

Configure segredos do aplicativo para o certificado:

dotnet user-secrets -p aspnetapp\aspnetapp.csproj init
dotnet user-secrets -p aspnetapp\aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "crypticpassword"

Observação

Observação: a senha deve corresponder à senha usada para o certificado.

Execute a imagem do contêiner com ASP.NET Core configurado para 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:aspnetapp

Quando o aplicativo for iniciado, navegue até https://localhost:8001 no seu navegador da Web.

Limpeza

Se os segredos e certificados não estiverem em uso, certifique-se de limpá-los.

dotnet user-secrets remove "Kestrel:Certificates:Development:Password" -p aspnetapp\aspnetapp.csproj
dotnet dev-certs https --clean

Com o PowerShell

Você pode usar o PowerShell para gerar certificados autoassinados. O cliente PKI pode ser usado para gerar um certificado autoassinado.

$cert = New-SelfSignedCertificate -DnsName @("contoso.com", "www.contoso.com") -CertStoreLocation "cert:\LocalMachine\My"

O certificado será gerado, mas para fins de teste, deve ser colocado em um repositório de certificados para teste em um navegador.

$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)

Neste ponto, os certificados devem ser exibidos de um snap-in do MMC.

Você pode executar o contêiner de exemplo no Subsistema do Windows para 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:aspnetapp

Observação

Observe que, com a montagem do volume, o caminho do arquivo pode ser tratado de forma diferente com base no host. Por exemplo, na WSL, você pode substituir /c/certs por /mnt/c/certs.

Se você estiver usando o contêiner criado anteriormente para Windows, o comando executar será semelhante ao seguinte:

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-sample

Depois que o aplicativo estiver atualizado, navegue até contoso.com:8001 em um navegador.

Verifique se as entradas do host sejam atualizadas para contoso.com responder no endereço IP apropriado (por exemplo, 127.0.0.1). Se o certificado não for reconhecido, verifique se o certificado carregado com o contêiner também é confiável no host e se há entradas SAN/DNS apropriadas para contoso.com.

Limpeza

$cert | Remove-Item
Get-ChildItem $certKeyPath | Remove-Item
$rootCert | Remove-item

With OpenSSL

Você pode usar o OpenSSL para criar certificados autoassinados. Este exemplo usa o WSL / Ubuntu e um shell bash com OpenSSL.

Esse comando gera um .crt e um .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.crt

Para obter um .pfx, use o seguinte comando:

openssl pkcs12 -export -out $PARENT.pfx -inkey $PARENT.key -in $PARENT.crt

Observação

A partir do .NET 5, o Kestrel pode aceitar arquivos .crt e .key codificados em PEM, além de arquivos .pfx com uma senha.

Dependendo do sistema operacional do host, o certificado precisa ser confiável. Em um host Linux, usar 'trusting' no certificado é diferente e depende da distribuição.

Para a finalidade deste guia, veja um exemplo no Windows usando o PowerShell:

Import-Certificate -FilePath $certKeyPath -CertStoreLocation 'Cert:\LocalMachine\Root'

Execute a amostra usando o seguinte comando no 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:aspnetapp

Observação

No WSL, o caminho da montagem do volume pode mudar dependendo da configuração.

Execute o seguinte comando no 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-sample

Depois que o aplicativo estiver atualizado, navegue até contoso.com:8001 em um navegador.

Verifique se as entradas do host sejam atualizadas para contoso.com responder no endereço IP apropriado (por exemplo, 127.0.0.1). Se o certificado não for reconhecido, verifique se o certificado carregado com o contêiner também é confiável no host e se há entradas SAN/DNS apropriadas para contoso.com.

Limpeza

Certifique-se de limpar os certificados autoassinados após o teste concluído.

Get-ChildItem $certKeyPath | Remove-Item

Confira também

• dotnet dev-certs