Signing PDFs with iText

<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itext-core</artifactId>
    <version>9.8.0</version>
    <type>pom</type>
</dependency>
<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>bouncy-castle-adapter</artifactId>
    <version>9.8.0</version>
</dependency>

# 0. Store password for both keystores, taken from the terminal and exported for keytool.
read -rs BILLING_KEYSTORE_PASSWORD && export BILLING_KEYSTORE_PASSWORD

# 1. Self-signed root CA (basicConstraints CA:true, may sign certificates and CRLs).
keytool -genkeypair -alias billing-test-ca -keyalg RSA -keysize 3072 -sigalg SHA256withRSA \
  -validity 3650 -dname "CN=Bookshelf Billing Test Root CA, O=Bookshelf Test, C=ES" \
  -ext bc:c=ca:true -ext ku:c=keyCertSign,cRLSign \
  -keystore billing-test-ca.p12 -storetype PKCS12 \
  -storepass:env BILLING_KEYSTORE_PASSWORD -keypass:env BILLING_KEYSTORE_PASSWORD

# 2. The signer's own key pair (with a temporary self-signed certificate that step 5 replaces).
keytool -genkeypair -alias billing-signer -keyalg RSA -keysize 3072 -sigalg SHA256withRSA \
  -validity 825 -dname "CN=Bookshelf Billing Test Signer, O=Bookshelf Test, C=ES" \
  -keystore billing-signer.p12 -storetype PKCS12 \
  -storepass:env BILLING_KEYSTORE_PASSWORD -keypass:env BILLING_KEYSTORE_PASSWORD

# 3. A certificate signing request for the signer.
keytool -certreq -alias billing-signer -sigalg SHA256withRSA \
  -keystore billing-signer.p12 -storepass:env BILLING_KEYSTORE_PASSWORD \
  -file billing-signer.csr

# 4. The CA issues the signer certificate: an end-entity certificate for document signing.
keytool -gencert -alias billing-test-ca -sigalg SHA256withRSA -validity 825 -rfc \
  -ext bc:c=ca:false -ext ku:c=digitalSignature,nonRepudiation -ext eku=emailProtection \
  -keystore billing-test-ca.p12 -storepass:env BILLING_KEYSTORE_PASSWORD \
  -infile billing-signer.csr -outfile billing-signer.pem

# 5. Export the CA certificate (the trust anchor), then import it and the issued certificate
#    into the signer keystore; the second import replaces the temporary certificate and stores
#    the full chain [signer, CA] under the alias billing-signer.
keytool -exportcert -rfc -alias billing-test-ca \
  -keystore billing-test-ca.p12 -storepass:env BILLING_KEYSTORE_PASSWORD \
  -file billing-test-ca.pem
keytool -importcert -noprompt -alias billing-test-ca -file billing-test-ca.pem \
  -keystore billing-signer.p12 -storepass:env BILLING_KEYSTORE_PASSWORD
keytool -importcert -noprompt -alias billing-signer -file billing-signer.pem \
  -keystore billing-signer.p12 -storepass:env BILLING_KEYSTORE_PASSWORD

# 6. Check: the signer entry must report a chain of length 2, issued by the test CA.
keytool -J-Duser.language=en -list -v -alias billing-signer -keystore billing-signer.p12 \
  -storepass:env BILLING_KEYSTORE_PASSWORD | grep -E "Certificate chain length|Owner|Issuer"

package com.example.billing;

import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.GeneralSecurityException;
import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.cert.Certificate;

/** Private key and certificate chain of the billing signer, read from a PKCS#12 keystore. */
public record BillingCredentials(PrivateKey privateKey, Certificate[] chain) {

    public static BillingCredentials load(Path keystore, String alias) throws IOException, GeneralSecurityException {
        String storePassword = System.getenv("BILLING_KEYSTORE_PASSWORD");
        if (storePassword == null || storePassword.isBlank()) {
            throw new IllegalStateException("Environment variable BILLING_KEYSTORE_PASSWORD is not set");
        }
        char[] password = storePassword.toCharArray();
        KeyStore store = KeyStore.getInstance("PKCS12");
        try (InputStream in = Files.newInputStream(keystore)) {
            store.load(in, password);
        }
        PrivateKey privateKey = (PrivateKey) store.getKey(alias, password);
        Certificate[] chain = store.getCertificateChain(alias);
        if (privateKey == null || chain == null) {
            throw new IllegalStateException("No private key and chain under alias " + alias);
        }
        return new BillingCredentials(privateKey, chain);
    }
}

package com.example.billing;

import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.layout.Document;
import com.itextpdf.layout.element.Paragraph;

import java.io.ByteArrayOutputStream;

public final class InvoiceFactory {

    private InvoiceFactory() {
    }

    /** Builds the unsigned invoice. Signing never happens while the document is being written. */
    public static byte[] unsignedInvoice(String number) {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        try (PdfDocument pdf = new PdfDocument(new PdfWriter(out));
             Document document = new Document(pdf)) {
            document.add(new Paragraph("Bookshelf Billing - invoice " + number));
            document.add(new Paragraph("Total: 42.50 EUR"));
        }
        return out.toByteArray();
    }
}

package com.example.billing;

import com.itextpdf.kernel.pdf.PdfReader;
import com.itextpdf.signatures.CrlClientOnline;
import com.itextpdf.signatures.ICrlClient;
import com.itextpdf.signatures.IExternalSignature;
import com.itextpdf.signatures.ITSAClient;
import com.itextpdf.signatures.OcspClientBouncyCastle;
import com.itextpdf.signatures.PdfPadesSigner;
import com.itextpdf.signatures.PrivateKeySignature;
import com.itextpdf.signatures.SignerProperties;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.security.Security;
import java.util.Calendar;

public class PadesBaselineSigner {

    static {
        Security.addProvider(new BouncyCastleProvider());
    }

    private final BillingCredentials credentials;
    private final ICrlClient crlClient;

    public PadesBaselineSigner(BillingCredentials credentials) {
        this(credentials, new CrlClientOnline());
    }

    public PadesBaselineSigner(BillingCredentials credentials, ICrlClient crlClient) {
        this.credentials = credentials;
        this.crlClient = crlClient;
    }

    private SignerProperties properties(String fieldName) {
        return new SignerProperties()
                .setFieldName(fieldName)
                .setReason("Invoice issued by Bookshelf Billing")
                .setLocation("Madrid")
                .setClaimedSignDate(Calendar.getInstance());
    }

    private IExternalSignature signature() {
        return new PrivateKeySignature(credentials.privateKey(), "SHA256", BouncyCastleProvider.PROVIDER_NAME);
    }

    /** B-B: signing certificate and chain, no timestamp. */
    public byte[] signBaselineB(byte[] pdf) throws IOException, GeneralSecurityException {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        PdfPadesSigner signer = new PdfPadesSigner(new PdfReader(new ByteArrayInputStream(pdf)), out);
        signer.signWithBaselineBProfile(properties("billing-signature"), credentials.chain(), signature());
        return out.toByteArray();
    }

    /** B-T: adds an RFC 3161 signature timestamp. Needs network access to the TSA. */
    public byte[] signBaselineT(byte[] pdf, ITSAClient tsa) throws IOException, GeneralSecurityException {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        PdfPadesSigner signer = new PdfPadesSigner(new PdfReader(new ByteArrayInputStream(pdf)), out);
        signer.signWithBaselineTProfile(properties("billing-signature"), credentials.chain(), signature(), tsa);
        return out.toByteArray();
    }

    /** B-LT: B-T plus validation data (certificates, OCSP, CRL) in the DSS dictionary. */
    public byte[] signBaselineLT(byte[] pdf, ITSAClient tsa) throws IOException, GeneralSecurityException {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        PdfPadesSigner signer = new PdfPadesSigner(new PdfReader(new ByteArrayInputStream(pdf)), out)
                .setOcspClient(new OcspClientBouncyCastle())
                .setCrlClient(crlClient);
        signer.signWithBaselineLTProfile(properties("billing-signature"), credentials.chain(), signature(), tsa);
        return out.toByteArray();
    }

    /** B-LTA: B-LT plus an archive document timestamp. */
    public byte[] signBaselineLTA(byte[] pdf, ITSAClient tsa) throws IOException, GeneralSecurityException {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        PdfPadesSigner signer = new PdfPadesSigner(new PdfReader(new ByteArrayInputStream(pdf)), out)
                .setOcspClient(new OcspClientBouncyCastle())
                .setCrlClient(crlClient)
                .setTimestampSignatureName("billing-archive-timestamp");
        signer.signWithBaselineLTAProfile(properties("billing-signature"), credentials.chain(), signature(), tsa);
        return out.toByteArray();
    }

    /** Adds a fresh document timestamp (and refreshed validation data) to a B-LTA file. */
    public byte[] prolong(byte[] signedPdf, ITSAClient tsa) throws IOException, GeneralSecurityException {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        PdfPadesSigner signer = new PdfPadesSigner(new PdfReader(new ByteArrayInputStream(signedPdf)), out)
                .setOcspClient(new OcspClientBouncyCastle())
                .setCrlClient(crlClient)
                .setTimestampSignatureName("billing-archive-timestamp-2");
        signer.prolongSignatures(tsa);
        return out.toByteArray();
    }
}

package com.example.billing;

import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfName;
import com.itextpdf.kernel.pdf.PdfReader;
import com.itextpdf.signatures.PdfPKCS7;
import com.itextpdf.signatures.SignatureUtil;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

import java.io.IOException;
import java.nio.file.Path;
import java.security.GeneralSecurityException;
import java.security.Security;

/** Prints what each signature of a file claims. It does not validate trust, revocation or policy. */
public class SignatureInspector {

    static {
        Security.addProvider(new BouncyCastleProvider());
    }

    public static void main(String[] args) throws IOException, GeneralSecurityException {
        try (PdfDocument pdf = new PdfDocument(new PdfReader(Path.of(args[0]).toString()))) {
            SignatureUtil util = new SignatureUtil(pdf);
            boolean hasDss = pdf.getCatalog().getPdfObject().containsKey(PdfName.DSS);
            System.out.println("DSS dictionary present: " + hasDss);
            for (String name : util.getSignatureNames()) {
                PdfPKCS7 pkcs7 = util.readSignatureData(name);
                System.out.printf("%s | subFilter=%s | revision %d of %d | whole document=%b | integrity=%b%n",
                        name,
                        util.getSignature(name).getSubFilter(),
                        util.getRevision(name), util.getTotalRevisions(),
                        util.signatureCoversWholeDocument(name),
                        pkcs7.verifySignatureIntegrityAndAuthenticity());
                if (pkcs7.isTsp()) {
                    System.out.println("   document timestamp at " + pkcs7.getTimeStampDate().getTime());
                } else {
                    System.out.println("   signer " + pkcs7.getSigningCertificate().getSubjectX500Principal()
                            + ", digest " + pkcs7.getDigestAlgorithmName()
                            + ", signature timestamp " + (pkcs7.getTimeStampDate() != null
                            ? pkcs7.getTimeStampDate().getTime() : "none"));
                }
            }
        }
    }
}

package com.example.billing;

import com.itextpdf.signatures.IExternalSignature;
import com.itextpdf.signatures.ISignatureMechanismParams;

import java.security.GeneralSecurityException;
import java.security.PrivateKey;
import java.security.Signature;

/**
 * An IExternalSignature that delegates to any JCA Signature. The private key may live in a PKCS#11 token
 * or a key management service behind a JCA provider; iText only ever sees the bytes to sign.
 */
public class JcaExternalSignature implements IExternalSignature {

    private final PrivateKey privateKey;
    private final String provider;

    public JcaExternalSignature(PrivateKey privateKey, String provider) {
        this.privateKey = privateKey;
        this.provider = provider;
    }

    @Override
    public String getDigestAlgorithmName() {
        return "SHA256";
    }

    @Override
    public String getSignatureAlgorithmName() {
        return "RSA";
    }

    @Override
    public ISignatureMechanismParams getSignatureMechanismParameters() {
        return null;
    }

    @Override
    public byte[] sign(byte[] message) throws GeneralSecurityException {
        Signature signature = provider == null
                ? Signature.getInstance("SHA256withRSA")
                : Signature.getInstance("SHA256withRSA", provider);
        signature.initSign(privateKey);
        signature.update(message);
        return signature.sign();
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<jasperReport name="billing-invoice" language="java" pageWidth="595" pageHeight="842"
              columnWidth="555" leftMargin="20" rightMargin="20" topMargin="20" bottomMargin="20">
    <parameter name="number" class="java.lang.String"/>
    <title height="60">
        <element kind="staticText" x="0" y="0" width="555" height="30" fontSize="18.0">
            <text><![CDATA[Bookshelf Billing invoice]]></text>
        </element>
        <element kind="textField" x="0" y="30" width="555" height="20">
            <expression><![CDATA["Number: " + $P{number}]]></expression>
        </element>
    </title>
</jasperReport>

package com.example.billing;

import com.itextpdf.kernel.pdf.PdfReader;
import com.itextpdf.signatures.PdfPadesSigner;
import com.itextpdf.signatures.PrivateKeySignature;
import com.itextpdf.signatures.SignerProperties;
import net.sf.jasperreports.engine.JRException;
import net.sf.jasperreports.engine.JasperCompileManager;
import net.sf.jasperreports.engine.JasperExportManager;
import net.sf.jasperreports.engine.JasperFillManager;
import net.sf.jasperreports.engine.JasperPrint;
import net.sf.jasperreports.engine.JasperReport;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.GeneralSecurityException;
import java.security.Security;
import java.util.HashMap;
import java.util.Map;

/** JasperReports renders the invoice; iText signs the exported bytes. The two libraries never share objects. */
public class JasperInvoiceSigner {

    static {
        Security.addProvider(new BouncyCastleProvider());
    }

    private final JasperReport report;
    private final BillingCredentials credentials;

    public JasperInvoiceSigner(BillingCredentials credentials) throws IOException, JRException {
        this.credentials = credentials;
        try (InputStream template = getClass().getResourceAsStream("/reports/billing-invoice.jrxml")) {
            this.report = JasperCompileManager.compileReport(template);
        }
    }

    public byte[] renderAndSign(String number) throws JRException, IOException, GeneralSecurityException {
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("number", number);
        JasperPrint print = JasperFillManager.fillReport(report, parameters);
        byte[] unsigned = JasperExportManager.exportReportToPdf(print);

        ByteArrayOutputStream signed = new ByteArrayOutputStream();
        new PdfPadesSigner(new PdfReader(new ByteArrayInputStream(unsigned)), signed)
                .signWithBaselineBProfile(
                        new SignerProperties().setFieldName("billing-signature"),
                        credentials.chain(),
                        new PrivateKeySignature(credentials.privateKey(), "SHA256", BouncyCastleProvider.PROVIDER_NAME));
        return signed.toByteArray();
    }
}