Cómo integrar CodeSign Secure con tu canalización de CircleCI

La fiabilidad de cualquier software implementado depende del proceso que lo generó. La firma de código es fundamental para esa confianza: demuestra que un archivo binario no ha sido manipulado y que proviene genuinamente de su organización. Sin embargo, firmar manualmente las compilaciones es propenso a errores y ralentiza al equipo. La mejor opción es integrar la firma directamente en su canalización de CI/CD , de modo que se realice de forma automática, consistente y segura en cada compilación.

Esta guía le muestra cómo integrar CodeSign Secure de Encryption Consulting con CircleCI utilizando Signtool de Microsoft y un ejecutor de CircleCI autohospedado en una máquina Windows. Con estos pasos de integración, su canalización firmará automáticamente cada compilación utilizando claves almacenadas de forma segura en la plataforma de CodeSign Secure con respaldo HSM , sin que las claves privadas queden expuestas en la máquina de compilación.

Integración de firma de código de CircleCI, definida: un ejecutor de CircleCI para Windows autohospedado que llama a signtool.exe de Microsoft a través del proveedor de almacenamiento de claves (KSP) de Encryption Consulting, que enruta cada solicitud de firma al HSM de CodeSign Secure a través de un canal autenticado, de modo que la máquina de compilación maneja un resumen y una firma, pero nunca la clave privada en sí.

Puntos Clave

• Este es un tutorial específico de la plataforma CircleCI. Para la arquitectura general detrás de la firma CI/CD sin secretos y respaldada por HSM (identidad, puertas de aprobación, patrones de verificación que se aplican a cualquier plataforma CI/CD), consulte Fortalecimiento de la seguridad de la cadena de suministro con SLSA Nivel 3 y firma de código..
• La clave privada nunca sale del HSM de CodeSign Secure; el programa de Windows solo gestiona un resumen y la firma resultante, a través del KSP de EC que actúa como proveedor CNG para signtool.exe.
• El token de API y el certificado de autenticación P12 creados durante la configuración son credenciales de producción, no valores desechables; trátelos con la misma disciplina de rotación y acceso que cualquier otro secreto de CI/CD.
• Esto requiere un ejecutor de Windows autohospedado porque signtool.exe y el EC KSP son nativos de Windows; las clases de recursos de Linux/macOS alojadas en la nube de CircleCI no pueden ejecutar esta integración directamente.

Arquitectura de referencia

Antes de los pasos de configuración, conviene ver cómo encajan las piezas. Una confirmación activa la canalización de CircleCI en la nube, que envía la tarea de firma al ejecutor de Windows autohospedado. En ese ejecutor, signtool.exe no almacena una clave propia; se conecta a través de EC KSP, un proveedor de CNG para Windows que Encryption Consulting instala específicamente para conectar signtool con claves remotas respaldadas por HSM. El KSP se autentica en CodeSign Secure mediante el token de API y el certificado P12 configurados durante la configuración, envía el hash del artefacto y recibe una firma calculada dentro del HSM. El artefacto firmado es lo que regresa a la canalización; la clave privada permanece dentro del perímetro del HSM de CodeSign Secure en todo momento.

Lo que necesitará

Antes de comenzar, asegúrese de tener lo siguiente:

• Un activo CodeSign seguro cuenta con acceso al portal
• Una máquina Windows que actuará como ejecutor de CircleCI autohospedado.
• Una cuenta de CircleCI
• Un repositorio de GitHub (u otro compatible) para conectar con tu proyecto CircleCI.
• Acceso de administrador en la máquina Windows para instalar herramientas.

Qué cubre esta guía

La estructura se divide en cuatro secciones principales, cada una de las cuales se basa en la anterior:

• Configuración del EC KSP — Instale y configure el proveedor de almacenamiento de claves de Encryption Consulting en su máquina Windows.
• Configuración de la autenticación P12 — Crear un certificado de autenticación de máquina y configurar las variables de entorno.
• Configuración de Signtool — Instale el SDK de Windows y configure su entorno para que apunte a Signtool.exe.
• Configuración y ejecución de CircleCI — Crea la configuración de tu organización, ejecutor, proyecto y canalización para conectar todo.

Configurar CodeSign Secure KSP

El proveedor de almacenamiento de claves (KSP) de Encryption Consulting para Windows es un componente de software que amplía el marco de trabajo de la API de criptografía de próxima generación (CNG) de Microsoft. Su objetivo principal es permitir que las aplicaciones de Windows, como signtool.exe, interactúen sin problemas con las claves y certificados criptográficos almacenados en un módulo de seguridad de hardware (HSM).

Pasos:

1. Descarga el EC KSP

• Inicie sesión en el portal CodeSign Secure y diríjase a la sección Herramientas de firma para descargar “EC KSP para Windows”.

  
• Extraiga el archivo zip para obtener el archivo “Setup.msi”.

2. Instale el EC KSP

• Ejecute el instalador “Setup.msi” con privilegios de administrador.

  
• Siga las instrucciones en pantalla del asistente de instalación.
  1. Acepte el Acuerdo de licencia de usuario final.
  2. Elija el directorio de instalación (el predeterminado es C:\Program Files\Encryption Consulting\SigningKSP).

  3. Elige si quieres instalar KSP para todos o solo para el usuario actual.

     
• Ingrese los detalles solicitados, como:
  1. Nombre de usuario – El nombre de usuario/correo electrónico que utiliza para iniciar sesión en el portal CodeSign Secure.
  2. Código – El código secreto que usted estableció al configurar la solución CodeSign Secure.
  3. Tipo de identidad – Mantener este campo como predeterminado (2).

  4. URL segura de CodeSign : la URL para acceder al portal (recuerde agregar “/api/” al final de la URL).

     

• Haga clic en Siguiente y confirme la instalación.

  

3. Configure los ajustes del Editor del Registro.

• Abra el Editor del Registro y navegue hasta HKEY_CURRENT_USER > Software > Encryption Consulting > SigningKSP directorio.

  

• Ahora abre el portal CodeSign Secure y ve a Configuración del sistema > Usuario . Selecciona la opción "Generar clave API".

  

• Crea un token para tu cuenta indicando el nombre y el período de validez. Recuerda copiar el token, ya que solo se mostrará una vez.

  

• Agregue este token al campo "ectoken" en el Editor del Registro.

  

Nota de privilegio mínimo

El token de API que acaba de generar se autentica como la cuenta que lo creó. En lugar de generarlo desde una cuenta de administrador personal, cree una cuenta de servicio dedicada, limitada únicamente a las operaciones de firma que requiere esta canalización, y asígnele su propio token. De esta forma, revocar el acceso a esta canalización específica o auditar lo que ha firmado no requiere modificar todas las demás credenciales vinculadas a la cuenta de una persona real.

Configurar el certificado de autenticación P12

Configurar un certificado P12 implica configurar las variables de entorno para autenticar la máquina cliente con CodeSign Secure de Encryption Consulting.

Pasos:

1. Crear un certificado de autenticación de máquina.

• Abra el portal CodeSign Secure y vaya a Configuración del sistema > Usuario . Seleccione la opción "Generar certificado de autenticación".

  
• Seleccione el nombre de usuario en el menú desplegable e introduzca los datos, como el nombre del certificado y su fecha de caducidad.
• Luego te proporcionará una .pfx archivo de certificado y también muestra la contraseña del archivo de certificado.

  NOTA: Esta contraseña se mostrará solo una vez. Por lo tanto, debe copiarla y guardarla en un lugar seguro para autenticarse con el servidor CodeSign Secure.

  

2. Configurar las variables de entorno

• Abre las variables de entorno desde el menú Inicio.

  
• Agregue nuevas variables del sistema haciendo clic en el New botón. Proporcione el siguiente nombre de variable y sus detalles correspondientes.
  1. Autenticación de cliente EC: Corresponde a la ruta de su certificado de autenticación SSL, que puede crearse desde CodeSign Secure.
  2. Contraseña del cliente EC: Corresponde a la contraseña de su certificado, que se proporciona en el momento de la creación del mismo.
  3. EC_SSL_VERBOSE: Corresponde a la configuración para habilitar (1) o deshabilitar (0) la salida de depuración para EC KSP.
  

Configurar Signtool para firmar

Configurar Signtool para la firma de código implica asegurarse de que la utilidad Signtool.exe esté disponible en su equipo y configurada para interactuar correctamente con el proveedor criptográfico de Encryption Consulting, que proporciona acceso a la clave privada de su certificado de firma de código.

Pasos:

1. Descarga e instala el SDK de Windows.

• Utilice el siguiente enlace de descarga para descargar el Kit de desarrollo de software de Windows: Descargas del SDK de Windows – Aplicaciones de Windows | Microsoft Learn

  

• Una vez descargado el instalador, ábrelo y selecciona "Siguiente" en la primera pantalla para mantener la configuración predeterminada.

  
• Siga las instrucciones en pantalla del asistente de instalación.
  1. Acepte la privacidad del kit de Windows.
  2. Acepte el Acuerdo de licencia de usuario final.

• Deseleccione todo excepto “Herramientas de firma del SDK de Windows para aplicaciones de escritorio” y seleccione “Instalar”.

  

• Diríjase a la siguiente ruta donde deberían haberse descargado las herramientas: C:\Program Files (x86)\Windows Kits\10\bin. Seleccione el directorio de versión deseado y compruebe si el “signtool.exe” el archivo está presente.

  
• Asegúrese de estar en el x64 directorio y copie esta ruta de directorio.

2. Agregue la ruta a Signtool.exe en las variables de entorno.

• Abra las variables de entorno desde el menú Inicio.

  

• Desplácese hacia abajo en la tabla inferior, donde encontrará las variables del sistema, hasta que encuentre PATH en los nombres de las variables.

  

• Haz doble clic en PATH en las variables del sistema y selecciona Nuevo en el lado izquierdo de la pantalla. Pega la ruta del directorio que copiaste de “signtool.exe” en la nueva selección.

  
• Seleccionar OK en la parte inferior para salir de la página Variables de entorno.

Configurar CircleCI

Configurar CircleCI requiere configurar la organización, configurar el proyecto y, específicamente, las máquinas de compilación con los ejecutores y las canalizaciones para firmar archivos usando signtool en una máquina Windows.

Pasos:

1. Crea una organización de CircleCI.

• Acceda a CircleCI e inicie sesión con su cuenta. A continuación, verá las opciones para crear una nueva organización o elegir una ya existente. En esta guía, crearemos una nueva organización.

  

• Ingrese el nombre único de la organización.

  

• A continuación, te llevará a la página de inicio de tu organización en la cuenta de CircleCI.

  

2. Crea una clase de recursos para un ejecutor autoalojado.

• Seleccione la sección "Corredores" en la barra lateral izquierda.

  

• En primer lugar, se le pedirá que revise y confirme los términos y condiciones, tras lo cual podrá crear una clase de recursos para el corredor.

  

• A continuación, te redirigirá de nuevo a la sección de Corredores para crear una clase de recursos.

  

• Haz clic en "Guardar y continuar" y se te proporcionará el token de autenticación.

  NOTA: Copie y guarde este token de forma segura, ya que lo necesitaremos en los siguientes pasos para autenticar al ejecutor con la canalización de CircleCI.

  

• Haz clic en “Continuar” para añadir a este corredor a tu organización.

  

3. Instale el programa Runner en su máquina Windows.

• Una vez obtenido el token, debemos instalar un ejecutor autohospedado en nuestra máquina. En esta máquina se instalarán y configurarán Signtool y ECSigningKSP.

• Descarga el script “Install-CircleCIRunner.ps1” desde GitHub en esta máquina.

  
• Abra PowerShell como administrador y navegue hasta el directorio donde colocó el archivo de script.
• Ejecute el siguiente comando:
  1. Copiar

     Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;

  2. Copiar

     ./Instalar-CircleCIRunner.ps1;

• Como parte de la instalación, el archivo de configuración del agente de ejecución (runner-agent-config.yaml) se abrirá en el Bloc de notas. Complete la información solicitada. El archivo de configuración se encuentra, por defecto, en el directorio de instalación: C:\Archivos de programa\CircleCI.

• Introduzca el token de autenticación que creamos al crear la clase Resource.

  
• Una vez completada la configuración del ejecutor, este se iniciará automáticamente y comenzará a buscar trabajos.

• Podrás ver un corredor en la página de CircleCI.

  

4. Crea un proyecto y configura un Pipeline.

• Ahora volvemos a la página de inicio de la organización para crear un proyecto e inicializar el flujo de trabajo.

  

• Haz clic en "Crear un proyecto" y selecciona la opción "Compilar, probar e implementar tu aplicación de software".

  

• Introduzca el nombre del proyecto y haga clic en la opción "Siguiente: configurar una canalización".

  

• Indique el nombre de la canalización y haga clic en la opción "Siguiente: elegir un repositorio".

  

• Puedes elegir a qué repositorio conectar tu canalización. En esta guía, utilizaremos un repositorio de GitHub.

  

• Selecciona el repositorio después de conectar tu cuenta de GitHub con CircleCI Pipeline.

  

• Haz clic en la opción "Preparar archivo de configuración" para enviar un archivo YAML de configuración de ejemplo a una nueva rama en tu repositorio conectado.

  

• A continuación, se mostrará un repositorio de ejemplo. Haga clic en la opción "Siguiente: configure sus activadores".

  

• Puedes configurar los activadores según tus necesidades. Dejaremos esta configuración por defecto, de modo que la canalización se ejecute con cada nueva confirmación. Haz clic en la opción "Siguiente: revisar y finalizar la configuración".

  

• Revisa tu configuración y haz clic en la opción "Confirmar configuración y ejecutar".

  

• Se ejecutará el proceso con este archivo de configuración de ejemplo para probarlo.

  

• Puedes ver tu flujo de trabajo en la sección "Flujos de trabajo" de la barra lateral izquierda.

  

5. Actualizar la configuración de la canalización

• Ahora actualizaremos el archivo config.yml en nuestra rama del repositorio para ejecutar el comando signtool y realizar la firma.

• Siga la siguiente estructura del archivo config.yml para ejecutar el comando signtool a través de la canalización de CircleCI:

  

• Aquí tiene un archivo config.yml funcional como referencia, que coincide con los detalles que utilizamos en los pasos anteriores para configurar la clase de recurso y signtool.

  

• Cuando confirmes esta actualización del archivo de configuración en la rama de tu repositorio, el ejecutor debería iniciar la canalización automáticamente.

  

6. Ejecutar la canalización de CircleCI

• Una vez que se haya confirmado el archivo, verá una nueva ejecución de la canalización en la sección Canalización.

  

• Una vez finalizado correctamente el proceso, puede comprobar las propiedades del archivo que debía firmarse para verificar que la firma sea válida.

  

Verificación desde la línea de comandos

Comprobar el cuadro de diálogo Propiedades del Explorador de Windows funciona para una comprobación puntual, pero para un paso de la canalización se necesita un comando que devuelva un resultado claro de aprobado/reprobado. Añada un paso de verificación después de la firma utilizando el comando verify de signtool:

signtool.exe verificar /v /pa ruta\a\tu-archivo-firmado.exe

Una verificación exitosa imprime el sujeto del certificado de firma y confirma que la firma es válida; un fallo indica el motivo específico (no se encontró firma, la cadena no se valida o el certificado fue revocado). Un código de salida distinto de cero de este comando se interpreta como un fallo en la canalización, no como una advertencia para verificar manualmente más adelante.

Manejo de fallos y reversión

Si el paso de firma falla, ya sea por un error de autenticación de KSP, un certificado P12 caducado o la inaccesibilidad del servicio CodeSign Secure, la canalización debería cerrarse: el artefacto de compilación no debería publicarse ni promocionarse. Dado que esta integración no modifica el código fuente ni las versiones firmadas existentes, la reversión es sencilla: se corrige el fallo (se renueva el certificado, se restablece la conectividad y se vuelve a ejecutar el instalador del ejecutor si el token ha caducado) y se vuelve a ejecutar la canalización. No hay ningún artefacto firmado que anular o revocar, a menos que se haya firmado y distribuido por error una compilación defectuosa, en cuyo caso se trata de un incidente relacionado con el certificado, no con la configuración de la canalización.

Evidencia de auditoría

Cada solicitud de firma que llega a CodeSign Secure a través de esta integración se registra en CodeSign Secure, capturando la identidad del solicitante (la cuenta de servicio vinculada al token de la API), el hash del artefacto, el certificado utilizado y la marca de tiempo, independientemente de lo que muestren los registros de compilación de CircleCI. Al investigar una versión, compare el historial de ejecución de la canalización de CircleCI con el registro de firma de CodeSign Secure para ese mismo período; ambos deberían coincidir en qué se firmó y cuándo.

Localización de averías

Síntoma	Causa probable	Qué comprobar
Signtool informa que no puede encontrar el certificado.	EC KSP no está registrado correctamente o el token de registro no se guardó.	Vuelva a comprobar las entradas del registro HKEY_CURRENT_USER > Software > Encryption Consulting > SigningKSP
La autenticación falla con CodeSign Secure.	El certificado P12 ha caducado o las variables de entorno EC_Client_Auth/EC_Client_Pass son incorrectas.	Confirma la fecha de caducidad del certificado y que las rutas de las variables de entorno coincidan con la ubicación real del archivo .pfx.
Runner aparece como desconectado en CircleCI.	El servicio de ejecución autohospedado se detuvo o el token de autenticación utilizado durante la instalación caducó.	Verifique el proceso del ejecutor en la máquina Windows y vuelva a ejecutar el script de instalación con un token nuevo si es necesario.
La firma funciona localmente, pero falla únicamente en la canalización.	Las variables de entorno configuradas para una cuenta de usuario no son visibles para el contexto de servicio del ejecutor.	Confirme que EC_Client_Auth, EC_Client_Pass y la entrada PATH de signtool estén configuradas como variables del sistema, no como variables exclusivas del usuario.

Firma manual frente a esta integración

Aspecto	Firma manual	CircleCI + CodeSign Secure
¿Quién puede firmar?	Cualquier persona con acceso local a la clave o token	Solo la canalización, utilizando una cuenta de servicio con ámbito definido.
Consistencia	Depende de la persona que recuerde cada bandera y certificado	El mismo paso de firma en cada compilación.
Registro de auditoría	Cualquier cosa que la persona haya documentado	Registrado automáticamente en CodeSign Secure, independientemente de los registros de la canalización.
Exposición clave	A menudo se trata de un archivo local o un token en la máquina del desarrollador.	Nunca sale del HSM de CodeSign Secure.

Preguntas frecuentes

¿Por qué esto requiere un ejecutor de Windows autohospedado en lugar de un ejecutor en la nube de CircleCI?

Signtool.exe y EC KSP son componentes nativos de Windows; las clases de recursos de Linux y macOS alojadas en la nube de CircleCI no pueden ejecutarlos. Un ejecutor de Windows autoalojado es lo que permite que la canalización envíe trabajos de firma a una máquina con las herramientas adecuadas instaladas.

¿La clave privada llega alguna vez al ejecutor de CircleCI?

No. El proveedor de servicios de clave pública de la CE solo envía el hash del artefacto a CodeSign Secure y recibe una firma a cambio; la clave privada permanece dentro del HSM durante todo el proceso.

¿Qué debo hacer si caduca el token de la API o el certificado P12?

Genere uno nuevo desde el portal CodeSign Secure siguiendo los mismos pasos que utilizó inicialmente, actualice la entrada del registro o la variable de entorno y confirme que la firma se realiza correctamente con una compilación de prueba antes de utilizarla para las versiones de producción.

¿Puedo utilizar este mismo patrón para otras plataformas de CI/CD?

La configuración de EC KSP y signtool es la misma independientemente de la plataforma de CI/CD que gestione la tarea; solo los pasos de registro del ejecutor y configuración de la canalización son específicos de CircleCI. Consulte nuestras guías para Azure DevOps , Jenkins y GitLab CI.

Conclusión

Ahora has configurado una canalización de firma de código totalmente automatizada con CircleCI y CodeSign Secure . Cada vez que un desarrollador realiza una confirmación en tu repositorio, la canalización se activa, ejecuta la tarea en tu servidor Windows autohospedado y firma el resultado con Signtool, todo ello sin que nadie tenga que gestionar manualmente una clave privada. Este enfoque ofrece importantes ventajas para tu equipo, como consistencia, seguridad y auditabilidad. A partir de aquí, puedes ampliar esta configuración para incluir varias canalizaciones, certificados de firma adicionales u otras plataformas de CI/CD.

Si tiene algún problema o desea explorar configuraciones más avanzadas, el equipo de Consultoría de Cifrado está a su disposición. Regístrese para una demostración o póngase en contacto con el equipo de Consultoría de Cifrado en www.encryptionconsulting.com para descubrir cómo CodeSign Secure puede hacer que la cadena de suministro de software de su organización sea segura y eficiente.