Guía de resolución de problemas para KeyLocker
KeyLocker es una poderosa herramienta de firma de código que permite almacenar su certificado de firma de código en la nube y firmar de manera segura su huella hash de manera remota. Sin embargo, la configuración inicial tiene ciertas dificultades que este artículo ayudará a resolver.
Verificación de variables
Un paso crucial para el funcionamiento de KeyLocker en su sistema es la configuración correcta de las variables. Estas no solo determinan la ruta a las herramientas de firma, sino que también llevan los datos de autenticación. Puede configurarlas para una sesión o de manera permanente.
Puede asignar las variables al sistema de diferentes maneras. Además de un archivo y variables independientes, también puede almacenarlas en el Administrador de Credenciales de Windows. Si desea firmar mediante la interfaz gráfica, puede configurarlas en la utilidad Click-to-sign, que encontrará en la cuenta de KeyLocker (sin embargo, las variables no funcionarán a nivel del sistema).
Configurar una variable en Windows es fácil usando la línea de comandos. Ejecute cmd y escriba setx VARIABLE=valor. Atención: setx funciona con variables de usuario, no del sistema.
Para el correcto funcionamiento de KeyLocker, es necesario configurar las variables para la autenticación del cliente + ubicación de las herramientas y bibliotecas de firma de DigiCert.
Configuración de autenticación
- SM_CLIENT_CERT_FILE - ruta a la ubicación del certificado de autenticación con la extensión p12, que descargó del asistente en DigiCert ONE
- SM_HOST - dirección del host de DigiCert ONE, que es https://clientauth.one.digicert.com
Estas dos variables no son secretas porque el certificado está protegido con contraseña. Puede configurarlas en el sistema sin problemas. Las siguientes dos variables sí son secretas y es recomendable no configurarlas en el sistema si más usuarios tienen acceso a él. Es mejor almacenarlas en el administrador de contraseñas de Windows. Más información sobre la configuración de variables para Windows en el artículo Credential setup for Windows.
- SM_API_KEY - clave API, que generó en la interfaz de DigiCert ONE
- SM_CLIENT_CERT_PASSWORD - contraseña del certificado de autenticación en P12, que se le mostró una vez en el asistente de DC1
Configuración de la ruta a las herramientas de firma
La adición de un valor a la variable PATH se realiza con el comando setx PATH "ruta;%PATH%". Este comando agrega un nuevo valor a los valores de usuario existentes de la variable PATH y lo guarda permanentemente. Para el correcto funcionamiento de KeyLocker, se necesitan configurar al menos dos:
- Ruta a Windows SDK y signtool
- Ruta a DigiCert Keylocker Tools
Averigüe la ruta válida al Windows SDK (la ruta utiliza el número de versión que tiene instalado). También necesitará DigiCert Keylocker Tools, que descargó e instaló desde DigiCert ONE; los encontrará en C:\Program Files\DigiCert\DigiCert Keylocker Tools.
Vamos a agregar ambas variables al mismo tiempo a través de CMD, de lo contrario una sobrescribirá a la otra:
setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"También puede configurar las variables del sistema a través de la GUI de Windows; a través de CMD es más rápido, pero los valores se sobrescriben si se introducen múltiples veces. También es posible usar PowerShell.
Cómo modificar manualmente la variable PATH en Windows
Si desea asegurarse de que los valores se mantengan, puede modificar PATH manualmente:
- Abra Panel de control → Sistema → Configuración avanzada del sistema.
- Haga clic en Variables de entorno.
- Encuentre PATH (en Variables del sistema o Variables de usuario).
- Haga clic en Editar, agregue las rutas individuales y guarde.
Cómo agregar la variable PATH usando PowerShell
Si desea agregar permanentemente una ruta a la variable PATH usando PowerShell, siga estos pasos:
- Abra PowerShell como administrador (haga clic derecho en Inicio → Windows PowerShell (Admin)).
- Primero obtenga el valor actual de la variable "PATH":
[System.Environment]::GetEnvironmentVariable("Path", "User") - Luego, agregue una nueva ruta a los valores existentes:
$path = [System.Environment]::GetEnvironmentVariable("Path", "User") $newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\" [System.Environment]::SetEnvironmentVariable("Path", $newPath, "User") - Si necesita agregar otra ruta, repita el proceso:
$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\" [System.Environment]::SetEnvironmentVariable("Path", $newPath, "User") - Después de ejecutar los comandos, reinicie la línea de comandos o la computadora para que los cambios se apliquen.
Nota: Si desea cambiar la variable del sistema "PATH" (válida para todos los usuarios), reemplace "User" por "Machine" en el comando.
Atención: Después de establecer las variables a través de CMD, reinicie la línea de comandos, de lo contrario, los cambios no se aplicarán.
Verificación del valor de la variable en cmd: echo %VARIABLE% Por ejemplo, "echo %PATH%". Luego, cmd le mostrará su valor.
Verificación de la configuración correcta
Las herramientas KeyLocker incluyen la utilidad smctl, con la que puede firmar, pero también se utiliza para diagnóstico básico. El siguiente comando verificará si todo está configurado correctamente en la estación y si smctl puede conectarse con la nube de DigiCert:
smctl healthcheckEn la salida verá confirmación de si se ha conectado a KeyLocker (autenticación funcionando) y si smctl detecta la presencia de herramientas de firma, como signtool. Ejemplo:
smctl healthcheck
--------- Account Settings ---------
Teams: Disabled
Threat detection: Enabled
Static Binary Analysis: Enabled
Software Composition Analysis: Disabled
--------- User credentials ---------
Status: Connected
Username: XXXX-keylocker
Accounts: XXXX-1699076
Authentication: 2FA
Environment: Prod
Credentials:
Host: https://clientauth.one.digicert.com
API key: 010897bf735bbc57d48270cd3d_50dxxxxx...e4 (Pulled from environment variable)
Client certificate file path: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
Client certificate password: ytf_xxxxxx0F (Pulled from environment variable)
API keys:
Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
Client certificates:
Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
Privileges:
Can sign: Yes
Can approve offline release: No
Can revoke certificate: Yes
Can scan: No
--------- Signing tools ---------
Signtool 32 bit:
Mapped: No
Signtool:
Mapped: Yes
Path: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe
Mage:
Mapped: No
Nuget:
Mapped: No
Jarsigner:
Mapped: No
Apksigner:
Mapped: NoSi hay algún problema con la autenticación, verifique si configuró los valores correctamente que obtuvo en el asistente de KeyLocker en la interfaz de DigiCert ONE. Si tiene dudas, puede restablecer el asistente y crear nuevas credenciales.
También puede encontrar que smctl no detecta signtool u otras herramientas de firma. Esto significa que debe agregar su ubicación a la variable PATH del usuario o sistema. Vea arriba en la sección sobre variables.
MMC y verificación de presencia del certificado
Si trabaja en Windows, eche un vistazo al administrador de certificados, que puede iniciar con el comando certmgr.msc. Si la sincronización con KeyLocker se realizó correctamente, verá un certificado con un indicador de clave privada en la tienda de certificados. Sin embargo, esto no significa que realmente esté allí con la clave privada; el certificado con la clave privada todavía está almacenado en la nube.
Si el certificado no está allí, ejecute la sincronización.
smctl windows certsyncCon una sincronización exitosa, verá una confirmación:
Sincronizando certificado para el alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db y Huella SHA1: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72cProblemas con la firma
Si tiene problemas con la firma, intente resolverlos desde lo más general hasta lo más complejo. Lo más sencillo es firmar utilizando la utilidad smctl de DigiCert, que puede servir como una superposición para herramientas de firma como signtool o jarsigner. Este es el método con menos conflictos y no necesita parámetros. Para resolver problemas, no utilice timestamp ni otras opciones.
La firma con smctl se realiza fácilmente:
smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exePuede referirse al certificado mediante el parámetro "keypair-alias" o "fingerprint"; encontrará esta información sobre el certificado, por ejemplo, con el comando smctl windows certsync.
Después de firmar, puede verificar la firma:
smctl sign verify --input <path to signed file or folder>Consulte el artículo de ayuda para firmar en el artículo Sign binaries with SMCTL.
Después de firmar con éxito con smctl, puede intentarlo con otra herramienta, como signtool. Este también debería funcionar. Deje que la selección de certificados se haga automáticamente y agregue gradualmente más parámetros.
Cuando funcione con éxito según sus preferencias, puede intentar firmar con Visual Studio u otro entorno de desarrollo.
Dónde encontrar los registros
Si todo lo anterior falla y la firma no funciona, le recomiendo que consulte los registros de smctl y otras herramientas de DigiCert. Si utiliza registros al resolver un problema con nuestro soporte, definitivamente acelerará la resolución del problema.
El registro de la utilidad smctl se encuentra en el archivo smctl.log, que estará ubicado en la carpeta /.signingmanager/logs en el perfil del usuario dado. Intente escribir en cmd echo %USERPROFILE%/.signingmanager/logs y verá la ubicación completa de la carpeta.
Otros recursos e información
- Errores comunes - Guía de resolución de problemas en la documentación de KeyLocker.
- Documentación de KeyLocker en el sitio web de DigiCert
¿Tiene preguntas?
No dude en contactar a nuestro soporte al cliente, que le asesorará y le ayudará.
ZONER, S.A.
¿Le resultó útil este artículo?
Gracias por su feedback en este artículo.
Lo sentimos que no haya encontrado lo necesario aquí.
Ayúdanos mejorar el artículo, por favor. Escríbenos lo que esperaba aquí y no encontró.