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

La fiabilidad de cualquier software implementado depende exclusivamente del proceso que lo produjo. Firma de código Se encuentra en el centro de esa confianza: demuestra que un binario no ha sido manipulado y que realmente proviene de su organización. Pero firmar manualmente las compilaciones es propenso a errores y ralentiza a su equipo. El mejor camino es incorporar la firma directamente a su Canalización de CI / CD, de modo que sucede 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 CodeSign Secure. HSMPlataforma con respaldo de seguridad, sin que las claves privadas se expongan en ningún momento en la máquina de compilación.

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 de consultoría de cifrado (KSP) para Windows es un componente de software que extiende el marco de la API de criptografía de Microsoft: próxima generación (CNG). Su propósito principal es permitir que las aplicaciones de Windows, como signtool.exe, interactúen sin problemas con las claves criptográficas y certificados almacenado dentro de un 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 (Recuerda añadir “/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 abra el portal CodeSign Secure y navegue hasta Configuración del sistema > UsuarioSeleccione 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 “ectoken” campo en el Editor del Registro.

  

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 navegue hasta Configuración del sistema > UsuarioSeleccione 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 de forma segura 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

Configuración herramienta de señalización Para la firma de código, es necesario 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 a través de las variables del sistema en la tabla inferior hasta que encuentre TRAYECTORIA en los nombres de las variables.

  

• Haga doble clic en TRAYECTORIA en variables del sistema y seleccione New en la parte izquierda de la pantalla. Pegue la ruta del directorio que copió. “signtool.exe” en la nueva selección.

  
• Seleccione 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: Copia y guarda 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.

  

Conclusión

Ahora has configurado una canalización de firma de código totalmente automatizada con CircleCI y CodeSign seguroCada 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 abarcar 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.