💡 Exemplo completo em funcionamento disponível no GitHub:
sign-pdf-with-vault-managed-key-java
O Modo Antigo Era Doloroso
O runbook para um serviço de assinatura Java tende a conter um passo que ninguém gosta de escrever: copiar signing.pfx para o novo host e, em seguida, colocar a senha no ambiente. A partir desse momento, a chave privada existe em pelo menos três lugares a mais do que alguém pretendia. Ela está na camada da imagem, no backup do host e na memória da JVM que a carrega, onde um dump de heap a mostrará felizmente a quem tiver o dump.
A assinatura externa é um recurso do GroupDocs.Signature para Java que entrega o resumo do documento a um callback que você fornece, em vez de assinar com uma chave privada que a aplicação carrega. É a peça que permite eliminar esse passo do runbook. A chave de assinatura migra para o HashiCorp Vault, o serviço mantém um token em vez de uma chave, e o único valor que atravessa a rede durante a assinatura é um hash de 32 bytes.
As equipes recorrem a isso quando uma revisão faz a pergunta óbvia – quem mais pode assinar em seu nome – e a resposta honesta é “qualquer pessoa que já teve acesso a esse arquivo”. Bloquear o arquivo com permissões e um volume criptografado reduz a janela; não elimina a cópia.
Existe um Caminho Melhor
O mecanismo Transit do Vault faz criptografia como serviço. Você envia um valor, ele assina com uma chave que possui e devolve o resultado. Uma chave criada dentro do Transit pode ser marcada como não exportável, portanto não há nada para copiar para um host em primeiro lugar, e o Vault não armazena o que você envia.
Isso só ajuda se a biblioteca de assinatura puder delegar, e é aí que o GroupDocs.Signature entra. DigitalSignOptions.setCustomSignHash aceita um callback. A biblioteca faz tudo até a criptografia: abre o PDF, calcula o intervalo de bytes que a assinatura cobre, gera o hash, chama seu callback com o resumo e, em seguida, incorpora os bytes retornados junto com o certificado.
Você precisa do JDK 8 ou superior, Maven, Docker para um Vault local e BouncyCastle para o certificado. O exemplo funciona com GroupDocs.Signature para Java 26.10; sem licença, o modo de avaliação aceita documentos de até 2 páginas.
O Novo Caminho: um Callback em vez de um Arquivo de Chave
Etapa 1 – Ler a chave do Vault
O serviço solicita ao Vault a chave que tem permissão para usar e obtém um número de versão com uma chave pública. A metade privada nunca está na resposta.
VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
vault.enableTransit();
vault.createKey(KEY_NAME, "rsa-2048");
key = vault.readKey(KEY_NAME);
}
Um 404 do Vault significa que a chave ou a montagem Transit está ausente, então o exemplo trata isso como configuração de primeira execução em vez de erro. Em produção, um administrador habilita o Transit e cria a chave antecipadamente, e o token da aplicação não tem permissão para fazer nenhum dos dois.
Leia a versão uma vez e mantenha‑a. Um certificado contém exatamente uma chave pública, portanto o certificado e cada assinatura precisam vir da mesma versão.
Etapa 2 – Construir um certificado ao redor da metade pública
Uma assinatura PDF carrega um certificado X.509 para que um verificador possa encontrar a chave pública. O JDK não tem como criar um certificado cuja assinatura venha de outro lugar, mas o BouncyCastle permite: X509v3CertificateBuilder delega a um ContentSigner, e um ContentSigner suportado pelo Vault tem cerca de quinze linhas.
@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);
}
}
O BouncyCastle grava os bytes a serem assinados no fluxo do assinante e então solicita a assinatura. Os bytes são hashados localmente e somente o resumo vai para o Vault. A interface não declara exceções verificadas, portanto uma falha no Vault precisa ser propagada envolvida e desembrulhada pelo chamador; ignore isso e um 403 do Vault aparecerá como um erro de tempo de execução enigmático.
Etapa 3 – Assinar e, em seguida, verificar na mesma execução
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 do callback o resumo vai para transit/sign com dois campos que decidem se o resultado é válido: prehashed = true, porque a entrada já é um hash, e signature_algorithm = pkcs1v15, porque o Vault usa PSS por padrão para chaves RSA, enquanto uma assinatura PDF é sha256WithRSAEncryption.
Então verifique antes que o arquivo vá a qualquer lugar. Assinar e verificar em uma única execução é o que transforma o único modo de falha silenciosa em um modo imediato.
Lado a Lado: Antes vs. Depois
| PFX no host | Callback do Vault Transit | |
|---|---|---|
| Cópias da chave privada | uma por host, imagem e backup | uma, dentro do Vault |
| O que o serviço mantém | a chave e sua senha | um token com escopo para duas operações |
| Etapa de implantação para novo host | copiar o PFX, definir a senha | nada |
| Registro de cada assinatura | logs da aplicação, se houver | uma entrada de auditoria do Vault |
| Após um vazamento suspeito | revogar, reemitir, redeploy em todos os lugares | rotacionar no Vault, reemitir uma vez |
| Quem pode assinar como você | qualquer um com o arquivo e a senha | qualquer um com um token válido do Vault |
A última linha vale a pena ser declarada claramente: isso move o segredo em vez de abolí‑lo. A diferença é que um token é de curta duração, revogável em um único ponto, limitado à leitura de uma chave e à chamada de assinatura, e registrado toda vez que é usado.
Exemplo Real: um Serviço de Extrato
Um serviço gera extratos mensais e assina cada um antes de disponibilizá‑lo em um portal do cliente. Na configuração antiga, a imagem do contêiner carregava o certificado, e três pessoas tinham a senha porque alguém precisava rotacioná‑la. Com o callback, a imagem não carrega nenhum segredo: o pod recebe um token AppRole na inicialização, a política em vault/sample-signer.hcl permite ler a chave e assinar com ela, e qualquer outra tentativa do token retorna 403 permission denied.
Quando o auditor pergunta quantos documentos foram assinados em março e com qual versão de chave, a resposta vem do dispositivo de auditoria do Vault em vez de ser extraída dos logs da aplicação.
A rotação é onde esse design demonstra seu valor, e também onde pode causar problemas. Após transit/keys/:name/rotate o Vault assina com a versão mais nova, a menos que você indique o contrário, de modo que um certificado construído para a versão 1 combinado com uma assinatura da versão 2 gera um PDF que não apresenta erro, mas não verifica. Como o assinante é construído com uma única versão, isso não pode acontecer por acidente aqui: o serviço de extrato continua assinando com a versão à qual seu certificado pertence até que alguém emita um novo certificado para a nova versão. Definir min_encryption_version na chave depois torna a versão antiga inutilizável, o que o Vault relata como recusa de assinatura em vez de assinatura inválida.
Que peculiaridades devo esperar na versão 26.10?
Quatro, todas encontradas ao executar esta compilação. O nome do método ICustomSignHash está ofuscado no JAR, então passe uma referência de método em vez de implementar a interface. A saída assinada chega com bytes zero ao final, fora da assinatura, então remova‑os. DigitalVerifyOptions espera um arquivo de certificado, não um stream. E a caixa de assinatura visível requer a fonte Arial instalada.
O Que Mais Você Pode Fazer com GroupDocs.Signature?
O callback não sabe o que está por trás dele, portanto os mesmos três passos funcionam contra um módulo de hardware, um smart card ou um KMS na nuvem. Eu portei isso das versões .NET e Python do mesmo exemplo, e o corpo da requisição ao Vault chegou inalterado; a construção do certificado e aquelas quatro peculiaridades são as únicas partes genuinamente específicas de Java. Além de assinaturas digitais, a biblioteca também adiciona e pesquisa assinaturas de texto, imagem, código de barras, QR code e metadados em PDF, Word, Excel, PowerPoint e formatos de imagem.
Conclusão
Assinar um PDF em Java sem manter a chave privada requer um callback, um certificado construído ao redor de uma chave pública e um token com dois direitos. O exemplo funciona contra um Vault em modo de desenvolvimento em dois comandos, e o mesmo código aponta para um Vault de produção alterando VAINT_ADDR e VAULT_TOKEN.