Guía de seguridad

La CLI de winapp facilita el desarrollo local en Windows: puede generar un certificado de firma, instalarlo como de confianza en tu equipo y activar el modo de desarrollador automáticamente. Cada uno de esos pasos cambia el estado de la máquina o crea un archivo que contiene una clave privada, por lo que ayuda a saber exactamente lo que hacen.

En esta página se explica la consecuencia de cada comando, cómo deshacerlo y qué hacer de forma diferente al enviar. Los certificados de desarrollo y el modo de desarrollador son la ruta de acceso normal y compatible para las pruebas locales: el objetivo aquí es que comprenda lo que implica, no que los evite.

Certificados de desarrollo

Los paquetes MSIX deben estar firmados antes de que Windows los instale. Para las pruebas locales, winapp cert generate crea un certificado autofirmado para que pueda firmar e instalar su propio paquete sin comprar nada.

Lo que crea winapp cert generate

El certificado generado es un certificado de firma de código de entidad final autofirmado:

Propiedad Valor
Key RSA de 2048 bits, marcado como exportable
Algoritmo de firma SHA-256 con RSA (PKCS#1 v1.5)
Uso de claves Firma digital
Uso mejorado de clave Firma de código (1.3.6.1.5.5.7.3.3)
Restricciones básicas No es una autoridad de certificación
Validez 365 días de forma predeterminada (--valid-days)
Asunto Debe coincidir con el Publisher de su manifiesto.

El comando escribe dos cosas:

  • devcert.pfx en el directorio actual (o la ruta de acceso que se pasa a --output). Este archivo contiene ambos, el certificado y su clave privada.
  • Copia del certificado en el almacén de certificados personal (Cert:\CurrentUser\My).

Con --export-cer, también escribe un .cer archivo junto al .pfx. Ese archivo contiene solo el certificado público ,sin clave privada, lo que hace que sea lo correcto para un compañero de equipo o una máquina de prueba que necesite confiar en las compilaciones.

Note

Un certificado autofirmado no es de confianza para nadie hasta que alguien confíe explícitamente en él. Está bien para su propia máquina y sus propias máquinas de prueba; no es un sustituto de una identidad de firma de código real al distribuir la aplicación.

Contraseña predeterminada

winapp cert generate usa password como contraseña PFX a menos que proporcione --password. El mismo valor predeterminado se aplica cuando posteriormente se proporciona ese certificado a winapp sign, cuya opción de contraseña es también --password, y a winapp pack, que toma --cert-password.

Una contraseña conocida significa que la clave privada en devcert.pfx está efectivamente desprotegida; cualquier persona que obtenga el archivo puede firmar código con ella. Es una compensación aceptable para un certificado desechable que solo firma las compilaciones de pruebas locales en su propia máquina, y es por eso por lo que existe el valor predeterminado.

Importante

Trate la contraseña predeterminada como señal de que el certificado es descartable. Si se usa un certificado para firmar algo que otra persona instalará, no debe ser un winapp cert generate certificado con la contraseña predeterminada; consulte Firma para producción.

Los scripts y agentes no tienen que comparar ellos mismos la contraseña: winapp cert generate --json notifica "defaultPasswordIsPublic": true y repite la divulgación en un warnings array cuando genera un certificado con la contraseña predeterminada. Una ejecución que mantiene un archivo existente con --if-exists skip no lo abre, por lo que tampoco notifica ninguno de los dos. Consulte salida JSON de cert generate.

Dónde reside el archivo de certificado

devcert.pfx es una clave privada en el disco. Dos reglas lo mantienen fuera de problemas:

No lo confirmes.winapp cert generate anexa automáticamente el nombre de archivo del certificado al .gitignore siguiente, por lo que el flujo predeterminado ya está cubierto. Si mueve el archivo, cámbiele el nombre o lo genera en un directorio administrado por otro .gitignore, compruebe que la entrada lo haya seguido:

git check-ignore -v devcert.pfx

Si no imprime nada, el archivo no se ignora; agréguelo antes de hacer commit.

No lo empaquete.winapp pack empaqueta todo lo que hay en el directorio de entrada, por lo que un devcert.pfx ubicado en la carpeta de salida de la aplicación termina dentro del MSIX distribuido. Genere el certificado fuera de la carpeta que empaqueta, como se muestra en la guía Empaquetado de un EXE/CLI y confirme que 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

Tip

Si un .pfx con una clave privada real alguna vez se confirma o publica, rótelo: genere un nuevo certificado, vuelva a firmar y deje de confiar en el anterior mediante los pasos descritos en Eliminación de un certificado de confianza. Al eliminar el archivo de una confirmación posterior no se quita del historial.

¿Qué concede winapp cert install?

winapp cert install agrega el certificado al LocalMachine\TrustedPeople almacén de certificados. Esto requiere privilegios de administrador, ya que cambia la confianza para cada usuario de la máquina.

Una vez que un certificado está en TrustedPeople, Windows aceptará cualquier paquete MSIX firmado por ese certificado como lo suficientemente de confianza para instalar, no solo el paquete que estaba probando. Para un certificado cuya clave privada posee y conserva localmente, ese es exactamente el efecto previsto. También es la razón para hacerlo de forma intencionada:

  • Confíe en los certificados que generó usted mismo o que provengan de alguien a quien dejaría instalar software en la máquina.
  • No instale un certificado de desarrollo en máquinas compartidas, de producción o de compilación de las que dependen otras personas.
  • Prefiere distribuir la .cer (solo clave pública) en lugar de la .pfx cuando un compañero necesita instalar el paquete de prueba. Obtienen la capacidad de confiar en sus compilaciones sin obtener la capacidad de firmar como usted.

Para confiar en un .cer en otro equipo de prueba, ejecute winapp cert install directamente en él; el comando acepta un .pfx o un .cer que contenga solo la clave pública:

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

El equivalente que usa solo herramientas integradas de Windows es:

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

Eliminar un certificado de confianza

Los certificados de desarrollo expiran después de un año de forma predeterminada, pero la caducidad no equivale a la eliminación. Cuando haya terminado de usar un certificado —el proyecto finalizó, la máquina se va a reasignar o la clave puede haberse filtrado—, quítela explícitamente.

En primer lugar, busque su huella:

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

A continuación, quítelo del almacén de confianza de la máquina. Este paso necesita elevación:

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

cert generate también colocó el certificado, junto con su clave privada, en el almacén de certificados personales. Quite eso de un prompt normal y sin privilegios elevados, que inició sesión como la cuenta que ejecutó cert generate:

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

Importante

Ejecute los dos comandos anteriores en los contextos que se muestran. Si elevó usando una cuenta de administrador diferente, Cert:\CurrentUser en esa sesión con privilegios elevados es el almacén de ese administrador —no el suyo—, por lo que la clave privada se quedaría en el almacén del usuario que la generó.

Por último, elimine .cer y las copias .pfx que haya entregado, y anule el registro de los paquetes que haya instalado localmente con él:

winapp unregister

Note

Al quitar el certificado no se desinstalan los paquetes que ya se instalaron con él. Desinstale esos elementos por separado a través de Configuración > Aplicaciones > Aplicaciones instaladas, o con winapp unregister para paquetes registrados en modo de desarrollo.

Modo de programador

Windows requiere el modo de desarrollador para registrar un paquete de aplicación directamente desde una carpeta en el disco, un loose layout, en lugar de instalar un MSIX compilado y firmado. Los comandos, como winapp run y create-debug-identity, dependen de eso y fallan sin ello, y winapp init ofrece activarlo para usted.

Qué cambia al habilitarlo

La CLI habilita el modo de desarrollador escribiendo dos DWORD valores en HKEY_LOCAL_MACHINE:

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

Dado que se trata de una configuración para toda la máquina, la CLI inicia un proceso auxiliar con privilegios elevados y Windows muestra un mensaje de control de cuentas de usuario. No se cambia nada si rechaza el aviso.

Prácticamente, esto significa que la máquina hará lo siguiente:

  • Registre los paquetes de aplicación directamente desde una carpeta en el disco, sin que estén empaquetados en un MSIX ni firmados en absoluto (AllowDevelopmentWithoutDevLicense).
  • Instale paquetes de aplicaciones desde fuera de la Microsoft Store siempre que estén firmados por un certificado en el que confía la máquina, incluido cualquier certificado de desarrollo en TrustedPeople (AllowAllTrustedApps).

Importante

El modo de desarrollador más un certificado de desarrollo de confianza es una relajación deliberada de las restricciones de instalación predeterminadas. Esa combinación pertenece a las máquinas de desarrollo y pruebas. Déjelo desactivado en máquinas de producción, quioscos y infraestructura compartida.

Controlar cuándo está habilitado

winapp init pregunta antes de cambiar cualquier cosa y --use-defaults omite la pregunta por completo, dejando el modo de desarrollador intacto. Esto hace que las ejecuciones automatizadas y de CI sean seguras de forma predeterminada:

winapp init --use-defaults

Si prefiere administrar la configuración usted mismo, habilítelo una vez a través de Configuración > Sistema > Para desarrolladores > Modo de desarrollador y la CLI lo detectará y continuará.

Desactivación

Use Configuración > Sistema > Para desarrolladores y desactive el modo de desarrollador. Esta es la ruta de acceso recomendada, ya que La configuración también limpia el estado del sistema operativo asociado. Para confirmar el valor del registro a continuación:

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

Desactivar el modo de desarrollador no quita los certificados de confianza ni los paquetes ya instalados; consulte Eliminación de un certificado de confianza.

Firma para producción

Un certificado de desarrollo solo funciona para las personas que hayan confiado explícitamente en él. Para distribuir la aplicación, fírmela con una identidad en la que Windows ya confía.

Seleccione una identidad de firma

  • Firma de confianza de Azure: un servicio de firma administrado en la nube. La clave privada nunca existe en el equipo de compilación, por lo que no hay ninguna .pfx que proteger, filtrar ni rotar manualmente. Usa winapp az-sign, que se autentica con la cadena de credenciales estándar de Azure y funciona con Acciones de GitHub OIDC o una identidad administrada.

    winapp az-sign .\MyApp.msix

  • Un certificado de firma de código de una entidad de certificación de confianza — páselo a winapp sign como segundo argumento posicional, con su contraseña en --password. Después, usted es responsable de almacenar el material clave de forma segura; guárdelo en un token de hardware, un almacén de claves o el almacén de secretos del proveedor de CI y nunca en el repositorio.

  • La Microsoft Store — si distribuyes exclusivamente a través de la Tienda, la Microsoft Store firma el paquete por ti y no necesitas firmar antes del envío.

En cada caso, el sujeto del certificado debe coincidir con el valor Publisher del manifiesto, incluido para los paquetes dispersos.

Mantén los secretos de firma fuera del repositorio

Las contraseñas de los certificados deben estar en tu almacén de secretos de CI, no en un archivo de configuración. Léelos desde el entorno en lugar de codificarlos de forma rígida:

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

Lo mismo se aplica a la configuración de compilación registrada en el control de código fuente, como una configuración de Electron Forge; consulte Empaquetado de Electron. winapp az-sign evita el problema por completo, ya que no hay ninguna contraseña que pasar.

Antes de publicar

Una lista de comprobación breve para la transición de las pruebas locales a la distribución:

  • El paquete está firmado con un certificado emitido por una autoridad de certificación, Firma de confianza de Azure o enviado a la Tienda, no con devcert.pfx.
  • No hay ningún archivo .pfx o .cer en el paquete generado.
  • No aparece ninguna contraseña de certificado en archivos confirmados en el repositorio, scripts de compilación o registros de CI.
  • El titular del certificado coincide con el manifiesto Publisher.
  • Los certificados de desarrollo y el modo de desarrollador no están habilitados en las máquinas que solo necesitan ejecutar la aplicación.

Notificación de un problema de seguridad

Para notificar una vulnerabilidad de seguridad en la PROPIA CLI de winapp, siga el proceso en SECURITY.md. No abra un problema de GitHub público para reportar vulnerabilidades.

  • Se actualizó por última vez el