Diretrizes de segurança

A CLI do winapp torna o desenvolvimento de Windows local simples: ele pode gerar um certificado de assinatura, confiar nele em seu computador e ativar o Modo de Desenvolvedor para você. Cada uma dessas etapas altera o estado do computador ou cria um arquivo que carrega uma chave privada, portanto, ajuda a saber exatamente o que eles fazem.

Esta página explica a consequência de cada comando, como desfazê-lo e o que fazer de forma diferente quando você envia. Os certificados de desenvolvimento e o Modo de Desenvolvedor são o caminho normal e compatível para testes locais . A meta aqui é que você entenda o que está aceitando, não que você os evite.

Certificados de desenvolvimento

Os pacotes MSIX devem ser assinados antes que Windows os instale. Para testes locais, winapp cert generate cria um certificado autoassinado para que você possa assinar e instalar seu próprio pacote sem comprar nada.

O que winapp cert generate cria

O certificado gerado é um certificado de assinatura de código autoassinado e de entidade final:

Property Value
Key RSA 2048 bits, marcado como exportável
Algoritmo de assinatura SHA-256 com RSA (PKCS nº 1 v1.5)
Uso de chave Assinatura digital
Uso avançado de chave Assinatura de código (1.3.6.1.5.5.7.3.3)
Restrições básicas Não é uma autoridade de certificação
Validade 365 dias por padrão (--valid-days)
Assunto Deve corresponder ao Publisher no seu manifesto

O comando grava duas coisas:

  • devcert.pfx no diretório atual (ou no caminho que você passa para --output). Esse arquivo contém o certificado e sua chave privada.
  • Uma cópia do certificado em seu repositório de certificados pessoal (Cert:\CurrentUser\My).

Com --export-cer, ele também grava um .cer arquivo ao lado do .pfx. Esse arquivo contém apenas o certificado público , nenhuma chave privada , o que torna a coisa certa a ser entregue a um colega de equipe ou a um computador de teste que precisa confiar em seus builds.

Note

Um certificado autoassinado é confiável por ninguém até que alguém confie explicitamente nele. Serve para sua própria máquina e suas máquinas de teste; não substitui uma identidade real de assinatura de código ao distribuir seu aplicativo.

A senha padrão

winapp cert generate usa password como a senha PFX, a menos que você passe --password. O mesmo valor padrão se aplica quando você posteriormente fornece esse certificado para winapp sign, cuja opção de senha também é --password, e para winapp pack, que usa --cert-password.

Uma senha conhecida significa que a chave devcert.pfx privada está efetivamente desprotegida. Qualquer pessoa que obtém o arquivo pode assinar o código com ela. Essa é uma concessão aceitável para um certificado descartável que serve apenas para assinar compilações locais de teste em seu próprio computador, e é por isso que esse padrão existe.

Importante

Trate a senha padrão como um sinal de que o certificado é descartável. Se um certificado for usado para assinar algo que outra pessoa instalará, ele não deverá ser um winapp cert generate certificado com a senha padrão – consulte Assinatura para produção.

Scripts e agentes não precisam comparar a senha por conta própria: winapp cert generate --json relata "defaultPasswordIsPublic": true e repete a informação em um array warnings sempre que o padrão estiver em vigor. Veja gerar saída JSON de certificado.

Onde o arquivo de certificado reside

devcert.pfx é uma chave privada no disco. Duas regras mantêm isso fora de problemas:

Não confirme isso.winapp cert generate acrescenta automaticamente o nome do arquivo do certificado ao .gitignore lado dele, de modo que o fluxo padrão já está coberto. Se você mover o arquivo, renomeá-lo ou gerá-lo em um diretório gerenciado por outro .gitignore, verifique se a entrada o acompanhou:

git check-ignore -v devcert.pfx

Se isso não imprimir nada, o arquivo não será ignorado – adicione-o antes de confirmar.

Não empacote.winapp pack empacota tudo o que está no diretório de entrada; portanto, um devcert.pfx localizado na pasta de saída do seu aplicativo acaba ficando dentro do MSIX distribuído. Gere o certificado fora da pasta que você empacota, como mostra o guia Empacotando um EXE/CLI e confirme se ele está ausente antes de distribuir:

# Unpack the package and check that no certificate is inside
winapp tool makeappx unpack /p .\MyApp.msix /d .\inspect /o
Get-ChildItem .\inspect -Recurse -Include *.pfx, *.cer

Gorjeta

Se um .pfx com uma chave privada real for incluído em um commit ou publicado, faça a rotação dele: gere um novo certificado, assine novamente e deixe de confiar no antigo usando as etapas em Remover um certificado confiável. Excluir o arquivo de uma confirmação posterior não o remove do histórico.

O que winapp cert install permite

winapp cert install adiciona o certificado ao repositório LocalMachine\TrustedPeople . Isso requer privilégios de administrador, pois altera a confiança de cada usuário no computador.

Quando um certificado estiver dentroTrustedPeople, Windows aceitará qualquer pacote MSIX assinado por esse certificado como confiável o suficiente para instalar, não apenas o pacote que você estava testando. Para um certificado cuja chave privada está em sua posse e que você mantém armazenada localmente, esse é exatamente o efeito pretendido. Esse também é o motivo para agir deliberadamente em relação a isso:

  • Confie nos certificados gerados por você mesmo ou que venham de alguém que você deixaria instalar o software no computador.
  • Não instale um certificado de desenvolvimento em computadores compartilhados, de produção ou de build dos quais outras pessoas dependem.
  • Prefira distribuir a .cer (somente a chave pública) em vez do .pfx quando um colega precisar instalar seu pacote de teste. Eles ganham a capacidade de confiar em seus builds sem obter a capacidade de assinar como você.

Para confiar em um .cer em outra máquina de teste, execute winapp cert install diretamente nela — o comando aceita tanto um .pfx quanto um .cer somente público:

# Run as Administrator
winapp cert install .\devcert.cer

O equivalente usando somente ferramentas internas de Windows é:

# Run as Administrator
Import-Certificate -FilePath .\devcert.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

Removendo um certificado confiável

Os certificados de desenvolvimento expiram após um ano por padrão, mas a expiração não é remoção. Quando você não precisar mais de um certificado — o projeto terminou, a máquina está sendo reaproveitada ou a chave pode ter vazado — remova-o explicitamente.

Primeiro, localize sua impressão digital:

Get-ChildItem Cert:\LocalMachine\TrustedPeople |
    Where-Object { $_.Subject -like '*CN=Contoso*' } |
    Format-List Subject, Thumbprint, NotAfter

Em seguida, remova-o do repositório de confiança do computador. Esta etapa precisa de elevação:

# Run as Administrator. Replace with the thumbprint from the previous command.
$thumbprint = 'ABCD...'
Remove-Item -Path "Cert:\LocalMachine\TrustedPeople\$thumbprint"

cert generate também colocou o certificado, juntamente com sua chave privada, em seu repositório pessoal. Remova isso de um prompt normal, sem privilégios elevados, conectado com a conta que executou o cert generate:

$thumbprint = 'ABCD...'
Remove-Item -Path "Cert:\CurrentUser\My\$thumbprint"

Importante

Execute os dois comandos acima nos contextos mostrados. Se você elevou usando uma conta de administrador diferente, Cert:\CurrentUser nessa sessão elevada é o repositório desse administrador — não o seu — portanto, a chave privada ficaria no repositório do usuário que a gerou.

Por fim, exclua o .pfx e quaisquer cópias do .cer que você tenha distribuído, e cancele o registro dos pacotes que você instalou por fora (sideload) com ele:

winapp unregister

Note

A remoção do certificado não desinstala pacotes que já foram instalados com ele. Desinstale-os separadamente por meio de Configurações > Aplicativos > Aplicativos instalados ou com winapp unregister, para pacotes registrados no modo de desenvolvimento.

Modo de desenvolvedor

O Windows exige o Modo de Desenvolvedor para registrar um pacote de aplicativo diretamente de uma pasta no disco — um layout solto — em vez de instalar um MSIX compilado e assinado. Comandos como winapp run e create-debug-identity dependem disso e falham sem isso, e winapp init se oferece para ativá-lo para você.

O que muda ao ativá-lo

A interface de linha de comando (CLI) habilita o Modo de Desenvolvedor gravando dois valores DWORD sob HKEY_LOCAL_MACHINE:

HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock
    AllowDevelopmentWithoutDevLicense = 1
    AllowAllTrustedApps               = 1

Como essas são configurações de todo o computador, a CLI inicia um processo auxiliar elevado e Windows mostra um prompt de Controle de Conta de Usuário. Nada será alterado se você recusar o prompt.

Na prática, isso significa que o computador:

  • Registre pacotes de aplicativos diretamente de uma pasta no disco, sem que eles sejam empacotados em um MSIX ou sequer assinados (AllowDevelopmentWithoutDevLicense).
  • Instale pacotes de aplicativos de fora do Microsoft Store desde que sejam assinados por um certificado em que o computador confia, incluindo qualquer certificado de desenvolvimento em TrustedPeople (AllowAllTrustedApps).

Importante

O Modo de Desenvolvedor mais um certificado de desenvolvimento confiável é um afrouxamento deliberado das restrições de instalação padrão. Essa combinação pertence a computadores de desenvolvimento e teste. Deixe-o desativado em máquinas de produção, quiosques e infraestrutura compartilhada.

Controlando quando ele está habilitado

winapp init pergunta antes de alterar qualquer coisa e --use-defaults ignora totalmente a pergunta, deixando o Modo de Desenvolvedor intocado. Isso torna as execuções por script e de CI seguras por padrão:

winapp init --use-defaults

Se você preferir gerenciar a configuração por conta própria, habilite-a uma vez por meio do Modo de Desenvolvedor do Sistema > de Configurações > para desenvolvedores > e a CLI a detectará e seguirá em frente.

Desativação

Use o Sistema > de Configurações para desenvolvedores e desative >o Modo de Desenvolvedor. Esse é o caminho recomendado, pois as Configurações também limpam o estado do sistema operacional associado. Para confirmar o valor do Registro posteriormente:

Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
    -Name AllowDevelopmentWithoutDevLicense, AllowAllTrustedApps

Desativar o Modo de Desenvolvedor não remove certificados confiáveis ou pacotes já instalados. Confira Como remover um certificado confiável.

Assinatura para produção

Um certificado de desenvolvimento só funciona para pessoas que confiaram explicitamente nele. Para distribuir seu aplicativo, assine-o com uma identidade na qual o Windows já confia.

Escolher uma identidade de assinatura

  • Assinatura Confiável do Azure – um serviço de assinatura gerenciado pela nuvem. A chave privada nunca existe no computador de build, portanto, não há como .pfx proteger, vazar ou girar manualmente. Use winapp az-sign, que se autentica com a cadeia de credenciais Azure padrão e funciona com GitHub Actions OIDC ou uma identidade gerenciada.

    winapp az-sign .\MyApp.msix

  • Um certificado de assinatura de código de uma autoridade certificadora confiável — passe-o para winapp sign como o segundo argumento posicional, com a senha em --password. Em seguida, você é responsável por armazenar o material da chave com segurança; mantenha-o em um token de hardware, em um cofre de chaves ou no repositório secreto do provedor de CI e nunca no repositório.

  • O Microsoft Store – se você distribuir exclusivamente por meio da Loja, ele assinará o pacote para você e você não precisará assinar antes do envio.

Em todos os casos, o assunto do certificado deve corresponder ao valor Publisherno seu manifesto, inclusive para pacotes esparsos.

Manter os segredos de assinatura fora do repositório

As senhas de certificado pertencem ao repositório de segredos de CI, não em um arquivo de configuração. Leia-os do ambiente em vez de codificá-los:

winapp sign .\MyApp.msix $env:SIGNING_CERT_PATH --password $env:SIGNING_CERT_PASSWORD

O mesmo se aplica à configuração de build incluída no controle de código-fonte, como uma configuração do Electron Forge — consulte Empacotamento do Electron. winapp az-sign evita totalmente o problema, porque não há senha para passar.

Antes de publicar

Uma breve lista de verificação para a transição do teste local para a distribuição:

  • O pacote é assinado com um certificado emitido por uma Autoridade Certificadora (CA), com a Assinatura Confiável do Azure ou enviado para a Loja, não com devcert.pfx.
  • Nenhum arquivo .pfx ou .cer está dentro da saída do pacote.
  • Nenhuma senha de certificado aparece em arquivos confirmados, scripts de build ou logs de CI.
  • O assunto do certificado corresponde ao manifesto Publisher.
  • Os certificados de desenvolvimento e o Modo de Desenvolvedor não estão habilitados em computadores que só precisam executar o aplicativo.

Relatando um problema de segurança

Para relatar uma vulnerabilidade de segurança na própria CLI do winapp, siga o processo em SECURITY.md. Não abra uma issue pública no GitHub para relatar problemas de segurança.

  • Last updated on