MACRO NEPAL
Securing Documents: A Comprehensive Guide to Digital Signatures in PDF with Java
awiskar acharya
November 15, 2025
3:52 am

Digital signatures in PDF documents provide authenticity, integrity, and non-repudiation—proving who signed a document, that it hasn't been altered since signing, and that the signer cannot deny their signature. With the rise of electronic documentation, implementing PDF signing has become a crucial requirement for many Java applications. This guide explores the practical implementation using popular Java libraries.

Understanding PDF Digital Signatures

A digital signature in a PDF is more than just a visual representation; it's a cryptographic operation that:

  1. Creates a Hash: Generates a unique fingerprint (hash) of the PDF content.
  2. Encrypts the Hash: The hash is encrypted with the signer's private key.
  3. Embeds the Signature: The encrypted hash (signature) and certificate are embedded in the PDF.
  4. Validates Integrity: Anyone can verify the signature using the signer's public key to ensure the document hasn't changed.

Key Components and Libraries

Primary Libraries:

  • Apache PDFBox: Popular open-source library for PDF manipulation
  • iText (Commercial): Powerful library with comprehensive signing capabilities
  • Bouncy Castle: Cryptographic provider for handling certificates and keys

Required Components:

  • Private Key: The signer's private key for creating the signature
  • Certificate Chain: X.509 certificate chain including the signer's certificate and any intermediate CAs
  • Keystore: Typically PKCS#12 (.p12 or .pfx) or JKS files containing keys and certificates

Implementation with Apache PDFBox

PDFBox provides excellent support for digital signatures through its "signing" module.

1. Dependencies (Maven)

<dependencies>
<dependency>
<groupId>org.apache.pdfbox</groupId>
<artifactId>pdfbox</artifactId>
<version>3.0.1</version>
</dependency>
<dependency>
<groupId>org.apache.pdfbox</groupId>
<artifactId>pdfbox-io</artifactId>
<version>3.0.1</version>
</dependency>
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcpkix-jdk18on</artifactId>
<version>1.76</version>
</dependency>
</dependencies>

2. Basic PDF Signing

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.interactive.digitalsignature.SignatureInterface;
import org.apache.pdfbox.pdmodel.interactive.digitalsignature.SignatureOptions;
import org.apache.pdfbox.pdmodel.interactive.digitalsignature.visible.PDVisibleSigProperties;
import java.security.*;
import java.security.cert.Certificate;
import java.io.*;
import java.util.Calendar;
public class PDFBoxSigner {
private final String keystorePath;
private final String keystorePassword;
private final String keyAlias;
private final String keyPassword;
public PDFBoxSigner(String keystorePath, String keystorePassword, 
String keyAlias, String keyPassword) {
this.keystorePath = keystorePath;
this.keystorePassword = keystorePassword;
this.keyAlias = keyAlias;
this.keyPassword = keyPassword;
}
public void signPdf(String inputPath, String outputPath, 
String reason, String location) throws Exception {
// Load the keystore
KeyStore keystore = KeyStore.getInstance("PKCS12");
try (FileInputStream fis = new FileInputStream(keystorePath)) {
keystore.load(fis, keystorePassword.toCharArray());
}
// Get private key and certificate chain
PrivateKey privateKey = (PrivateKey) keystore.getKey(keyAlias, keyPassword.toCharArray());
Certificate[] certificateChain = keystore.getCertificateChain(keyAlias);
// Load the PDF document
try (PDDocument document = PDDocument.load(new File(inputPath))) {
// Create signature interface
SignatureInterface signatureInterface = new CustomSignatureInterface(
privateKey, certificateChain
);
// Configure signature options
SignatureOptions signatureOptions = new SignatureOptions();
signatureOptions.setPreferredSignatureSize(12 * 1024); // 12KB reserved space
// Create visible signature properties (optional)
PDVisibleSigProperties visibleSigProperties = new PDVisibleSigProperties();
visibleSigProperties.setsignerName("John Doe")
.setSignatureReason(reason)
.setSignatureLocation(location)
.setPage(1) // Page where signature appears
.setVisualSignEnabled(true); // Enable visible signature
// Apply the signature
document.addSignature(signatureInterface, signatureOptions, visibleSigProperties);
// Save signed document
document.save(new File(outputPath));
}
}
// Custom signature implementation
private static class CustomSignatureInterface implements SignatureInterface {
private final PrivateKey privateKey;
private final Certificate[] certificateChain;
public CustomSignatureInterface(PrivateKey privateKey, Certificate[] certificateChain) {
this.privateKey = privateKey;
this.certificateChain = certificateChain;
}
@Override
public byte[] sign(InputStream content) throws IOException {
try {
// Get the content to be signed
byte[] contentBytes = readContent(content);
// Create signature
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
signature.update(contentBytes);
return signature.sign();
} catch (Exception e) {
throw new IOException("Signing failed", e);
}
}
private byte[] readContent(InputStream input) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
byte[] buffer = new byte[4096];
int bytesRead;
while ((bytesRead = input.read(buffer)) != -1) {
baos.write(buffer, 0, bytesRead);
}
return baos.toByteArray();
}
}
}

3. Usage Example

public class PDFSigningExample {
public static void main(String[] args) {
try {
PDFBoxSigner signer = new PDFBoxSigner(
"keystore.p12",      // PKCS12 keystore
"keystore-password", // Keystore password  
"my-key-alias",      // Key alias in keystore
"key-password"       // Key-specific password
);
signer.signPdf(
"input-document.pdf",
"signed-document.pdf", 
"I approve this document",
"New York, USA"
);
System.out.println("PDF signed successfully!");
} catch (Exception e) {
e.printStackTrace();
}
}
}

Advanced Signing Features

1. Timestamp Authority (TSA) Support

Adding a trusted timestamp provides proof of when the document was signed.

public class AdvancedPDFSigner extends PDFBoxSigner {
private final String tsaUrl;
public AdvancedPDFSigner(String keystorePath, String keystorePassword,
String keyAlias, String keyPassword, String tsaUrl) {
super(keystorePath, keystorePassword, keyAlias, keyPassword);
this.tsaUrl = tsaUrl;
}
@Override
public void signPdf(String inputPath, String outputPath, 
String reason, String location) throws Exception {
// Load keystore and get credentials (same as before)
KeyStore keystore = KeyStore.getInstance("PKCS12");
try (FileInputStream fis = new FileInputStream(keystorePath)) {
keystore.load(fis, keystorePassword.toCharArray());
}
PrivateKey privateKey = (PrivateKey) keystore.getKey(keyAlias, keyPassword.toCharArray());
Certificate[] certificateChain = keystore.getCertificateChain(keyAlias);
try (PDDocument document = PDDocument.load(new File(inputPath))) {
// Create advanced signature interface with TSA
SignatureInterface signatureInterface = new TSASignatureInterface(
privateKey, certificateChain, tsaUrl
);
SignatureOptions signatureOptions = new SignatureOptions();
signatureOptions.setPreferredSignatureSize(15 * 1024);
document.addSignature(signatureInterface, signatureOptions);
document.save(new File(outputPath));
}
}
private static class TSASignatureInterface extends CustomSignatureInterface {
private final String tsaUrl;
public TSASignatureInterface(PrivateKey privateKey, 
Certificate[] certificateChain, String tsaUrl) {
super(privateKey, certificateChain);
this.tsaUrl = tsaUrl;
}
@Override
public byte[] sign(InputStream content) throws IOException {
try {
byte[] contentBytes = readContent(content);
// Create CMS signature
CMSSignedDataGenerator generator = new CMSSignedDataGenerator();
ContentSigner signer = new JcaContentSignerBuilder("SHA256withRSA")
.build(privateKey);
// Add signer
generator.addSignerInfoGenerator(
new JcaSignerInfoGeneratorBuilder(
new JcaDigestCalculatorProviderBuilder().build()
).build(signer, (X509Certificate) certificateChain[0])
);
// Add certificates
generator.addCertificates(new JcaCertStore(Arrays.asList(certificateChain)));
// Generate signature
CMSSignedData signedData = generator.generate(
new CMSProcessableByteArray(contentBytes), true);
// Add timestamp if TSA URL provided
if (tsaUrl != null && !tsaUrl.isEmpty()) {
signedData = addTimeStamp(signedData);
}
return signedData.getEncoded();
} catch (Exception e) {
throw new IOException("Advanced signing failed", e);
}
}
private CMSSignedData addTimeStamp(CMSSignedData signedData) throws Exception {
TimeStampTokenGenerator tokenGenerator = new TimeStampTokenGenerator(
new JcaSimpleSignerInfoGeneratorBuilder().build("SHA256withRSA", privateKey, 
(X509Certificate) certificateChain[0]),
new SHA256DigestCalculator(),
new ASN1ObjectIdentifier("1.2")
);
TimeStampRequestGenerator requestGenerator = new TimeStampRequestGenerator();
TimeStampRequest request = requestGenerator.generate(
new ASN1ObjectIdentifier("1.2.840.113549.1.7.1"), 
signedData.getEncoded()
);
// Make TSA request (implementation depends on TSA service)
TimeStampResponse response = callTSAService(request);
return signedData; // Simplified - actual implementation would merge timestamp
}
private TimeStampResponse callTSAService(TimeStampRequest request) throws Exception {
// Implementation depends on your TSA provider
// Typically involves HTTP POST request with TimeStampRequest
URL url = new URL(tsaUrl);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/timestamp-query");
conn.setDoOutput(true);
try (OutputStream os = conn.getOutputStream()) {
os.write(request.getEncoded());
}
try (InputStream is = conn.getInputStream()) {
return new TimeStampResponse(is);
}
}
}
}

2. Multiple Signatures (Countersigning)

public class MultipleSignatureHandler {
public void addSecondSignature(String signedPdfPath, String outputPath, 
String keystorePath, String password) throws Exception {
try (PDDocument document = PDDocument.load(new File(signedPdfPath))) {
// Check if document already has signatures
if (document.getSignatureDictionaries().isEmpty()) {
throw new IllegalStateException("Document has no existing signatures");
}
// Load second signer's credentials
KeyStore keystore = KeyStore.getInstance("PKCS12");
try (FileInputStream fis = new FileInputStream(keystorePath)) {
keystore.load(fis, password.toCharArray());
}
PrivateKey privateKey = (PrivateKey) keystore.getKey("alias", password.toCharArray());
Certificate[] certificateChain = keystore.getCertificateChain("alias");
// Add second signature
SignatureInterface signatureInterface = new CustomSignatureInterface(
privateKey, certificateChain
);
SignatureOptions signatureOptions = new SignatureOptions();
document.addSignature(signatureInterface, signatureOptions);
document.save(new File(outputPath));
}
}
}

Signature Verification

Validating signatures is crucial to ensure document integrity.

public class PDFSignatureVerifier {
public void verifySignatures(String pdfPath) throws Exception {
try (PDDocument document = PDDocument.load(new File(pdfPath))) {
List<PDSignature> signatures = document.getSignatureDictionaries();
if (signatures.isEmpty()) {
System.out.println("No signatures found in document");
return;
}
for (PDSignature signature : signatures) {
verifySignature(document, signature);
}
}
}
private void verifySignature(PDDocument document, PDSignature signature) throws Exception {
System.out.println("=== Verifying Signature ===");
System.out.println("Name: " + signature.getName());
System.out.println("Reason: " + signature.getReason());
System.out.println("Location: " + signature.getLocation());
System.out.println("Signing Time: " + signature.getSignDate().getTime());
// Verify cryptographic signature
SignatureInterface verifier = new SignatureVerifier();
boolean isValid = document.validateSignature(signature, verifier);
System.out.println("Cryptographic Validation: " + 
(isValid ? "VALID" : "INVALID"));
// Additional certificate validation
Certificate[] certs = signature.getCertificates();
if (certs != null && certs.length > 0) {
X509Certificate signerCert = (X509Certificate) certs[0];
System.out.println("Subject: " + signerCert.getSubjectX500Principal());
System.out.println("Issuer: " + signerCert.getIssuerX500Principal());
System.out.println("Valid From: " + signerCert.getNotBefore());
System.out.println("Valid Until: " + signerCert.getNotAfter());
// Check certificate expiration
boolean isExpired = new Date().after(signerCert.getNotAfter());
System.out.println("Certificate Expired: " + isExpired);
}
}
private static class SignatureVerifier implements SignatureInterface {
@Override
public byte[] sign(InputStream content) {
throw new UnsupportedOperationException("Verifier cannot sign");
}
}
}

Creating Test Certificates

For development and testing, you can generate self-signed certificates:

# Generate private key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
# Create PKCS12 keystore
openssl pkcs12 -export -out keystore.p12 -inkey key.pem -in cert.pem

Best Practices and Security Considerations

  1. Key Security: // Never hardcode passwords public class SecureKeyProvider { public static char[] getKeyPassword() { // Read from secure configuration, HSM, or environment variables return System.getenv("PDF_SIGNING_PASSWORD").toCharArray(); } }
  2. Certificate Validation: public void validateCertificateChain(X509Certificate[] chain) throws Exception { CertificateFactory factory = CertificateFactory.getInstance("X.509"); CertPath certPath = factory.generateCertPath(Arrays.asList(chain));PKIXParameters params = new PKIXParameters(getTrustAnchors()); params.setRevocationEnabled(true); CertPathValidator validator = CertPathValidator.getInstance("PKIX"); validator.validate(certPath, params);}
  3. Signature Appearance:
    java private void configureVisibleSignature(PDVisibleSigProperties props) { props.setPage(1); // Page number (1-based) props.setLlx(50); // Lower-left X props.setLly(50); // Lower-left Y props.setUrx(200); // Upper-right X props.setUry(100); // Upper-right Y props.setSignatureGraphic("signature.png"); // Optional image props.setRenderingMode(PDVisibleSigProperties.RenderingMode.GRAPHIC_AND_DESCRIPTION); }

Common Issues and Solutions

1. Insufficient Signature Space:

// Reserve adequate space for the signature
signatureOptions.setPreferredSignatureSize(15 * 1024); // 15KB

2. Certificate Chain Issues:

// Ensure full certificate chain is included
CertificateFactory factory = CertificateFactory.getInstance("X.509");
List<Certificate> fullChain = new ArrayList<>();
fullChain.add(signerCert);
fullChain.addAll(Arrays.asList(intermediateCerts));

3. Timestamping Failures:

// Implement retry logic for TSA
private TimeStampResponse callTSAServiceWithRetry(TimeStampRequest request, int maxRetries) {
for (int i = 0; i < maxRetries; i++) {
try {
return callTSAService(request);
} catch (Exception e) {
if (i == maxRetries - 1) throw e;
Thread.sleep(1000 * (i + 1)); // Exponential backoff
}
}
return null;
}

Conclusion

Implementing digital signatures in PDFs with Java provides robust document security and legal compliance. Apache PDFBox offers a powerful open-source solution, while commercial libraries like iText provide additional enterprise features.

Key success factors include:

  • Proper handling of cryptographic keys and certificates
  • Adequate signature space reservation
  • Timestamp authority integration for long-term validity
  • Comprehensive verification procedures
  • Secure storage and management of signing credentials

By following the patterns and best practices outlined above, you can build reliable PDF signing functionality that meets enterprise security requirements and complies with electronic signature regulations like eIDAS and ESIGN.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper