Buena parte del software de firma electrónica que circula en Ecuador corre sobre la máquina virtual de Java: el firmador oficial del Estado, los componentes de varios sistemas públicos y no pocos emisores de comprobantes desarrollados a la medida. Si tu equipo trabaja en ese ecosistema, tarde o temprano tiene que entender el almacén de claves de Java, porque es la puerta por la que el certificado entra al proceso.
Es un tema con más trampas de las que aparenta: dos contraseñas distintas, formatos que cambiaron con las versiones del lenguaje, un almacén de confianza que nadie recuerda actualizar y mensajes de error que no dicen lo que parece. Este artículo ordena todo eso desde la perspectiva de un servidor que firma sin supervisión humana.
Almacén de claves y almacén de confianza: dos cosas distintas
La confusión inicial más costosa. Son dos archivos con propósitos opuestos:
- El almacén de claves guarda tu identidad: el certificado del firmante junto con su clave privada. Es lo que se usa para firmar y es material sensible.
- El almacén de confianza guarda certificados de otros: las raíces de las autoridades que tu aplicación considera confiables. Solo contiene información pública y sirve para validar, no para firmar.
Cuando una aplicación Java no logra establecer una conexión segura con el servicio del SRI, el problema casi siempre está en el segundo. Cuando no logra firmar, en el primero. Distinguirlos ahorra horas de diagnóstico en la dirección equivocada.
Formatos: el cambio que rompió instructivos viejos
Durante años el formato propietario de Java fue el predeterminado. Con el tiempo, la plataforma pasó a usar por defecto el formato estándar de la industria, el mismo de los archivos .p12 que entrega una entidad de certificación. Esto tiene dos consecuencias prácticas:
| Formato | Extensión habitual | Portabilidad | Recomendación |
|---|---|---|---|
| Propietario de Java | .jks | Solo el ecosistema Java | Solo para compatibilidad con sistemas antiguos |
| Estándar PKCS#12 | .p12 o .pfx | Java, .NET, navegadores, herramientas de línea de comandos | El formato a usar en proyectos nuevos |
La buena noticia operativa: el .p12 que emite la entidad de certificación se puede cargar directamente como almacén de claves, sin conversión previa. Muchos manuales antiguos indican convertirlo primero al formato propietario; ya no hace falta y ese paso extra genera copias del certificado en lugares que después nadie limpia.
Cargar el certificado desde código
El flujo conceptual es corto:
- Se obtiene una instancia del almacén indicando el tipo.
- Se lo carga desde un flujo de entrada con la contraseña del almacén.
- Se identifica el alias de la entrada que interesa.
- Se recupera la clave privada de ese alias, usando la contraseña de la clave.
- Se obtiene también la cadena de certificados asociada, que hay que incluir al firmar.
Dos advertencias que explican la mayoría de los tickets de soporte. Primera: hay dos contraseñas, la del almacén y la de cada entrada de clave. En los .p12 que entrega una entidad de certificación suelen coincidir, pero un almacén armado a mano puede tenerlas distintas y el mensaje de error no lo aclara. Si el desconcierto es al revés —la contraseña parece correcta y no funciona— el diagnóstico está en la contraseña es correcta y no entra.
Segunda: no supongas el alias. Varía entre emisiones y no siempre es un nombre legible. Lo correcto es enumerar las entradas del almacén y seleccionar la que tenga clave privada, o filtrar por el titular del certificado. Un alias en duro en el código es una bomba de tiempo que estalla en la primera renovación.
La herramienta de línea de comandos
El utilitario que viene con la plataforma resuelve las tareas de inventario sin escribir código. Con él se puede listar el contenido de un almacén y ver alias, titular, emisor, vigencia y huella; importar un certificado al almacén de confianza; y convertir entre formatos cuando toca convivir con sistemas viejos.
Un consejo de operación: documenta el listado del almacén de producción —alias, titular y fecha de vencimiento— en el mismo lugar donde vive el inventario de certificados de la empresa. Sin eso, el día que el certificado vence nadie sabe qué archivo hay que reemplazar ni en qué servidores está copiado.
El almacén de confianza y las raíces ecuatorianas
Cuando tu aplicación valida firmas de terceros o se conecta a servicios externos, necesita reconocer las autoridades correspondientes. La plataforma trae un almacén de confianza con raíces preinstaladas, pero las de las entidades de certificación acreditadas del país no necesariamente están ahí.
Si vas a validar firmas emitidas en Ecuador, tienes que incorporar esas raíces de forma explícita. Cómo hacerlo bien:
- Usa un almacén de confianza propio de la aplicación, no el del sistema. Modificar el archivo global obliga a repetir el cambio en cada actualización de la plataforma y en cada servidor nuevo.
- Versiona ese almacén junto al despliegue. Contiene solo información pública, así que puede vivir en el repositorio de configuración sin riesgo.
- Verifica la huella de cada raíz que importas contra la publicada por la entidad. Importar una raíz sin verificar es aceptar como confiable lo que llegue.
El síntoma típico de un almacén de confianza incompleto es un error de ruta de certificación al validar. Su significado y sus causas están en qué significa el error de cadena de certificados.
Cuando la clave está en un dispositivo
Si el certificado vive en un token o en un módulo de hardware, no hay archivo que cargar. La plataforma ofrece un proveedor que expone el dispositivo como si fuera un almacén de claves: se configura con la ruta de la biblioteca del fabricante y desde ahí el código usa la misma API de siempre, con el PIN en lugar de la contraseña del archivo.
Es una solución elegante, con dos precauciones importantes: los reintentos de PIN consumen el contador del dispositivo y pueden bloquearlo, y la concurrencia está limitada por el hardware. El detalle completo está en PKCS#11: cómo hablar con tokens y HSM.
Errores clásicos y su traducción
- Formato de almacén no reconocido: el tipo declarado no corresponde al archivo. Suele ser un .p12 cargado como si fuera formato propietario, o al revés.
- Contraseña incorrecta: además de lo obvio, revisa la codificación del carácter especial. Una contraseña con tilde o con símbolos puede llegar alterada desde una variable de entorno mal definida.
- No se encuentra ruta de certificación válida: falta la raíz en el almacén de confianza. No es un problema del certificado del firmante.
- Alias no encontrado: el almacén se renovó y el alias cambió. Enumera en vez de suponer.
- Algoritmo no soportado: la versión de la plataforma o el proveedor criptográfico no admite lo que pides. Revisa qué proveedores están registrados.
Si el problema aparece con el firmador oficial del Estado y no con tu aplicación, el camino es otro: está en Java no abre FirmaEC: cómo solucionarlo.
Buenas prácticas en un servidor de producción
- El almacén de claves no va dentro del artefacto desplegable ni en el repositorio de código. Va en una ruta del servidor con permisos restringidos, o en un gestor de secretos.
- Contraseñas fuera del código y fuera de los archivos de configuración versionados. Variables de entorno como mínimo, gestor de secretos como objetivo.
- Un usuario del sistema dedicado al proceso, propietario exclusivo del archivo.
- Nada de volcar el contenido del almacén en logs ni siquiera en modo depuración.
- Ambientes separados: el certificado real jamás en desarrollo ni en pruebas.
El tratamiento completo de esta parte, incluida la discusión sobre de quién es la clave que el servidor custodia, está en firmar en servidor con .p12: buenas prácticas.
Antes de la próxima renovación
El almacén se vuelve a armar cada vez que el certificado se renueva, y ese es el momento en que se rompen las integraciones con alias en duro y rutas dispersas. Tener el proceso escrito —dónde se coloca el archivo, qué servicios hay que reiniciar, quién valida que firmó bien— convierte una emergencia anual en una tarea de veinte minutos. La emisión es 100% en línea y toma aproximadamente 30 minutos, en archivo .p12, token USB o firma en la nube; los valores por volumen están en la página de precios.
Omnifox en el equipo de TI
El grupo también desarrolla Omnifox, una plataforma omnicanal que reúne WhatsApp, correo, redes y llamadas en una bandeja compartida. Para un área de TI que atiende solicitudes de varias áreas —"no puedo firmar", "el sistema pide contraseña"— tener esas conversaciones en una sola cola, con asignación y historial por usuario, evita que el soporte dependa de quién vio el mensaje primero. Más información en omnifox.io.
Preguntas frecuentes
¿Tengo que convertir el .p12 a formato propietario de Java?
No. Las versiones actuales de la plataforma cargan el .p12 directamente. Convertirlo solo agrega copias del material sensible y un paso más que mantener.
¿Puedo tener varios certificados en el mismo almacén?
Sí, cada uno con su alias. Es útil cuando el servidor firma en nombre de distintos titulares, siempre que el código seleccione el alias correcto de forma explícita y no por posición.
¿Dónde guardo la contraseña del almacén?
En un gestor de secretos o, como mínimo, en una variable de entorno gestionada por la plataforma de despliegue. Nunca en el repositorio, ni en un archivo de propiedades versionado, ni en un comentario del código.
¿Por qué mi aplicación no confía en un certificado que el navegador sí acepta?
Porque Java usa su propio almacén de confianza, independiente del sistema operativo y del navegador. Hay que importar la raíz correspondiente al almacén que usa la aplicación.
¿Sirve el mismo almacén en varios servidores?
Técnicamente sí, aunque conviene evaluarlo: copiar el material de clave a más lugares multiplica la superficie de exposición. Si el volumen lo justifica, un módulo de hardware o la firma en la nube resuelven el problema sin replicar archivos.
Si tu equipo va a renovar o desplegar certificados para firmar desde aplicaciones Java en servidor, conversa con un asesor corporativo de Firmas.com.ec. Cotiza tu plan corporativo.