Configuración de SSigner API REST¶

Variables de Entorno¶

La API se configura principalmente mediante variables de entorno. Aquí están las más importantes:

Variable	Descripción	Valor por defecto
`SERVER_PORT`	Puerto donde se ejecuta el servicio	`8087`
`DB_URL`	URL de PostgreSQL	`changeme`
`DB_USERNAME`	Usuario de la base de datos	`changeme`
`DB_PASSWORD`	Contraseña de la base de datos	`changeme`
`JWT_SECRET_KEY`	Clave secreta JWT	`changeme`
`SSIGNER_BASE_PATH`	Ruta donde se guardan archivos	`/opt/ssigner/users`
`SSIGNER_FIRMA_DEFAULTS_FIRMA_CREADOR`	Valor por defecto de `firma.creador`	(vacío; usa `SSigner v2.5.2`)
`SSIGNER_FIRMA_DEFAULTS_FIRMA_CREADOR_HABILITAR`	Valor por defecto de `firma.creador.habilitar`	(vacío; usa `true`)

Configuración de la base de datos¶

La API usa PostgreSQL. Asegúrate de crear la base de datos antes de iniciar:

# Crear base de datos
createdb -h localhost -U postgres ssigner

# Crear usuario
psql -h localhost -U postgres -c "CREATE USER ssigner WITH PASSWORD 'tu_password';"
psql -h localhost -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE ssigner TO ssigner;"

Clave JWT¶

La clave JWT debe ser Base64 de 64 caracteres. Para generar una:

openssl rand -base64 64

Propiedades de la Aplicación¶

Configuración del servidor¶

server:
  port: ${SERVER_PORT:8087}
  tomcat:
    threads:
      max: 300          # Hilos máximos de procesamiento
      min-spare: 20     # Hilos en espera
    max-connections: 10000
    accept-count: 100

Configuración de seguridad¶

application:
  security:
    jwt:
      secret-key: ${JWT_SECRET_KEY}
      expiration: ${JWT_EXPIRATION:86400000}        # 24 horas en ms
      refresh-token:
        expiration: ${JWT_REFRESH_EXPIRATION:604800000}  # 7 días en ms

Configuración del Motor de Firma¶

La API utiliza un archivo de configuración predeterminado para el motor de firma. Este archivo está en:

src/main/resources/ssigner-config_predeterminado.properties

Propiedades principales del motor¶

Propiedad	Descripción	Valor por defecto
`firma.perfil`	Perfil de firma: PAdES-B, PAdES-BT, PAdES-LT, PAdES-LTA, CAdES-B, CAdES-BT, PKCS7-B, PKCS7-BT, PKCS7-LT o PKCS7-LTA	`PAdES-B`
`firma.creador`	Nombre de producto o versión registrado como metadata de creador en la firma PDF	`SSigner v2.5.2`
`firma.creador.habilitar`	Agregar u omitir la metadata de creador en la firma PDF	`true`
`firma.coordenadas.unidad`	Unidad de coordenadas	`pixeles`
`firma.coordenadas.convertir.desde.pixeles`	Convertir píxeles a puntos	`true`
`firma.imagen.modo`	Modo de ajuste de imagen; actualmente el comportamiento implementado equivale a `escalar`	`escalar`
`firma.imagen.mantener.proporcion`	Mantener proporción al limitar dimensiones de imagen	`true`
`firma.imagen.maximo.ancho`	Ancho máximo de imagen en puntos (`0` = sin límite)	`0`
`firma.imagen.maximo.alto`	Alto máximo de imagen en puntos (`0` = sin límite)	`0`
`glosa.habilitar`	Habilitar glosa legal	`true`
`glosa.url`	URL de verificación	(según proveedor)
`glosa.barras.habilitar`	Incluir código de barras	`false`
`glosa.qr.habilitar`	Incluir código QR	`true`
`tsa.habilitar`	Habilitar sello de tiempo	`0`
`tsa.url`	URL del servidor TSA	(según proveedor)
`ssigner.log.level`	Nivel de logs	`info`

Estructura de Carpetas¶

La API organiza los archivos de cada firmante en carpetas:

{SSIGNER_BASE_PATH}/
└── {idFirmante}/
    ├── entrada/
    │   ├── documento.pdf
    │   ├── documento.pdf.prefirma
    │   └── documento.pdf.prefirma.sha256
    ├── salida/
    │   └── documento_signed.pdf
    ├── imagen/
    │   └── firma.png
    ├── cache/
    │   └── certificado.pem
    └── config/
        ├── propiedades_generales.properties
        └── *_doc.properties (por documento)

Cada firmante tiene su propia carpeta identificada por su ID (DNI, RUC, etc.).

Niveles de Logging¶

Controla cuánto detalle quieres en los logs:

Nivel	Descripción
`debug`	Todo, incluyendo información de desarrollo
`info`	Eventos principales del sistema
`warn`	Solo advertencias y errores
`error`	Solo errores críticos

Ejemplo de Configuración Completa¶

Variables de entorno¶

# Base de datos
export DB_URL=jdbc:postgresql://localhost:5432/ssigner
export DB_USERNAME=ssigner
export DB_PASSWORD=MiPasswordSeguro123

# Seguridad
export JWT_SECRET_KEY=AQuiVaTuClaveBase64De64CaracteresExactos12345678901234567890

# Rutas
export SSIGNER_BASE_PATH=/opt/ssigner/users

# Metadata de creador de la firma PDF
export SSIGNER_FIRMA_DEFAULTS_FIRMA_CREADOR="SSigner v2.5.2"
export SSIGNER_FIRMA_DEFAULTS_FIRMA_CREADOR_HABILITAR=true

# Servidor
export SERVER_PORT=8087

En el codigo actual, si no defines estas variables, DB_URL, DB_USERNAME, DB_PASSWORD y JWT_SECRET_KEY quedan como changeme; son placeholders y deben cambiarse antes de usar el servicio fuera de desarrollo local. Los valores de PostgreSQL del ejemplo son sugeridos para una instalacion local, no defaults del codigo.

Archivo de configuración del motor¶

# Tipo de firma PAdES
firma.perfil=PAdES-B

# Metadata de creador de la firma PDF
firma.creador=SSigner v2.5.2
firma.creador.habilitar=true

# Imagen de firma
firma.imagen.modo=escalar
firma.imagen.mantener.proporcion=true
firma.imagen.maximo.ancho=0
firma.imagen.maximo.alto=0

# Coordenadas en píxeles (convertir a puntos automáticamente)
firma.coordenadas.unidad=pixeles
firma.coordenadas.convertir.desde.pixeles=true

# Glosa legal
glosa.habilitar=true
glosa.url=https://verificador.gob.pe
glosa.qr.habilitar=true

# TSA (Time Stamping Authority)
tsa.habilitar=0

# Logging
ssigner.log.level=info

Validación de Certificados¶

Puedes configurar cómo se validan los certificados digitales:

Propiedad	Descripción	Valor típico
`certificado.validar`	Validación obligatoria del certificado	`true`
`certificado.validar.crl`	Validación CRL obligatoria	`true`
`certificado.validar.ocsp`	Validación OCSP obligatoria	`true`
`certificado.validar.tsl`	Validación TSL obligatoria	`true`
`tsl.urls`	URL de la TSL	`https://iofe.indecopi.gob.pe/TSL/tsl-pe.xml`

Notas de Implementación¶

Arquitectura de la API¶

Framework: Spring Boot 4.x con Java 17
Seguridad: JWT con tokens de acceso y refresh
Persistencia: PostgreSQL con JPA/Hibernate
Procesamiento asíncrono: Hilos para procesamiento paralelo

Límites de rendimiento¶

Conexiones máximas: 10,000
Hilos de procesamiento: 300
Cola de aceptación: 100

Recomendaciones¶

Usa HTTPS en producción para proteger los tokens
Configura el pool de conexiones según tu capacidad de PostgreSQL
Monitorea los logs para detectar problemas de rendimiento
Respaldar la base de datos regularmente

Timeout del proxy para insertar firmas¶

El endpoint POST /api/v2/ssigner/insertar-hash-firmado ejecuta el motor de forma síncrona. Si la API se publica detrás de OpenResty o Nginx, el timeout del proxy debe ser mayor que el tiempo máximo esperado del motor:

location /api/v2/ssigner/insertar-hash-firmado {
    # Mantener aquí el proxy_pass actual.
    proxy_connect_timeout 60s;
    proxy_send_timeout 900s;
    proxy_read_timeout 900s;
    send_timeout 900s;
}

Después de modificar la configuración, valide con nginx -t y recargue OpenResty. El parámetro server.tomcat.connection-timeout controla el establecimiento de la conexión, no el tiempo total de ejecución de este endpoint.