Configuración del Motor SSigner¶

Introducción¶

El motor de firma digital SSigner se configura mediante un archivo de propiedades (ssigner.properties). Este documento explica cada opción disponible de forma clara y práctica para el usuario final.

Estructura del Archivo de Configuración¶

1. Proxy¶

Si tu organización usa un servidor proxy para acceder a internet, configura estos valores:

Propiedad	Descripción
`proxy.url`	Dirección del proxy (ej: `http://proxy.empresa.com`)
`proxy.puerto`	Puerto del proxy (ej: `8080`)
`proxy.usuario`	Usuario para autenticación en el proxy (dejar vacío si no requiere)
`proxy.clave`	Contraseña del proxy

2. Repositorio de Claves (Certificado Digital)¶

El certificado digital es el elemento central para firmar documentos. El motor soporta tres tipos de almacenamiento:

Tipo de keystore¶

Propiedad	Valores posibles	Descripción
`firma.repositorio`	`Windows-My`, `PKCS11`, `PKCS12`	Donde está almacenado tu certificado

Configuración por tipo¶

Windows (Certificados de Windows):

firma.repositorio=Windows-My
firma.alias=tu_alias_del_certificado

Token USB o HSM (PKCS#11):

firma.repositorio=PKCS11
firma.repositorio.pkcs11.libreria=C:/ruta/a/libreria_pkcs11.dll
firma.repositorio.pkcs11.clave=tu_pin
firma.alias=tu_alias

Archivo P12/PFX:

firma.repositorio=PKCS12
firma.repositorio.pkcs12.archivo=C:/ruta/certificado.p12
firma.repositorio.pkcs12.clave=contraseña_del_archivo

Propiedad	Descripción
`firma.separador`	Carácter separador para campos múltiples (normalmente `>`)

3. Apariencia de la Firma¶

Define cómo se verá la firma digital en el documento.

Propiedades básicas¶

Propiedad	Valores	Descripción
`firma.visible`	`true` / `false`	Si la firma será visible en el documento
`firma.motivo`	Texto libre	Razón de la firma (ej: "Aprobación de documento")
`firma.locacion`	Texto libre	Ubicación donde se firma (ej: "Lima, Perú")
`firma.norepudio`	`true` / `false`	Incluye prueba de no repudiación

Ubicación en el documento¶

Propiedad	Descripción
`firma.pagina`	Número de página donde aparecerá la firma (1 = primera)
`firma.paginas.varias`	`true` = firma en todas las páginas, `false` = solo en una
`firma.x`, `firma.y`	Coordenadas de la esquina inferior izquierda (en píxeles)
`firma.x1`, `firma.y1`	Coordenadas de la esquina superior derecha
`firma.posicion.relativa`	Permite posicionar relativo a un campo específico
`firma.etiqueta`	Nombre del campo en el PDF donde ubicar la firma

Algoritmo y tipo¶

Propiedad	Valores	Descripción
`firma.algoritmo`	`SHA256`, `SHA384`, `SHA512`	Algoritmo de hash para la firma
`firma.perfil`	`PAdES-B`, `PAdES-BT`, `PAdES-LT`, `PAdES-LTA`, `CAdES-B`, `CAdES-BT`, `PKCS7-B`, `PKCS7-BT`, `PKCS7-LT`, `PKCS7-LTA`	Perfil de firma; determina TSA, DSS y sello de archivo. `XAdES-B`/`XAdES-BT` (firma de XML) también existen, pero solo en la rama `xades-dss` — ver Funcionalidades.
`firma.estilo`	Ver tabla de estilos	Estilo visual de la firma. Se recomiendan nombres textuales; los números se conservan por compatibilidad.
`firma.cerrar`	`true` / `false`	Cerrar documento después de firmar

Información del creador¶

Estas propiedades controlan la metadata de creador que se agrega a la apariencia de firma PDF mediante setSignatureCreator.

Propiedad	Valores	Descripción
`firma.creador`	Texto libre	Nombre de producto o versión que se registra como creador de la firma. Por defecto: `SSigner v2.5.2`.
`firma.creador.habilitar`	`true` / `false`	Si es `true`, agrega `firma.creador` como metadata de creador. Si es `false`, omite esa metadata.

4. Texto de la Firma¶

El texto que aparece junto con la firma puede incluir información dinámica del certificado.

Propiedad	Descripción
`firma.texto`	Texto a mostrar (usa placeholders como `[CN]`, `[FECHA]`)
`firma.texto.fuente`	Nombre de la fuente (ej: `Helvetica`, `Arial`)
`firma.texto.tamanio`	Tamaño de la fuente en puntos

Placeholders disponibles¶

Placeholder	Se reemplaza por
`[CN]`	Nombre del firmante (Common Name)
`[O]`	Organización
`[OU]`	Unidad organizacional
`[T]`	Título
`[C]`	País
`[ST]`	Estado o provincia
`[L]`	Localidad
`[E]`	Correo electrónico
`[MOTIVO]`	Motivo de la firma
`[LOCACION]`	Ubicación
`[FECHA]`	Fecha actual (dd/MM/yyyy)
`[HORA]`	Hora actual (HH:mm:ss)
`[FECHA_HORA]`	Fecha y hora completa

Alineación del texto¶

Propiedad	Valores posibles	Descripción
`firma.texto.alineacion.horizontal`	`LEFT`, `CENTER`, `RIGHT`, `JUSTIFIED`	Alineación horizontal
`firma.texto.alineacion.vertical`	`TOP`, `MIDDLE`, `BOTTOM`	Alineación vertical

5. Imagen de Firma¶

Si deseas incluir una imagen (como una firma manuscrita escaneada) en la firma digital:

Propiedad	Descripción
`firma.imagen`	Nombre o ruta de la imagen principal (PNG o JPG). Si se envía un nombre relativo, se resuelve dentro de `firma.carpeta.imagen`.
`firma.imagen.fondo`	Imagen de fondo (reservada para estilos que usen imagen de fondo).

La imagen se usa cuando firma.estilo requiere componente gráfico:

Estilo	Uso de la imagen
`1`	Solo imagen. iText ajusta la imagen al área visible de la firma.
`2`	Texto a la izquierda e imagen a la derecha.
`3`	Imagen a la izquierda y texto a la derecha.
`4`	Imagen arriba y texto abajo.
`5`	Texto arriba e imagen abajo.
`6`	Imagen como fondo y texto encima.
`8`	Imagen a la izquierda con porcentajes personalizados para dividir el área entre imagen y texto.

Si firma.estilo=texto o nombre-texto, firma.imagen no participa en la apariencia visible.

Dimensiones de imagen¶

Propiedad	Descripción
`firma.imagen.ancho`	Ancho explícito de la imagen en puntos. `0` o vacío = cálculo automático.
`firma.imagen.alto`	Alto explícito de la imagen en puntos. `0` o vacío = cálculo automático.
`firma.imagen.maximo.ancho`	Ancho máximo permitido en puntos. `0` = sin límite explícito.
`firma.imagen.maximo.alto`	Alto máximo permitido en puntos. `0` = sin límite explícito.

Comportamiento efectivo:

Si firma.imagen.ancho y firma.imagen.alto son mayores que 0, el motor fuerza esas dimensiones y desactiva el autoescalado de iText para esa imagen.
Si no se definen dimensiones explícitas, el motor deja que iText autoescale la imagen en estilos con layout horizontal (2, 3, 8) o calcula el tamaño según la mitad del alto del campo en layouts verticales (4, 5).
firma.imagen.maximo.ancho y firma.imagen.maximo.alto se aplican en los estilos verticales (4 y 5) para limitar el tamaño calculado. En estilos horizontales (2, 3, 8) el espacio disponible queda determinado por la celda de imagen, firma.imagen.ancho, firma.imagen.alto y, en 8, los porcentajes personalizados.
Las medidas están en puntos PDF. Si trabajas en píxeles para el recuadro de firma, recuerda que esa conversión aplica a las coordenadas del campo, no al tamaño explícito de imagen.

Comportamiento de la imagen¶

Propiedad	Valores	Descripción
`firma.imagen.mantener.proporcion`	`true` / `false`	Mantiene la relación ancho/alto original cuando el motor reduce la imagen por `firma.imagen.maximo.ancho` o `firma.imagen.maximo.alto`.
`firma.imagen.modo`	`escalar`, `recortar`, `ajustar`	Modo declarado de ajuste. Actualmente el motor lo carga como configuración, pero el comportamiento implementado es equivalente a `escalar`; `recortar` y `ajustar` no ejecutan una rama distinta.

Detalle de firma.imagen.modo:

escalar: comportamiento actual. La imagen se escala para caber en el área asignada o en las dimensiones explícitas configuradas.
recortar: valor aceptado para compatibilidad de configuración, pero actualmente no recorta la imagen.
ajustar: valor aceptado para compatibilidad de configuración, pero actualmente no aplica un algoritmo diferente a escalar.

Para evitar distorsión, mantén firma.imagen.mantener.proporcion=true y configura solo máximos (firma.imagen.maximo.ancho, firma.imagen.maximo.alto) cuando uses estilos 4 o 5. Si necesitas un tamaño exacto, configura ambos valores firma.imagen.ancho y firma.imagen.alto.

Alineación de la imagen¶

Propiedad	Valores	Descripción
`firma.imagen.alineacion.horizontal`	`LEFT`, `CENTER`, `RIGHT`	Alineación horizontal
`firma.imagen.alineacion.vertical`	`TOP`, `MIDDLE`, `BOTTOM`	Alineación vertical

La alineación se aplica a la celda o área reservada para la imagen. Su efecto es más visible cuando la imagen no ocupa todo el espacio disponible, por ejemplo cuando se configuraron dimensiones explícitas o máximos.

Ejemplos de configuración de imagen¶

Imagen a la izquierda con texto a la derecha:

firma.estilo=texto-imagen-izquierda
firma.imagen=firma.png
firma.imagen.ancho=0
firma.imagen.alto=0
firma.imagen.alineacion.horizontal=CENTER
firma.imagen.alineacion.vertical=MIDDLE

Imagen arriba con límites y proporción conservada:

firma.estilo=texto-imagen-arriba
firma.imagen=firma.png
firma.imagen.maximo.ancho=120
firma.imagen.maximo.alto=50
firma.imagen.mantener.proporcion=true
firma.imagen.modo=escalar

Tamaño fijo de imagen:

firma.estilo=texto-imagen-derecha
firma.imagen=firma.png
firma.imagen.ancho=80
firma.imagen.alto=40

Recetas frecuentes¶

Quiero que toda la imagen entre dentro del cuadro de firma

Usa una firma visible solo con imagen (firma.estilo=imagen). En este estilo el motor entrega la imagen a iText como SignatureGraphic y usa RenderingMode.GRAPHIC; iText la ajusta dentro del rectángulo de firma definido por firma.x, firma.y, firma.x1 y firma.y1.

firma.visible=true
firma.estilo=imagen
firma.imagen=firma.png

# Recuadro visible de la firma
firma.x=100
firma.y=100
firma.x1=250
firma.y1=180

# No fuerces dimensiones manuales
firma.imagen.ancho=0
firma.imagen.alto=0

En este caso la imagen completa entra en el cuadro. Si la proporción de la imagen no coincide con la proporción del recuadro, puede quedar espacio libre horizontal o vertical. Para un resultado limpio, procura que la imagen tenga una proporción parecida al recuadro.

Quiero que la imagen entre completa, pero también mostrar texto

Elige un estilo que reserve espacio para ambos elementos. Por ejemplo, con imagen a la izquierda y texto a la derecha:

firma.visible=true
firma.estilo=texto-imagen-izquierda
firma.imagen=firma.png
firma.texto=Firmado por [CN]

# Recuadro completo de firma
firma.x=100
firma.y=100
firma.x1=300
firma.y1=180

# Deja que iText autoescale dentro de la celda de imagen
firma.imagen.ancho=0
firma.imagen.alto=0
firma.imagen.alineacion.horizontal=CENTER
firma.imagen.alineacion.vertical=MIDDLE

En firma.estilo=texto-imagen-izquierda, el cuadro se divide aproximadamente en dos columnas: imagen y texto. La imagen completa entra en su celda, no necesariamente en todo el cuadro de firma. Si necesitas más espacio para la imagen, usa firma.estilo=texto-imagen-izquierda-personalizado con porcentajes personalizados:

firma.visible=true
firma.estilo=texto-imagen-izquierda-personalizado
firma.porcentajes=70>30
firma.separador=>
firma.imagen=firma.png
firma.texto=Firmado por [CN]
firma.imagen.alineacion.horizontal=CENTER
firma.imagen.alineacion.vertical=MIDDLE

firma.porcentajes=70>30 asigna 70% del ancho a la imagen y 30% al texto.

Quiero evitar que la imagen se deforme

No configures solo una dimensión. Si necesitas controlar tamaño, usa máximos y conserva proporción:

firma.estilo=texto-imagen-arriba
firma.imagen=firma.png
firma.imagen.maximo.ancho=120
firma.imagen.maximo.alto=50
firma.imagen.mantener.proporcion=true
firma.imagen.ancho=0
firma.imagen.alto=0

Esto es especialmente útil en firma.estilo=texto-imagen-arriba y firma.estilo=texto-imagen-abajo, donde el motor calcula el tamaño de imagen y luego lo limita con firma.imagen.maximo.ancho y firma.imagen.maximo.alto.

Quiero un tamaño exacto aunque cambie la proporción

Configura ambos valores explícitos:

firma.estilo=texto-imagen-derecha
firma.imagen=firma.png
firma.imagen.ancho=100
firma.imagen.alto=40

Con ambos valores mayores que 0, el motor fuerza ese ancho y alto. Si la imagen original tiene otra proporción, puede verse estirada o comprimida.

6. Espaciado y Padding¶

Controla el espacio entre elementos de la firma y los márgenes internos.

Propiedad	Descripción	Valor típico
`firma.espacio.texto.imagen`	Espacio entre texto e imagen	`10`
`firma.padding.texto.top`	Margen superior del texto	`0`
`firma.padding.texto.right`	Margen derecho del texto	`0`
`firma.padding.texto.bottom`	Margen inferior del texto	`0`
`firma.padding.texto.left`	Margen izquierdo del texto	`5`
`firma.padding.imagen.top`	Margen superior de la imagen	`0`
`firma.padding.imagen.right`	Margen derecho de la imagen	`5`
`firma.padding.imagen.bottom`	Margen inferior de la imagen	`0`
`firma.padding.imagen.left`	Margen izquierdo de la imagen	`0`
`firma.multipliedLeading`	Factor de interlineado	`0.85`

Alineación del campo firma¶

Propiedad	Valores	Descripción
`firma.campo.alineacion.horizontal`	`LEFT`, `CENTER`, `RIGHT`	Alineación horizontal del campo
`firma.campo.alineacion.vertical`	`TOP`, `MIDDLE`, `BOTTOM`	Alineación vertical del campo

7. Fecha y Hora¶

Propiedad	Descripción
`firma.fecha.hora`	Forzar una fecha/hora específica (dejar vacío para usar la actual)
`firma.fecha.hora.formato`	Formato de fecha (ej: `yyyy.MM.dd HH:mm:ss z`)

8. Carpetas de Trabajo¶

Define dónde están los archivos de entrada, salida y recursos.

Propiedad	Descripción
`firma.carpeta.entrada`	Carpeta con los documentos a firmar
`firma.carpeta.salida`	Carpeta donde se guardarán los documentos firmados
`firma.carpeta.cache`	Carpeta para archivos temporales
`firma.carpeta.imagen`	Carpeta donde están las imágenes de firma
`firma.carpeta.config`	Carpeta con archivos de configuración adicionales
`documento`	Nombre del archivo que lista los documentos a firmar

9. Time Stamping Authority (TSA)¶

Un sello de tiempo añade validez a largo plazo a la firma. Si tu organización tiene un servidor TSA:

Propiedad	Descripción
`tsa.habilitar`	Derivada de `firma.perfil`; no debe configurarse manualmente
`tsa.url`	URL del servidor TSA (ej: `http://tsa.example.com`)
`tsa.usuario`	Usuario para autenticación (cifrado AES)
`tsa.clave`	Contraseña del servicio TSA (cifrado AES)
`tsa.cadena.incluir.raiz`	Incluir el root TSA embebido (`false` por defecto; actívalo solo si tu política exige mostrarlo en el contenedor)

10. Validación de Certificados¶

Configura cómo se valida el certificado digital durante el proceso de firma.

Propiedad	Valores	Descripción
`certificado.validar`	`true`	La validación del certificado se fuerza siempre en el motor
`certificado.validar.crl`	`true`	La validación CRL se fuerza siempre en el motor
`certificado.validar.ocsp`	`true`	La validación OCSP se fuerza siempre en el motor
`certificado.validar.tsl`	`true`	La validación TSL se fuerza siempre en el motor
`certificado.validar.limite`	Número	Límite de profundidad en la cadena de validación
`tsl.urls`	URLs	URLs de TSL separadas por `\|`. Si se omite o queda vacía, usa `https://iofe.indecopi.gob.pe/TSL/tsl-pe.xml`

11. LTV (Long Term Validation)¶

LTV permite que la firma permanezca válida indefinidamente, incluso si el certificado expira o el servicio de validación deja de estar disponible.

Propiedad	Valores	Descripción
`firma.perfil`	`PAdES-LT`, `PAdES-LTA`, `PKCS7-LT`, `PKCS7-LTA`	Los perfiles `LT` agregan DSS y los perfiles `LTA` agregan ademas Document Timestamp.

12. Glosa (Texto Informativo)¶

La glosa es el texto legal que aparece en el documento firmado, verificable posteriormente.

Propiedad	Descripción
`glosa.habilitar`	`0` = desactivada, `1` = activada
`glosa.url`	URL de verificación (ej: la del INDECOPI)
`glosa.contenido`	Texto legal de la glosa

Elementos de la glosa¶

Propiedad	Valores	Descripción
`glosa.barras.habilitar`	`true` / `false`	Incluir código de barras
`glosa.qr.habilitar`	`true` / `false`	Incluir código QR con link de verificación

Placeholders de glosa¶

Placeholder	Descripción
`{{GLOSA_URL}}`	Se reemplaza con la URL de verificación
`{{GLOSA_CODIGO}}`	Se reemplaza con el código CVD único

Márgenes y dimensiones¶

Propiedad	Descripción	Valor típico
`glosa.margen.superior`	Margen superior en puntos	`50`
`glosa.margen.inferior`	Margen inferior en puntos	`50`
`glosa.margen.izquierdo`	Margen izquierdo en puntos	`50`
`glosa.margen.derecho`	Margen derecho en puntos	`50`
`glosa.ancho.porcentaje`	Ancho de la glosa (% del ancho de página)	`80`
`glosa.padding.celda.top`	Padding superior interno	`8`
`glosa.padding.celda.left`	Padding izquierdo interno	`10`
`glosa.padding.celda.qr`	Espacio adicional para el QR	`0`
`glosa.padding.celda.barra`	Espacio adicional para código de barras	`1`

13. Códigos de Barras y QR¶

Configuración del tamaño de los códigos generados.

Propiedad	Descripción	Valor típico
`qr.ancho`	Ancho del código QR en puntos	`80`
`qr.alto`	Alto del código QR en puntos	`80`
`barra.ancho`	Ancho de cada barra	`0.8`
`barra.alto`	Alto del código de barras	`25`
`barra.baseline`	Posición de la línea base	`10`

14. Configuración de Fuente¶

Propiedad	Descripción	Valor típico
`fuente.tamanio.minimo`	Tamaño mínimo permitido	`3`
`fuente.tamanio.maximo`	Tamaño máximo permitido	`30`
`fuente.tamanio.default`	Tamaño por defecto	`7`

15. Sistema de Coordenadas¶

Propiedad	Valores	Descripción
`firma.coordenadas.unidad`	`puntos`, `pixeles`	Unidad de medida para coordenadas
`firma.coordenadas.convertir.desde.pixeles`	`true` / `false`	Convertir automáticamente coordenadas de píxeles a puntos

16. Logging¶

Controla el nivel de detalle de los logs del sistema.

Propiedad	Valores	Descripción
`ssigner.log.level`	`debug`, `info`, `warn`, `error`	Nivel de logging

Estilos de Apariencia de Firma¶

El parámetro firma.estilo define cómo se combina el texto y la imagen. Use nombres textuales para nuevas configuraciones; los códigos numéricos siguen siendo válidos para configuraciones antiguas.

Valor recomendado	Código compatible	Descripción
`texto`	`0`	Solo texto (sin imagen)
`imagen`	`1`	Solo imagen (sin texto)
`texto-imagen-derecha`	`2`	Texto con imagen a la derecha
`texto-imagen-izquierda`	`3`	Texto con imagen a la izquierda
`texto-imagen-arriba`	`4`	Texto con imagen arriba
`texto-imagen-abajo`	`5`	Texto con imagen abajo
`texto-imagen-fondo`	`6`	Texto con imagen de fondo (marca de agua)
`nombre-texto`	`7`	Nombre del firmante y descripción
`texto-imagen-izquierda-personalizado`	`8`	Texto con imagen a la izquierda con porcentajes personalizados

Ejemplo de Configuración Completa¶

# === IDENTIFICACIÓN ===
firma.repositorio=Windows-My
firma.alias=Mi Cert大唐
firma.separador=>

# === APARIENCIA ===
firma.visible=true
firma.motivo=Aprobación de documento
firma.locacion=Lima, Perú
firma.norepudio=true
firma.pagina=1
firma.paginas.varias=false
firma.algoritmo=SHA256
firma.perfil=PAdES-B
firma.creador=SSigner v2.5.2
firma.creador.habilitar=true
firma.estilo=texto-imagen-derecha
firma.texto=Firmado por [CN] el [FECHA]
firma.texto.fuente=Helvetica
firma.texto.tamanio=7
firma.imagen=firma.png

# === CARPETAS ===
firma.carpeta.entrada=C:/documentos/entrada
firma.carpeta.salida=C:/documentos/salida
firma.carpeta.cache=C:/documentos/cache
firma.carpeta.imagen=C:/documentos/imagenes

# === TSA ===
tsa.habilitar=1
tsa.url=http://tsa.example.com
tsa.usuario=usuario_tsa
tsa.clave=clave_tsa

# === VALIDACIÓN ===
certificado.validar=true
certificado.validar.crl=true
certificado.validar.ocsp=true
certificado.validar.tsl=true
tsl.urls=https://iofe.indecopi.gob.pe/TSL/tsl-pe.xml

# === LTV ===
firma.perfil=PAdES-LT

# === GLOSA ===
glosa.habilitar=true
glosa.url=https://verificador.gob.pe
glosa.contenido=Documento firmado electrónicamente
glosa.qr.habilitar=true

Normalización de Valores Booleanos¶

El motor normaliza automáticamente los valores booleanos:

Valor en archivo	Se interpreta como
`"1"`, `"true"`, `"TRUE"`	`true`
`"0"`, `"false"`, `"FALSE"`	`false`

Solución de Problemas Comunes¶

La firma no aparece en el documento: - Verifica que firma.visible=true - Revisa las coordenadas firma.x, firma.y, firma.x1, firma.y1

Error "Certificado no encontrado": - Confirma que firma.alias coincida exactamente con el alias del certificado - Verifica que el certificado esté en el keystore configurado

La validación OCSP/CRL falla: - Verifica que tienes conexión a internet - Revisa la configuración del proxy si es necesario - Considera deshabilitar temporalmente certificado.validar.ocsp o certificado.validar.crl