Orientações de segurança

A linha de comando winapp torna o desenvolvimento local para Windows simples: pode gerar um certificado de assinatura, confiar nele na sua máquina e ativar o Modo Desenvolvedor por si. Cada um desses passos altera o estado da máquina ou cria um ficheiro que transporta uma chave privada, por isso ajuda saber exatamente o que fazem.

Esta página explica a consequência de cada comando, como o desfazer e o que fazer de diferente quando se envia. Os certificados de desenvolvimento e o Modo Desenvolvedor são o caminho normal e suportado para testes locais — o objetivo aqui é que compreenda no que está a aderir, não que os evite.

Certificados de desenvolvimento

Os pacotes MSIX devem ser assinados antes de o Windows os instalar. Para testes locais, winapp cert generate cria um certificado auto-assinado para que possa assinar e instalar o seu próprio pacote sem comprar nada.

O que winapp cert generate cria

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

O comando escreve duas coisas:

• devcert.pfx no diretório atual (ou no caminho que passa a --output). Este ficheiro contém tanto o certificado como a sua chave privada.
• Uma cópia do certificado na sua loja de certificados pessoais (Cert:\CurrentUser\My).

Com --export-cer, também escreve um .cer ficheiro ao lado do .pfx. Esse ficheiro contém apenas o certificado público — sem chave privada — o que o torna o correto a entregar a um colega de equipa ou a uma máquina de testes que precisa de confiar nas tuas builds.

A palavra-passe padrão

winapp cert generate usa password como palavra-passe do PFX, a menos que passe --password. O mesmo padrão aplica-se quando mais tarde fornece esse certificado a winapp sign, cuja opção de palavra-passe é também --password, e para winapp pack, que assume --cert-password.

Uma palavra-passe bem conhecida significa que a chave privada em devcert.pfx está, na prática, desprotegida — qualquer pessoa que obtenha o ficheiro pode assinar código com ela. Esse é um compromisso aceitável para um certificado descartável, utilizado apenas para assinar compilações de teste locais na sua própria máquina, e é por isso que essa predefinição existe.

Scripts e agentes não têm de comparar eles próprios a palavra-passe: winapp cert generate --json indicam "defaultPasswordIsPublic": true e repetem essa indicação numa matriz warnings sempre que a predefinição estiver ativa. Consulte cert generate JSON output.

Onde se encontra o ficheiro do certificado

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

Não o comprometas.winapp cert generate Adiciona automaticamente o nome do ficheiro do certificado ao .gitignore seguinte, por isso o fluxo padrão já está coberto. Se mover o ficheiro, renomeá-lo ou gerá-lo num diretório gerido por outro .gitignore, verifique se a entrada o seguiu:

git check-ignore -v devcert.pfx

Se isso não imprimir nada, o ficheiro não é ignorado — adicione-o antes de se comprometer.

Não o incluas no pacote.winapp pack inclui tudo no diretório de entrada, por isso, um devcert.pfx que esteja na pasta de saída da tua aplicação acaba dentro do MSIX distribuído. Gere o certificado fora da pasta que vai empacotar, como mostra o guia Packaging an EXE/CLI, e confirme que este está ausente antes de o 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

O que winapp cert install concede

winapp cert install adiciona o certificado ao arquivo LocalMachine\TrustedPeople. Isto requer privilégios de administrador, porque altera a confiança de todos os utilizadores na máquina.

Uma vez que um certificado está inseridoTrustedPeople, o Windows aceitará qualquer pacote MSIX assinado por esse certificado como suficientemente confiável para ser instalado — não apenas o pacote que estava a testar. Para um certificado cuja chave privada detém e guarda localmente, esse é precisamente o efeito pretendido. É também a razão para agir deliberadamente quanto a isso:

• Certificados de confiança que geraste tu próprio, ou que vêm de alguém que deixarias instalar software na máquina.
• Não instale um certificado de desenvolvimento em máquinas partilhadas, de produção ou de construção em que outras pessoas dependam.
• Prefira distribuir apenas a .cer em vez da .pfx quando um colega precisar de instalar o seu pacote de teste. Eles ganham a capacidade de confiar nas tuas builds sem terem a capacidade de assinar como tu.

Para confiar num .cer em outra máquina de teste, execute winapp cert install diretamente nessa máquina — o comando aceita um .pfx ou um .cer apenas público:

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

O equivalente, usando apenas ferramentas do Windows integradas, é:

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

Remoção de um certificado de confiança

Os certificados de desenvolvimento expiram ao fim de um ano por predefinição, mas a expiração não significa a remoção. Quando já não precisar de um certificado — o projeto terminou, a máquina está a ser reutilizada ou a chave pode ter sido comprometida — remova-o de forma explícita.

Primeiro, encontre a sua impressão digital:

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

Depois remove-o da loja de confiança das máquinas. Este degrau 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 Coloque também o certificado, juntamente com a sua chave privada, na sua loja pessoal. Remova isso de uma linha de comandos normal, sem elevação, com sessão iniciada na conta que executou cert generate:

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

Por fim, elimina o .pfx e quaisquer cópias .cer que tenhas distribuído, e desregista os pacotes que instalaste manualmente com ele:

winapp unregister

Modo Desenvolvedor

O Windows exige que o Modo Desenvolvedor registre um pacote de aplicação diretamente a partir 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 oferece ativá-lo por si.

O que muda ao ativá-la

A CLI ativa o Modo Desenvolvedor escrevendo dois DWORD valores em HKEY_LOCAL_MACHINE:

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

Como estas são definições para toda a máquina, a CLI inicia um processo auxiliar elevado e o Windows mostra um aviso de Controlo de Conta de Utilizador. Nada é alterado se rejeitares a solicitação.

Na prática, isto significa que a máquina irá:

• Registar pacotes de aplicações diretamente de uma pasta no disco, sem serem empacotados num MSIX nem assinados de todo (AllowDevelopmentWithoutDevLicense).
• Instale pacotes de aplicações fora da Microsoft Store, desde que estejam assinados por um certificado em que a máquina confie — incluindo qualquer certificado de desenvolvimento em TrustedPeople (AllowAllTrustedApps).

Controlar quando está ativado

winapp init pergunta antes de mudar qualquer coisa, e --use-defaults ignora completamente a pergunta, deixando o Modo Desenvolvedor inalterado. Isso torna seguras por defeito as execuções em script e de CI:

winapp init --use-defaults

Se preferires gerir a definição tu mesmo, ativa-a uma vez através do Modo Desenvolvedor do Sistema > de Definições > Para Desenvolvedores > e a CLI irá detetá-la e seguir em frente.

Desligar

Use o Sistema > de Definições > para programadores e desligue o Modo Desenvolvedor. Este é o caminho recomendado, porque as Definições também limpam o estado associado ao sistema operativo. Para confirmar o valor do registo depois:

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

Desligar o Modo Desenvolvedor não remove certificados de confiança nem pacotes já instalados — ver Remoção de um certificado de confiança.

Assinatura para produção

Um certificado de desenvolvimento só funciona para pessoas que confiaram explicitamente nele. Para distribuir a sua aplicação, assine-a com uma identidade em que o Windows já confie.

Escolha uma identidade de assinatura

• Assinatura Confiável do Azure — um serviço de assinatura gerido na cloud. A chave privada nunca existe na sua máquina de compilação, pelo que não existe .pfx para proteger, divulgar ou efetuar manualmente a sua rotação. Use winapp az-sign, que autentica com a cadeia de credenciais padrão do Azure e funciona com GitHub Actions OIDC ou uma identidade gerida.

  winapp az-sign .\MyApp.msix
  

• Um certificado de assinatura de código de uma autoridade certificadora de confiança — passe-o a winapp sign como o segundo argumento posicional, com a sua palavra-passe em --password. Passa então a ser responsável por armazenar o material criptográfico da chave em segurança; guarde-o num token de hardware, num cofre de chaves ou no arquivo de segredos do seu fornecedor de CI, e nunca no repositório.

• A Loja Microsoft — se distribuir exclusivamente através da Loja, esta assina-lhe o pacote e não precisa de o assinar antes da submissão.

Em todos os casos, o titular do certificado deve corresponder ao valor Publisher no seu manifesto, incluindo nos pacotes esparsos.

Mantenha os segredos de assinatura fora do repositório

As palavras-passe dos certificados pertencem ao teu armazenamento secreto CI, não a um ficheiro de configuração. Leia-as do ambiente em vez de as codificar fixamente:

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

O mesmo se aplica à configuração de compilação registada no controlo de código-fonte, como uma configuração do Electron Forge — ver empacotamento do Electron. winapp az-sign Evita o problema por completo, porque não há palavra-passe para passar.

Antes de publicares

Uma breve lista de verificação para a transição dos testes locais para a distribuição:

• O pacote é assinado com um certificado emitido pela CA, Assinatura Confiável do Azure, ou submetido à Store — não com devcert.pfx.
• Nenhum ficheiro .pfx ou .cer se encontra na saída do pacote.
• Não aparece nenhuma palavra-passe de certificado em ficheiros comprometidos, scripts de compilação ou registos CI.
• O tema do certificado corresponde ao manifesto Publisher.
• Os certificados de desenvolvimento e o Modo Desenvolvedor não estão ativados em máquinas que só precisam de executar a aplicação.

Reportar um problema de segurança

Para reportar uma vulnerabilidade de segurança na própria linha de comando winapp, siga o processo em SECURITY.md. Por favor, não abra um problema público no GitHub para relatórios de segurança.

Tópicos relacionados

• Referência da CLI
• Depuração com identidade de pacote
• Empacotamento de um EXE/CLI
• Embalagem esparsa
• Empacotamento de eletrões
• Assinar um pacote de aplicação usando o SignTool
• Assinatura Confiável do Azure