💡 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.

Recursos Adicionais