💡 Ejemplo completo disponible en GitHub: sign-pdf-with-vault-managed-key-java
El método antiguo era doloroso
El manual de operaciones para un servicio de firma Java tiende a contener un paso que a nadie le gusta escribir: copiar signing.pfx al nuevo host, luego colocar la contraseña en el entorno. Desde ese momento la clave privada existe en al menos tres lugares más de los que cualquiera pretendía. Está en la capa de la imagen, en la copia de seguridad del host y en la memoria de la JVM que la carga, donde un volcado de heap la mostrará felizmente a quien tenga el volcado.
La firma externa es una capacidad de GroupDocs.Signature para Java que entrega el resumen del documento a una devolución de llamada que usted proporciona en lugar de firmar con una clave privada que la aplicación carga. Es la pieza que le permite eliminar ese paso del manual. La clave de firma se traslada a HashiCorp Vault, el servicio conserva un token en lugar de una clave, y el único valor que cruza el cable durante la firma es un hash de 32 bytes.
Los equipos recurren a esto cuando una revisión plantea la obvia pregunta: ¿quién más puede firmar en su nombre? y la respuesta honesta es “cualquiera que haya tenido acceso a ese archivo”. Bloquear el archivo con permisos y un volumen cifrado reduce la ventana; no elimina la copia.
Hay una forma mejor
El motor Transit de Vault realiza criptografía como servicio. Usted le envía un valor, él firma con una clave que posee y devuelve el resultado. Una clave creada dentro de Transit puede marcarse como no exportable, de modo que no hay nada que copiar a un host en primer lugar, y Vault no almacena lo que usted le envía.
Eso solo ayuda si la biblioteca de firma puede delegar, que es donde entra GroupDocs.Signature. DigitalSignOptions.setCustomSignHash acepta una devolución de llamada. La biblioteca hace todo hasta la criptografía: abre el PDF, determina el rango de bytes que cubre la firma, lo hash, llama a su devolución de llamada con el resumen y luego incrusta los bytes que regresa junto con el certificado.
Necesita JDK 8 o posterior, Maven, Docker para un Vault local y BouncyCastle para el certificado. El ejemplo se ejecuta con GroupDocs.Signature para Java 26.10; sin licencia, el modo de evaluación acepta documentos de hasta 2 páginas.
La nueva forma: una devolución de llamada en lugar de un archivo de clave
Paso 1 - Leer la clave de Vault
El servicio solicita a Vault la clave que está autorizado a usar y obtiene un número de versión con una clave pública. La mitad privada nunca está en la respuesta.
VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
vault.enableTransit();
vault.createKey(KEY_NAME, "rsa-2048");
key = vault.readKey(KEY_NAME);
}
Un 404 de Vault significa que falta la clave o el montaje Transit, por lo que el ejemplo lo trata como una configuración de primera ejecución en lugar de un error. En producción un administrador habilita Transit y crea la clave con anticipación, y el token de la aplicación no está autorizado a hacer ninguno de los dos.
Lea la versión una vez y consérvela. Un certificado contiene exactamente una clave pública, por lo que el certificado y cada firma deben provenir de la misma versión.
Paso 2 - Construir un certificado alrededor de la mitad pública
Una firma PDF lleva un certificado X.509 para que un verificador pueda encontrar la clave pública. El JDK no tiene forma de crear un certificado cuya firma provenga de otro lugar, pero BouncyCastle sí: X509v3CertificateBuilder delega a un ContentSigner, y un ContentSigner respaldado por Vault ocupa unas quince líneas.
@Override
public byte[] getSignature() {
try {
byte[] digest =
MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
return vault.signHash(keyName, keyVersion, digest, "sha2-256");
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
BouncyCastle escribe los bytes a firmar en el flujo del firmante y luego solicita la firma. Los bytes se hash localmente y solo el resumen se envía a Vault. La interfaz no declara excepciones comprobadas, por lo que una falla de Vault debe propagarse envuelta y ser desempaquetada por el llamador; omítalo y un 403 de Vault aparece como un error de tiempo de ejecución desconcertante.
Paso 3 - Firmar y luego verificar en la misma ejecución
DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);
DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);
ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));
Dentro de la devolución de llamada el resumen se envía a transit/sign con dos campos que deciden si el resultado es válido: prehashed = true, porque la entrada ya es un hash, y signature_algorithm = pkcs1v15, porque Vault usa PSS por defecto para claves RSA mientras que una firma PDF es sha256WithRSAEncryption.
Luego verifique antes de que el archivo vaya a cualquier lado. Firmar y verificar en una sola ejecución es lo que convierte el único modo de falla silenciosa en uno inmediato.
Comparación lado a lado: Antes vs. Después
| PFX en el host | Devolución de llamada de Vault Transit | |
|---|---|---|
| Copias de la clave privada | una por host, imagen y copia de seguridad | una, dentro de Vault |
| Lo que el servicio conserva | la clave y su contraseña | un token limitado a dos operaciones |
| Paso de despliegue para un nuevo host | copiar el PFX, establecer la contraseña | nada |
| Registro de cada firma | registros de la aplicación, si se escriben | una entrada de auditoría de Vault |
| Después de una fuga sospechada | revocar, volver a emitir, redeplegar en todas partes | rotar en Vault, volver a emitir una vez |
| Quién puede firmar como usted | cualquiera con el archivo y la contraseña | cualquiera con un token válido de Vault |
La última fila vale la pena expresar claramente: esto traslada el secreto en lugar de abolirlo. La diferencia es que un token es de corta duración, revocable en un solo lugar, limitado a leer una clave y a llamar a firmar, y se registra cada vez que se usa.
Ejemplo del mundo real: un servicio de estados de cuenta
Un servicio genera estados de cuenta mensuales y firma cada uno antes de depositarlo en un portal de cliente. Con la configuración antigua su imagen de contenedor llevaba el certificado, y tres personas tenían la contraseña porque alguien tenía que rotarla. Con la devolución de llamada, la imagen no lleva ningún secreto: el pod recibe un token AppRole al iniciar, la política en vault/sample-signer.hcl permite leer la clave y firmar con ella, y cualquier otro intento del token devuelve 403 permission denied.
Cuando el auditor pregunta cuántos documentos se firmaron en marzo y con qué versión de clave, la respuesta proviene del dispositivo de auditoría de Vault en lugar de buscar en los registros de la aplicación.
La rotación es donde este diseño muestra su valor, y también donde puede causar problemas. Después de transit/keys/:name/rotate Vault firma con la versión más reciente a menos que usted indique lo contrario, de modo que un certificado creado para la versión 1 combinado con una firma de la versión 2 produce un PDF que no muestra error y no verifica. Como el firmante se construye con una versión, eso no puede suceder por accidente aquí: el servicio de estados de cuenta sigue firmando con la versión a la que pertenece su certificado hasta que alguien emite un nuevo certificado para la nueva versión. Establecer min_encryption_version en la clave después hace que la versión antigua sea inutilizable, lo que Vault reporta como una negativa a firmar en lugar de como una firma incorrecta.
¿Qué peculiaridades debo esperar en la versión 26.10?
Cuatro, todas encontradas al ejecutar esta compilación. El nombre del método ICustomSignHash está ofuscado en el JAR, así que pase una referencia de método en lugar de implementar la interfaz. La salida firmada llega con bytes cero al final fuera de la firma, así que elimínelos. DigitalVerifyOptions requiere un archivo de certificado, no un flujo. Y el cuadro de firma visible necesita Arial instalado.
¿Qué más puede hacer con GroupDocs.Signature?
La devolución de llamada no sabe qué hay detrás, por lo que los mismos tres pasos funcionan contra un módulo de hardware, una tarjeta inteligente o un KMS en la nube. Porté esto de las versiones .NET y Python del mismo ejemplo, y el cuerpo de la solicitud a Vault llegó sin cambios; la construcción del certificado y esas cuatro peculiaridades son las únicas partes genuinamente específicas de Java. Más allá de firmas digitales, la biblioteca también agrega y busca firmas de texto, imagen, código de barras, código QR y metadatos en PDF, Word, Excel, PowerPoint y formatos de imagen.
Conclusión
Firmar un PDF en Java sin poseer la clave privada requiere una devolución de llamada, un certificado construido alrededor de una clave pública y un token con dos derechos. El ejemplo se ejecuta contra un Vault en modo dev en dos comandos, y el mismo código apunta a un Vault de producción cambiando VAULT_ADDR y VAULT_TOKEN.