Manual de Integración S-FiDE

Introducción y filosofía

S-FiDE (Sistema de Firma Digital Extendido) es una suite de programas Java independientes para firmar y verificar firmas digitales en documentos XML y PDF, y para extraer o inspeccionar certificados digitales desde tokens criptográficos (PKCS#11), archivos PKCS#12 o el almacén de certificados de Windows.

El diseño responde a un principio central: cada capacidad es un programa independiente, invocable por línea de comandos, que cualquier aplicación externa puede ejecutar como proceso hijo sin integrar ninguna librería Java. No existe una "librería S-FiDE" para enlazar — se distribuye como un conjunto de archivos .jar ejecutables, más una interfaz gráfica opcional que orquesta esos mismos programas.

Principios de diseño

• Contrato uniforme de proceso. Todo se invoca como java -jar Programa.jar <argumentos>. Código de salida 0 = éxito, 1 = error.
• Salidas separadas y limpias. Resultado normal por stdout, errores por stderr, siempre como texto simple. Nunca un stack trace de Java al usuario final.
• UTF-8 de punta a punta, en cualquier sistema operativo.
• Multiplataforma — Windows, Linux y macOS, salvo los dos módulos de almacén de Windows (exclusivos de ese sistema por diseño).
• La GUI no es un atajo privilegiado. Invoca exactamente los mismos .jar con los mismos argumentos que usaría un integrador externo.
• Vocabulario de comandos especiales unificado. Todos los módulos aceptan las mismas familias de alias: -version/-v/--version, -ayuda/-h/--help, -licencia/--license. Unificado en 1.1.1 — ver sección 13.

Especificaciones técnicas del producto

Software de terceros y dependencias

Licencia de uso

S-FiDE se distribuye bajo la Licencia Pública General GNU (GPL), versión 2 o cualquier versión posterior, publicada por la Free Software Foundation.

• Es software libre: se puede redistribuir y/o modificar bajo esos términos.
• Se distribuye con la intención de que sea útil, sin garantía de ningún tipo.
• Texto completo en el archivo LICENSE.txt de cada módulo, y en gnu.org/licenses/gpl-2.0.html.
• Copyright © 2024 Juan Carlos Ríos y Juan Ignacio Ríos, Grupo Sauken S.A.
• El soporte técnico es un servicio con cargo, independiente de la libertad de uso del software.

Código fuente y repositorio

• Repositorio: github.com/Grupo-Sauken-S-A/S-FIDE
• Proyecto Maven multi-módulo (14 módulos), un pom.xml raíz agregador.
• Versionado SemVer. Tags publicados: v1.0.0, v1.1.1, v1.2.0, v1.3.0 (actual).

Compilar desde el código fuente:

git clone https://github.com/Grupo-Sauken-S-A/S-FIDE.git
cd S-FIDE
./mvnw clean install

Requiere JDK 23 — el proyecto incluye Maven Wrapper, no hace falta Maven instalado aparte. El código fuente completo está disponible conforme a la GPLv2: cualquier integrador puede auditar qué hace cada programa antes de confiar en él para documentos con validez legal.

Arquitectura de integración

Tanto una aplicación integradora externa como la propia GUI invocan los módulos exactamente igual: como proceso hijo, mismos argumentos, misma salida. No hay una API interna distinta para "uso avanzado" — el contrato de línea de comandos es la API.

Cada módulo recibe sus parámetros por argumentos de línea de comandos (nunca por variables de entorno ni configuración, salvo la excepción documentada de sfide-defaults.properties que usa solo la GUI), realiza su tarea, escribe el resultado en stdout y/o un archivo, y termina con código 0 o 1.

Mecanismos de firma digital: PKCS#11, PKCS#12 y Windows CSP/KSP

S-FiDE soporta tres formas distintas de acceder a una clave privada para firmar. Elegir la correcta depende de dónde vive esa clave.

7.1 — PKCS#11 (tokens criptográficos y HSM)

PKCS#11 es un estándar de la industria (OASIS) que define una API en C para que cualquier aplicación hable con un dispositivo criptográfico sin conocer los detalles del fabricante. El fabricante provee una biblioteca dinámica (.dll/.so/.dylib) que la aplicación carga en tiempo de ejecución. En Java esto se hace vía el proveedor SunPKCS11, incluido en el JDK.

Hash interno vs. externo — el detalle que resolvimos en 1.1.1

Un token firma RSA-SHA256 mediante un "mecanismo" (CK_MECHANISM). Existen dos posibles:

• CKM_SHA256_RSA_PKCS (combinado): el token calcula el hash internamente. Un solo llamado. Los tokens SafeNet/Thales lo soportan.
• CKM_RSA_PKCS (puro): el token solo aplica padding PKCS#1 v1.5 y la operación RSA — el hash SHA-256 debe calcularlo la aplicación antes, envuelto en una estructura ASN.1 DigestInfo. En teoría, tokens en modo FIPS 140-2 Nivel 3 como el Feitian ePass2003 solo exponen este mecanismo a bajo nivel.

Desde 1.1.1, XMLSignerPKCS11 y PDFSignerPKCS11 prueban el mecanismo combinado primero y, si el token lo rechaza, calculan el hash por software y reintentan — de forma transparente. No hay ningún parámetro para elegir el mecanismo.

7.2 — PKCS#12 (archivos de certificado)

PKCS#12 es un formato de contenedor de archivo (.p12/.pfx) que empaqueta, cifrado con contraseña, un certificado X.509 junto a su clave privada — sin hardware involucrado.

Ventajas: simple, sin drivers, igual en cualquier SO. Desventajas: la clave es un archivo copiable — la seguridad depende de proteger ese archivo y su contraseña; no aceptable para trámites que exigen hardware homologado FIPS 140-2.

7.3 — Windows CSP/KSP (almacén de certificados de Windows)

En una frase, para quien no conoce PKCS#11: en Windows, la forma más simple de firmar con un token es la misma que usa Adobe Acrobat/Reader por defecto — sin indicar ninguna ruta de biblioteca de fabricante ni saber la marca/modelo exacto del token. Es lo mismo que ve un usuario al abrir el Administrador de certificados de Windows (certmgr.msc) y encontrar su certificado ya listo para usar: Acrobat, y ahora S-FiDE, lo leen directamente de ese mismo lugar.

Cómo funciona, en detalle: además de PKCS#11, Windows ofrece un mecanismo nativo del sistema operativo: CryptoAPI (CAPI, legado) y su sucesor CNG, vía CSP o KSP respectivamente. Los fabricantes de tokens suelen instalar, además de PKCS#11, un minidriver CSP/KSP certificado por Microsoft — el certificado aparece automáticamente en el almacén de certificados de Windows, sin que ninguna aplicación deba configurar una ruta de biblioteca.

S-FiDE incorpora esta alternativa vía XMLSignerWindowsCSP y PDFSignerWindowsCSP, usando SunMSCAPI para acceder al almacén Windows-MY. En vez de una biblioteca .dll y un número de slot, estos dos módulos piden un alias o fragmento del nombre del titular del certificado (-listar-certificados muestra qué hay disponible). No se pasa contraseña — el acceso lo administra Windows (puede pedir el PIN con un diálogo nativo al momento de firmar), a diferencia de los módulos PKCS#11, donde el PIN se pasa como argumento del programa.

7.4 — Comparación

7.5 — Validación de revocación: OCSP y CRL

Un certificado puede ser matemáticamente válido (no vencido, cadena de confianza correcta) y sin embargo haber sido revocado por su emisor — por ejemplo, porque el token fue robado o la clave se vio comprometida. La única forma de saberlo es consultar a la autoridad certificante; no hay manera de verificar esto sin conexión.

Al verificar una firma, XMLVerifySignatures y PDFVerifySignatures intentan dos mecanismos, en este orden:

1. OCSP (Online Certificate Status Protocol): consulta en tiempo real al respondedor de la autoridad certificante — su URL está publicada dentro del propio certificado (extensión Authority Information Access). S-FiDE arma una solicitud identificando el certificado por su número de serie, y la autoridad responde indicando si está vigente o revocado. Es el mecanismo más preciso, refleja el estado en el instante exacto de la consulta.
2. CRL (Certificate Revocation List): si OCSP no responde o el resultado es indeterminado, se recurre a la lista de revocados que la autoridad publica periódicamente (URL también en el certificado, extensión CRL Distribution Point). Menos preciso — puede no reflejar una revocación muy reciente — pero funciona aunque el respondedor OCSP puntual esté caído.

Tiempos de espera exactos (verificados en el código): la comprobación de conectividad usa un socket de prueba con 3 segundos de espera; las consultas HTTP a OCSP y CRL usan 5 segundos de espera de conexión cada una.

Si ninguno responde, o no hay URLs de OCSP/CRL en el certificado, el estado queda "No verificable" — esto no invalida la firma: integridad criptográfica y revocación son dos verificaciones independientes. Un documento puede salir VÁLIDO con revocación "No verificable": la firma es genuina, solo que no se pudo confirmar en ese momento que el certificado siga vigente.

Fecha usada para evaluar la revocación en XML. Por defecto, XMLVerifySignatures usa la fecha y hora actual del sistema para decidir si una revocación es anterior o posterior a la firma — con una excepción deliberada para documentos ALADI/MERCOSUR, ver sección 10.

Fecha usada para evaluar la revocación en PDF — de dónde sale exactamente, verificado contra el bytecode real de iText 8.0.5. PDFVerifySignatures usa PdfPKCS7.getSignDate() como fecha de referencia. Tiene dos fuentes posibles, en este orden de prioridad:

1. Un sello de tiempo RFC 3161 (TSA) embebido en la firma, si existe — una fecha certificada por una autoridad de sellado de tiempo independiente, no por el propio firmante.
2. El campo /M del diccionario de firma del PDF, si no hay sello de tiempo. Lo escribe la propia aplicación firmante con la hora de su reloj de sistema al firmar (SignatureUtil.readSignatureData() lo lee vía PdfSignature.getDate() y PdfDate.decode(...)). Queda dentro del rango de bytes cubierto por la firma — no se puede alterar después sin invalidarla — pero es un dato autodeclarado por el firmante, no verificado por ningún tercero.

Por qué un certificado revocado invalida la firma, en términos simples: la revocación significa que la autoridad certificante retiró la confianza en ese certificado — por ejemplo, porque la clave privada se filtró o el titular dejó de estar habilitado — después de haberlo emitido. Que la firma sea criptográficamente correcta solo demuestra que el documento no fue alterado y que fue producido con esa clave privada; no demuestra que esa clave siga siendo confiable. Por eso XMLVerifySignatures marca como INVÁLIDA cualquier firma cuyo certificado figure como revocado en el momento correspondiente, y lo informa explícitamente: "El certificado fue revocado por su autoridad certificante. Aunque la firma es criptográficamente correcta, esta firma se considera INVÁLIDA por ese motivo."

7.5.1 — Validación de revocación antes de firmar

Desde la versión 1.2.0, los seis módulos que aplican una firma digital (XMLSignerPKCS11, XMLSignerPKCS12, XMLSignerWindowsCSP, PDFSignerPKCS11, PDFSignerPKCS12, PDFSignerWindowsCSP) validan el estado de revocación del certificado antes de firmar, no solo después. Usa exactamente el mismo mecanismo y el mismo orden de la sección 7.5 — OCSP primero, CRL como respaldo — con una sola diferencia: la fecha de referencia es siempre el instante actual, ya que todavía no existe ningún documento firmado del cual extraer una fecha.

Flag -omitir-revocacion true: disponible en los seis módulos, por defecto false. Si se indica true, fuerza la firma incluso si el certificado está confirmado como revocado — pensado para un caso de uso legítimo puntual o para no romper una automatización existente. Su uso queda registrado en la propia línea de comando ejecutada; el mensaje de advertencia siempre deja explícito que se forzó.

Comportamiento distinto en la interfaz gráfica, en los módulos PKCS#12 y Windows CSP/KSP. La CLI nunca pregunta nada — firma en silencio ante "no se pudo determinar", pensado para automatización desatendida. La GUI, en cambio, siempre tiene un usuario presente en tiempo real: en XMLSignerPKCS12, PDFSignerPKCS12, XMLSignerWindowsCSP y PDFSignerWindowsCSP, antes de firmar consulta el estado con un nuevo modo de solo lectura (-verificar-revocacion <credenciales>, sin tocar el documento) y decide: si no está revocado, firma directo; si no se pudo determinar, muestra un diálogo "¿Desea firmar de todas formas?" (Sí firma, Cancelar no firma nada); si está confirmado revocado, nunca firma y no hay diálogo — no hay forma de forzarlo desde la GUI.

7.6 — Compatibilidad con firmas SHA-1 de aplicaciones de terceros

S-FiDE firma exclusivamente con SHA-256 — es una decisión deliberada, SHA-1 se considera criptográficamente débil para firmar documentos nuevos. Sus verificadores, en cambio, están diseñados para validar cualquier firma conforme al estándar, sin importar qué aplicación la generó ni con qué algoritmo de hash — incluyendo firmas SHA-1 de software de terceros ya discontinuado.

• XML (XMLVerifySignatures, XMLVerifyXSDStructure): deshabilitan explícitamente el modo "validación segura" de JSR-105 (secureValidation = false), que de lo contrario rechazaría de plano cualquier firma SHA-1. Ambos reconocen rsa-sha1 y rsa-sha256.
• PDF (PDFVerifySignatures): verifica vía PdfPKCS7.verifySignatureIntegrityAndAuthenticity() de iText, sin restricción de algoritmo — el algoritmo se informa de manera descriptiva pero nunca se usa como criterio de rechazo.

Por qué esto es especialmente relevante para COD y DJO (sección 10): en la práctica, los elementos COD/CODEH/DJO/DJOEH de un mismo documento a veces se firman con software de distintas empresas — un exportador puede usar S-FiDE mientras que la Entidad Habilitada usa otra aplicación (o viceversa), y esas otras aplicaciones pueden seguir usando SHA-1. XMLVerifySignatures tiene que poder validar ambas firmas del mismo documento sin importar cuál de las dos las generó ni con qué algoritmo — es exactamente el escenario que este soporte está pensado para cubrir.

Catálogo de tokens y drivers soportados

Cualquier token PKCS#11 es utilizable. La siguiente tabla —fuente única en shared-resources/token-profiles.txt— documenta los modelos del ecosistema AC-ONTI argentino:

Hardware validado end-to-end

Modelos efectivamente probados por Grupo Sauken S.A. contra el dispositivo físico real (no solo software/simulación), cubriendo el ciclo completo firma → verificación:

Ayuda de selección de driver

• GUI: combo de marca/modelo + botón "Detectar automáticamente" (revisa qué rutas de la tabla existen en el equipo).
• CLI: comando -listar-drivers (también aceptado como --listar-drivers) en TokenSlotsView, TokenCertificateExtractor, XMLSignerPKCS11 y PDFSignerPKCS11.

Catálogo de aplicaciones

Convenciones comunes: código de salida 0 éxito / 1 error (salvo aclaración); todas leen y escriben en UTF-8; los comandos -version/-v/--version, -ayuda/-h/--help y -licencia/--license son idénticos en los 13 módulos de línea de comandos desde 1.1.1.

java -jar TokenSlotsView.jar <biblioteca PKCS#11> <contraseña>
java -jar TokenSlotsView.jar [-version | -ayuda | -licencia | -listar-drivers]

java -jar TokenSlotsView.jar C:\Windows\System32\eTPKCS11.dll "MiPIN123"

java -jar TokenCertificateExtractor.jar <biblioteca PKCS#11> <contraseña> <slot>
java -jar TokenCertificateExtractor.jar [-version | -ayuda | -licencia | -listar-drivers]

java -jar TokenCertificateExtractor.jar C:\Windows\System32\eTPKCS11.dll "MiPIN123" 0

java -jar PKCS12CertificateExtractor.jar <archivo.p12> <password>
java -jar PKCS12CertificateExtractor.jar [-version | -ayuda | -licencia]

java -jar PKCS12CertificateExtractor.jar C:\certificados\empresa.pfx "MiContraseña123"

Reglas de firma comunes a los tres firmadores XML

XMLSignerPKCS11, XMLSignerPKCS12 y XMLSignerWindowsCSP aplican, antes de firmar, dos controles obligatorios:

1. Nunca firmar un elemento que ya tiene una firma digital aplicada — vale para cualquier XML genérico, no solo los especializados de comercio exterior. Si el elemento indicado (o el documento completo, con "") ya tiene una <ds:Signature> cuya Reference apunta a él, el programa rechaza la operación sin modificar el archivo.
2. Regla de orden para CODEH/DJOEH (sección 10): no se puede firmar CODEH sin una firma previa sobre COD, ni firmar DJOEH sin una firma previa sobre DJO.

Ambos controles buscan <ds:Signature>/<ds:Reference> existentes en el documento — no vuelven a verificar criptográficamente la firma previa, solo confirman que existe.

El elemento '[id]' ya tiene una firma digital aplicada. No se puede firmar el mismo elemento dos veces. · El documento ya tiene una firma digital aplicada sobre todo su contenido... (con elemento vacío) · No se puede firmar el elemento CODEH: no existe una firma digital previa sobre el elemento COD. · No se puede firmar el elemento DJOEH: no existe una firma digital previa sobre el elemento DJO.

java -jar XMLSignerPKCS11.jar <biblioteca> <contraseña> <slot> <archivo.xml> <elemento> [-omitir-revocacion true|false]
java -jar XMLSignerPKCS11.jar [-version | -ayuda | -licencia | -listar-drivers]

java -jar XMLSignerPKCS11.jar C:\Windows\System32\eTPKCS11.dll "MiPIN123" 0 C:\docs\certificado-origen.xml COD

java -jar XMLSignerPKCS12.jar <certificado.p12> <password> <archivo.xml> <elemento> [-omitir-revocacion true|false]
java -jar XMLSignerPKCS12.jar [-version | -ayuda | -licencia]

java -jar XMLSignerPKCS12.jar C:\certificados\empresa.pfx "MiContraseña123" C:\docs\declaracion.xml DJO

java -jar XMLVerifySignatures.jar <archivo.xml> [-simple]
java -jar XMLVerifySignatures.jar [-version | -ayuda | -licencia]

java -jar XMLVerifySignatures.jar C:\docs\certificado-origen-signed.xml
java -jar XMLVerifySignatures.jar C:\docs\certificado-origen-signed.xml -simple

NOTA: Diferencia en nombres de archivo XSD
├─ XSD referenciado en XML: esquema-v2.xsd
├─ XSD proporcionado: esquema-v1-local.xsd
└─ Se utilizará el archivo proporcionado: esquema-v1-local.xsd

java -jar XMLVerifyXSDStructure.jar <archivo.xml> [esquema.xsd]
java -jar XMLVerifyXSDStructure.jar [-version | -ayuda | -licencia]

java -jar XMLVerifyXSDStructure.jar C:\docs\certificado-origen.xml
java -jar XMLVerifyXSDStructure.jar C:\docs\certificado-origen.xml C:\xsd\esquema-v2.xsd

Opciones específicas de los firmadores de PDF

PDFSignerPKCS11, PDFSignerPKCS12 y PDFSignerWindowsCSP comparten estas opciones, sin equivalente en los firmadores de XML — un XML no tiene "apariencia visual" ni concepto de página.

• Firma visible vs. invisible. Sin -x/-y (o en 0), la firma es igual de válida criptográficamente pero no se dibuja nada. Con coordenadas, se dibuja un recuadro con firmante, fecha y el texto de -t si se indicó.
• Sistema de coordenadas. PDF usa el estándar PostScript: origen (0,0) en la esquina inferior izquierda de la página, X crece a la derecha, Y crece hacia arriba. -x/-y ubican la esquina inferior izquierda del recuadro (160×70 puntos, tamaño fijo) — no es "de abajo a la derecha", es de abajo a la izquierda. 1 punto PDF = 1/72 de pulgada. Siempre en la página 1.
• Texto personalizado (-t). Se agrega debajo del nombre y la fecha, dentro del mismo recuadro. Sin efecto si la firma es invisible.
• Bloquear el documento (-k/-l true, según el módulo). Dos efectos, siempre acoplados desde 1.1.1: (1) marca la firma como certificante (permiso PDF DocMDP = "sin cambios permitidos" — solo puede haber una por documento, y debe ser la primera), y (2) cifra el PDF en AES-256 restringiendo permisos a solo impresión y lectores de pantalla.
• Validación de firmas preexistentes. Los tres firmadores verifican, antes de firmar, que cualquier firma ya presente sea íntegra — si no lo es, no se modifica el archivo.

java -jar PDFSignerPKCS11.jar -i <pdf> -l <biblioteca> -p <password> -s <slot> [-k true|false] [-x pos] [-y pos] [-t "texto"] [-omitir-revocacion true|false]
java -jar PDFSignerPKCS11.jar [-v | -h | --license | --listar-drivers]

java -jar PDFSignerPKCS11.jar -i C:\docs\certificado.pdf -l C:\Windows\System32\eTPKCS11.dll -p "MiPIN123" -s 0 -k true -x 40 -y 55 -t "Exportador"

java -jar PDFSignerPKCS12.jar -i <pdf> -c <certificado.p12> -p <password> [-l true|false] [-x pos] [-y pos] [-t "texto"] [-omitir-revocacion true|false]
java -jar PDFSignerPKCS12.jar [-v | -h | --license]

java -jar PDFSignerPKCS12.jar -i C:\docs\certificado.pdf -c C:\certificados\empresa.pfx -p "MiContraseña123" -l true -x 40 -y 55

java -jar PDFVerifySignatures.jar <archivo.pdf> [-simple]
java -jar PDFVerifySignatures.jar [-version | -ayuda | -licencia]

java -jar PDFVerifySignatures.jar C:\docs\certificado-signed.pdf
java -jar PDFVerifySignatures.jar C:\docs\certificado-signed.pdf -simple

java -jar XMLSignerWindowsCSP.jar <alias o fragmento del CN> <archivo.xml> <elemento> [-omitir-revocacion true|false]
java -jar XMLSignerWindowsCSP.jar [-version | -ayuda | -licencia | -listar-certificados]

java -jar XMLSignerWindowsCSP.jar "Juan Carlos Ríos" C:\docs\certificado-origen.xml COD

java -jar PDFSignerWindowsCSP.jar -i <pdf> -a <alias o fragmento CN> [-k true|false] [-x pos] [-y pos] [-t "texto"] [-omitir-revocacion true|false]
java -jar PDFSignerWindowsCSP.jar [-v | -h | --license | --listar-certificados]

java -jar PDFSignerWindowsCSP.jar -i C:\docs\certificado.pdf -a "Juan Carlos Ríos" -k true -x 40 -y 55

java -jar WindowsCertificateStoreView.jar
java -jar WindowsCertificateStoreView.jar [-version | -ayuda | -licencia | -listar-certificados]

java -jar WindowsCertificateStoreView.jar

Especialización de comercio exterior ALADI/MERCOSUR: COD, CODEH, DJO y DJOEH

Esta sección documenta una funcionalidad adicional (add-on) por encima del soporte estándar de firma XML, orientada al intercambio de documentación de comercio exterior entre países miembros de la ALADI (Asociación Latinoamericana de Integración), incluyendo el bloque MERCOSUR.

10.1 — Contexto

Los acuerdos comerciales entre países miembros de ALADI obligan a las partes a intercambiar datos de comercio exterior mediante documentos XML normalizados. Dos tipos de documento son centrales:

• Certificado de Origen Digital, agrupado en un elemento COD (firma como Exportador) o CODEH (firma como Funcionario Habilitado del organismo emisor).
• Declaración Jurada de Origen, agrupada en un elemento DJO (Exportador) o DJOEH (Funcionario Habilitado).

Estos documentos deben llevar firmas digitales embebidas exactamente sobre esos elementos — no sobre el documento completo — de modo que cada parte quede firmada de manera independiente y verificable por separado, dentro del mismo XML.

10.2 — Estructura real de un COD/CODEH

Ejemplo real (esquema codaladi.org/directorio/cod_ver_1.8.2.xsd):

ns1:Envelope
  ns1:CertOrigin
    CODEH (id="CODEH")            ← elemento EXTERIOR, envuelve todo
      CODExporter
        COD (id="COD")            ← elemento INTERIOR, anidado vía CODExporter
          CODVer, CODSubmitterType, Agreement, FormA18...
        [firma del Exportador]    ← Reference="#COD", justo después de </COD>
      /CODExporter
      EH (EHId, EHCountry, EHName, EHAddress, EHCity, EHTelephone, EHFax, EHEmail, EHURL)
      CertificationEH (CertificateControlCode, CertificateDate, CertificateID)
    /CODEH
    [firma del Funcionario]       ← Reference="#CODEH", justo después de </CODEH>
  /ns1:CertOrigin

Cuatro etapas estrictamente secuenciales: (1) el XML se crea con COD completo, sin firmas — en ese momento solo COD puede firmarse, porque CODEH aún no tiene EH/CertificationEH; (2) el Exportador firma COD, la firma queda hermana justo después de </COD>, dentro de CODExporter; (3) el sistema externo de gestión de certificados (no S-FiDE) agrega <EH> y <CertificationEH> dentro de CODEH, después de </CODExporter>; (4) recién ahí el Funcionario Habilitado puede firmar CODEH — esa firma queda hermana justo después de </CODEH>, y su digest cubre todo el subárbol de CODEH, incluida la firma del Exportador ya embebida.

Regla de orden (no se puede firmar CODEH sin firma válida en COD, ni sin los datos de certificación): la garantiza el sistema externo que orquesta las llamadas a S-FiDE — S-FiDE no la conoce ni la valida. Los firmadores solo firman el elemento por Id que se les indique, cuando se los invoque.

Nombre de archivo: el contenido de <CertificateID> más .xml — p. ej. AR001A18170000043000.xml (país + código de entidad ALADI + código de acuerdo + año + número de certificado). Se recomienda enviarlo al importador dentro de un ZIP.

10.3 — Estructura real de un DJO/DJOEH

Misma mecánica de dos etapas, para una Declaración Jurada de Origen:

ns1:Envelope
  ns1:Affidavit                   ← raíz distinta a la de COD (CertOrigin)
    DJOEH (id="DJOEH")
      DJOExporter
        DJO (id="DJO")
          DJOVer, DJOSubmitterType, Agreement, Exporter, Producer,
          Declaration (DeclarationDate), FormDJO...
        [firma del Exportador]    ← Reference="#DJO"
      /DJOExporter
      EH (EHId, EHCountry, EHName, EHAddress, EHCity, EHTelephone, EHEmail, EHURL)
      ApprovalEH (ApprovalNumber, ApprovalDate, ROMCompliance)
    /DJOEH
    [firma del Funcionario]       ← Reference="#DJOEH"
  /ns1:Affidavit

Mismas cuatro etapas que COD/CODEH, con nombres propios: el bloque de certificación del funcionario se llama ApprovalEH (no CertificationEH), con campos ApprovalNumber/ApprovalDate/ROMCompliance — una declaración de cumplimiento del Régimen de Origen Mercosur, no un número de certificado.

10.4 — Validación de revocación por elemento

Un documento completo (COD o DJO) contiene dos firmas independientes, de titulares y momentos distintos. XMLVerifySignatures extrae, para cada una, la fecha correcta según a qué elemento apunta su Reference:

Tabla de husos horarios (TimezoneConverter): Argentina, Bolivia, Brasil, Chile, Colombia, Cuba, Ecuador, México, Panamá, Paraguay, Perú, Uruguay y Venezuela.

Por qué DJO/DJOEH no convierten huso horario: a diferencia de un Certificado de Origen, una Declaración Jurada de Origen se opera siempre dentro de un mismo país — el que emite el XML. El valor de fecha ya representa el instante correcto tal cual está escrito.

Por qué CODEH usa EHCountry y no ExporterCountry: la firma sobre CODEH la aplica el Funcionario Habilitado, actuando por la Entidad Habilitada — su acto de firma ocurre en el país de esa entidad, no necesariamente en el del exportador.

10.5 — Reglas de firma obligatorias

Además de la regla genérica de no volver a firmar un elemento ya firmado, los tres firmadores XML aplican una regla de orden específica para esta especialización, reflejando la secuencia operativa real de 10.2/10.3:

• CODEH no puede firmarse si COD no tiene ya una firma digital aplicada.
• DJOEH no puede firmarse si DJO no tiene ya una firma digital aplicada.

Ambas verificaciones son de existencia, no de validez criptográfica completa: el firmador confirma que hay una <ds:Signature> con Reference al elemento requerido, sin volver a verificarla — la disciplina de orden real la garantiza el sistema externo que orquesta las llamadas a S-FiDE, no S-FiDE actuando como autoridad de validación completa al momento de firmar.

No se puede firmar el elemento CODEH: no existe una firma digital previa sobre el elemento COD. · No se puede firmar el elemento DJOEH: no existe una firma digital previa sobre el elemento DJO.

Regla adicional — no se permite firmar el documento completo

Los tres firmadores XML detectan automáticamente si el XML es un documento de comercio exterior: basta con que exista, en cualquier parte del documento, un elemento con Id/id/ID igual a COD o a DJO (no hace falta que sea justo el elemento que se está por firmar). Si se detecta esta condición y el elemento a firmar indicado es la cadena vacía "" (equivalente a firmar todo el documento), la operación se rechaza — en un XML de comercio exterior siempre hay que indicar explícitamente qué elemento firmar (COD, CODEH, DJO o DJOEH, según la etapa). Se suma a las reglas anteriores, no las reemplaza.

Este XML corresponde a un documento de comercio exterior (un Certificado de Origen Digital / una Declaración Jurada de Origen). No se permite firmar el documento completo: debe indicarse un elemento específico a firmar.

10.6 — Sensibilidad a mayúsculas/minúsculas

El nombre del elemento a firmar es sensible a mayúsculas y minúsculas. Para Certificados de Origen Digitales y Declaraciones Juradas de Origen, usar siempre los identificadores en mayúsculas: COD, CODEH, DJO, DJOEH.

Integración desde otras aplicaciones

Patrón recomendado por Grupo Sauken: redirigir stdout/stderr a archivos separados y capturar el código de salida, para que la aplicación integradora los lea una vez que el proceso terminó.

Windows (.bat)

@echo off
set SFIDE=C:\ruta\a\S-FiDE
C:
cd %SFIDE%
set JAVA_HOME=%SFIDE%\openjdk-23.0.1\windows-x64
set PATH=%JAVA_HOME%\bin;%PATH%

%JAVA_HOME%\bin\java -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -jar PKCS12CertificateExtractor.jar "C:\ruta\al\certificado.pfx" "<Contraseña>" 1>"C:\temp\salida.txt" 2>"C:\temp\error.txt"

set RESULT=%ERRORLEVEL%
echo %RESULT% > "C:\temp\result.txt"
exit /b %RESULT%

• JAVA_HOME/PATH apuntan al runtime embebido en la propia distribución — no dependen de que el sistema tenga Java instalado.
• -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8: recomendado incluir siempre, fuerza UTF-8 en salida y en rutas/argumentos con acentos.
• 1>archivo / 2>archivo redirigen stdout/stderr por separado.
• %ERRORLEVEL% es el código de salida del proceso, sin transformación.

Este patrón sirve para cualquiera de los 13 módulos — solo cambia el jar y sus argumentos.

Linux/macOS (shell)

#!/bin/sh
SFIDE=/opt/S-FiDE
cd "$SFIDE"
JAVA_HOME="$SFIDE/openjdk-23.0.1/linux-x64"   # macOS: "$SFIDE/openjdk-23.0.1/macos"
PATH="$JAVA_HOME/bin:$PATH"

"$JAVA_HOME/bin/java" -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 \
    -jar PKCS12CertificateExtractor.jar "/ruta/al/certificado.pfx" "<Contraseña>" \
    >"/tmp/salida.txt" 2>"/tmp/error.txt"

RESULT=$?
echo $RESULT > "/tmp/result.txt"
exit $RESULT

Distribución y despliegue

Una distribución lista para usar es una carpeta autocontenida:

S-FiDE/
├── openjdk-23.0.1/          ← runtime de Java embebido (por plataforma)
├── javafx-sdk-23.0.1/       ← SDK de JavaFX embebido (por plataforma)
├── *.jar                    ← los 14 módulos, nombre "amigable" sin versión
├── SFide-GUI.bat / .sh      ← launchers, se autodetectan solos
├── doc/  test/  xsd/        ← documentación y ejemplos

No requiere instalación ni Java preinstalado — puede copiarse a cualquier ubicación, incluido un medio removible, y correr en un equipo "limpio", gracias al runtime embebido y a que los launchers se autodetectan (sin rutas ni letras de unidad hardcodeadas).

Historial de versiones

v1.3.0 (2026-09-05)

• Verificación de instancia única por carpeta de instalación: FileLock exclusivo sobre sfide-gui.lock, no un flag persistido — el sistema operativo libera el lock automáticamente al terminar el proceso, sea un cierre normal o una caída. Ver sección 9.14.
• Nueva pestaña "Documentación" en la ventana de Ayuda, con enlaces a la Guía de Usuario y el Manual Técnico (URL file://) y a los visualizadores externos de ALADI para COD/CODEH y DJO/DJOEH. La pestaña "Contacto" suma un enlace a GitHub. Ver sección 9.14.
• Botón "Abrir documento generado" junto al documento de entrada en las seis pestañas de firma — habilitado solo cuando la firma termina con éxito y el archivo -signed existe realmente en disco.
• Botones de ayuda contextual ("?") junto a "Elemento XML (ID) a Firmar" (las tres pestañas de firma XML) y junto a la posición X/Y (las tres pestañas de firma PDF), y placeholders reales en todo campo de entrada vacío.
• Revisión completa de qué se recuerda entre sesiones: "Salida simple" (verificadores) ahora se recuerda; la posición X/Y de firma visible en PDF y "Bloquear documento después de firmar" dejaron de recordarse y de compartirse entre pestañas — el usuario siempre debe indicarlas de nuevo, igual que el elemento/ID de un XML a firmar. De paso, sfide-defaults.properties pasó a resolverse junto al jar en ejecución, no al directorio de trabajo del proceso.
• Diálogo "Acerca de" ampliado, con enlaces al repositorio en GitHub y a la página del proyecto, y una mención de la licencia.

v1.2.0 (2026-09-03)

• Validación de revocación antes de firmar, en los seis módulos que aplican firma digital (XMLSignerPKCS11, XMLSignerPKCS12, XMLSignerWindowsCSP, PDFSignerPKCS11, PDFSignerPKCS12, PDFSignerWindowsCSP) — ver sección 7.5.1 para el detalle completo (política, flag -omitir-revocacion, y la limitación conocida heredada del mecanismo de los verificadores).
• Diálogo de confirmación en la GUI cuando no se puede determinar el estado de revocación, en las pestañas PKCS#12 y Windows CSP/KSP (no en las de token, por el riesgo de un segundo ingreso de PIN) — ver sección 7.5.1, apartado "Comportamiento distinto en la interfaz gráfica".
• El acceso directo a la aplicación ya no lleva el número de versión en el nombre (S-FiDE.lnk, antes S-FiDE <versión>.lnk): al actualizar de versión, el primer arranque reemplaza el ícono anterior en vez de sumar uno más al lado. Nuevo ítem de menú Herramientas → Recrear accesos directos (Windows) para recrearlos a pedido — ver sección 9, nota "(Windows) Accesos directos automáticos".

v1.1.1 (2026-09-01)

• Compatibilidad ampliada de tokens PKCS#11 (hash externo, sección 7.1).
• Autodetección de marca/modelo y ayuda de selección de driver.
• Dos módulos nuevos: XMLSignerWindowsCSP y PDFSignerWindowsCSP, más un tercero, WindowsCertificateStoreView, dedicado exclusivamente a listar el almacén de Windows (equivalente de TokenSlotsView para PKCS#11).
• Actualización de dependencias criptográficas por alertas de seguridad.
• Corrección de dos errores hallados en QA con hardware real (SafeNet 5110+ L3).
• Especialización ALADI/MERCOSUR completada (sección 10): corregido un error real — la revocación de la firma sobre CODEH usaba ExporterCountry en vez de EHCountry para convertir a UTC; agregado soporte de extracción de fecha para DJO/DJOEH (literal como UTC, sin conversión de huso horario); verificado contra archivos DJO reales en sus 4 etapas; agregadas dos reglas de firma obligatorias (nunca firmar un elemento ya firmado, nunca firmar CODEH/DJOEH sin firma previa en COD/DJO); mensajes de revocación de XMLVerifySignatures aclarados para explicar por qué un certificado revocado invalida la firma; XMLVerifyXSDStructure ahora reintenta contra un dominio espejo (cod.certificadoorigen.com.ar) cuando el dominio oficial de ALADI (codaladi.org) está caído, incluyendo el caso de una redirección HTTP→HTTPS que antes se descargaba como si fuera el XSD; los tres firmadores XML ahora prohíben firmar el documento completo (elemento vacío) cuando detectan un XML de comercio exterior (contiene COD o DJO), e informan en consola de qué tipo de documento se trata y qué elemento se firmó.
• Auditoría de código y corrección de inconsistencias entre módulos hermanos: se eliminó un stack trace expuesto en XMLVerifySignatures; PDFSignerPKCS12 ahora acopla siempre certificación DocMDP + cifrado al bloquear (antes solo con firma visible); PDFSignerWindowsCSP ahora valida firmas preexistentes y rechaza PDFs ya encriptados; se unificó el vocabulario de comandos especiales en los módulos CLI; se corrigieron afirmaciones de documentación no respaldadas por el código (versión de PKCS#11/12, XAdES, XML Schema 1.1, timeouts de OCSP/CRL).
• Validado de punta a punta con hardware real: SafeNet 5110+ L3, mToken CryptoID nueva y Feitian ePass2003, además de PKCS#12 (sección 8, "Hardware validado end-to-end").
• Rediseño de s_fide_gui: panel lateral de navegación en vez de pestañas horizontales, panel "Salida del Proceso" colapsable, ConfigurationManager reescrito con valores observables (guardado y sincronización en vivo entre módulos), y reescritas las 10 descripciones de módulo heredadas de 1.0.0.
• Corregido un problema real de extracción del ZIP de distribución: algunos usuarios lo descomprimieron directo en la raíz de una unidad (C:\). Se corrigió el empaquetado (los ZIP del Release ahora traen una carpeta propia) y un bug latente real en SFide-GUI.bat que en ese caso podía hacer que el programa arrancara con el directorio de trabajo equivocado (sección 12); también se corrigió para funcionar desde una carpeta con espacios en el nombre.
• Accesos directos automáticos (Windows): al primer arranque, s_fide_gui crea accesos directos en el escritorio y el menú inicio con ícono propio, blindados para nunca fallar visiblemente ni bloquear el arranque bajo políticas de seguridad corporativas restrictivas. El alias/CN del almacén de Windows también se recuerda y sincroniza en vivo entre los dos firmadores CSP/KSP.
• GUIUtils.executeCommand (ejecución de módulos desde la GUI) ganó un límite de tiempo de 10 minutos con cancelación automática, para no quedar colgado ante un proceso que no responde.
• LICENSE simplificado al texto canónico exacto de la GPLv2 para que GitHub reconozca correctamente la licencia del proyecto.
• Guía de Usuario S-FiDE GUI nueva (doc/manual-usuario-sfide-gui.html): recorrido de las 13 pantallas de la interfaz gráfica con capturas reales, para quien opera la GUI en vez de integrar por línea de comandos.
• s_fide_gui (Windows): dos accesos directos más al primer arranque, además del de la aplicación — abren en el navegador la Guía de Usuario y este mismo Manual Técnico (ver sección 9.14).
• Corregido un error real en PDFVerifySignatures: el campo "Algoritmo de firma" informaba el algoritmo con que la CA firmó el certificado del firmante, no el de la firma del documento — ver sección 7.6. Puramente informativo, no afecta el resultado de la verificación.
• Migración de los tres firmadores de PDF a la API vigente de iText 8 (SignerProperties/SignatureFieldAppearance en vez de PdfSignatureAppearance, deprecado) — sin cambio de comportamiento observable, verificado firmando y verificando documentos reales.
• Corregido en XMLVerifyXSDStructure: si la descarga del esquema XSD fallaba por un problema de certificado SSL, DNS o conexión, la advertencia mostrada exponía el mensaje interno de la excepción de Java tal cual, incluyendo nombres de clases internas de la JVM — ver sección 9.7. Ahora se traduce a un mensaje simple según el tipo de falla; puramente cosmético, no cambia si la validación termina en éxito o error.

v1.0.0 (2024-12) — primer release estable

Suite inicial de 10 módulos más la GUI JavaFX.

Guía de migración desde 1.0.0

Si ya tenías una integración funcionando contra los jars de S-FiDE 1.0.0, la gran mayoría de los cambios de 1.1.1 son aditivos (flags opcionales nuevos, módulos nuevos) y no requieren ningún cambio de tu lado. Esta guía identifica puntualmente los pocos casos donde cambió el comportamiento de un jar que ya usabas en 1.0.0. No aplica a XMLSignerWindowsCSP.jar/PDFSignerWindowsCSP.jar: son módulos nuevos, no existían en 1.0.0.

Glosario

Soporte y contacto

Grupo Sauken S.A. — Córdoba, Argentina

Email: soporte@sauken.com.ar · Sitio: www.sauken.com.ar · Repositorio: github.com/Grupo-Sauken-S-A/S-FIDE

El software se distribuye libremente bajo GNU GPLv2 o posterior. El soporte técnico es un servicio comercial, con cargo, independiente de la licencia de uso.