Complete tutorial: sign a PDF using P12 or PFX
Verified scope: this tutorial is based on file-based
.p12/.pfxcertificates. USB tokens, smartcards and PKCS#11 hardware signing have not been tested and are not advertised as supported. Legal trust requires separate validation.
B4JPdf Pro integrates CMS/PKCS#7 PDF digital signatures with PDFBox 3.0.8 and Bouncy Castle 1.85. A signing certificate must be a PKCS#12 file (.p12 or .pfx) containing the private key and password.
1. Prepare the files
Provide:
contract.pdf: the input document.my-certificate.p12ormy-certificate.pfx: the signing credential.- Optional
stamp.png: an image displayed in a visible signature.
Do not ship real P12/PFX files, private keys or passwords in source code, repositories, or demo packages. Read the password from a protected UI field; never hard-code it.
Use a different output filename, such as contract-signed.pdf, to preserve the original.
2. Complete reusable B4J signing procedure
The procedure takes the input paths and a password supplied by the host application, checks files and certificate, signs visibly or invisibly, then inspects the output. Names and argument order match the v1.0 PDFBoxTools public API.
' Call after collecting the password from a secure UI field.
' CertFile can be .p12 or .pfx. StampFile="" means invisible signing.
Sub SignContract(WorkingDir As String, InputFile As String, OutputFile As String, _
CertDir As String, CertFile As String, Password As String, _
StampDir As String, StampFile As String) As Boolean
If File.Exists(WorkingDir, InputFile) = False Then
Log("Input PDF not found.")
Return False
End If
If File.Exists(CertDir, CertFile) = False Then
Log("PKCS#12 file not found.")
Return False
End If
If InputFile = OutputFile Then
Log("Choose a different output filename.")
Return False
End If
Dim tools As PDFBoxTools
tools.Initialize
' Step 1: inspect the certificate.
Dim cert As CertValidationResult = tools.ValidateCertFile( _
File.Combine(CertDir, CertFile), Password)
If cert.IsValid = False Then
Log("Certificate cannot be used: " & cert.ErrorMessage)
Return False
End If
' Step 2: visible or invisible signature.
Dim signed As Boolean
If StampFile = "" Then
signed = tools.SignPDF(WorkingDir, InputFile, WorkingDir, OutputFile, _
CertDir, CertFile, Password, "Document approval", _
"Office", DateTime.Now)
Else
If File.Exists(StampDir, StampFile) = False Then
Log("Visible signature image is missing.")
Return False
End If
tools.setShowName(True)
tools.setShowReason(True)
tools.setShowLocation(True)
tools.setShowDate(True)
tools.setImageOnly(False)
' Page 0 = first page. Coordinates are PDF points.
' Origin: bottom-left corner.
signed = tools.SignPDFVisible( _
WorkingDir, InputFile, WorkingDir, OutputFile, _
CertDir, CertFile, Password, "Document approval", "Office", _
DateTime.Now, StampDir, StampFile, 0, 80, 80, 200, 85)
End If
If signed = False Then
Log("Digital signing failed.")
Return False
End If
If File.Exists(WorkingDir, OutputFile) = False Then
Log("Signed output was not created.")
Return False
End If
' Step 3: inspect signatures in the generated PDF.
Dim signatures As List = tools.ValidatePDFSignatures( _
File.Combine(WorkingDir, OutputFile))
If signatures.Size = 0 Then
Log("No verifiable signatures were returned.")
Return False
End If
For Each item As PDFSignatureResult In signatures
Log("Signer: " & item.SignerName)
Log("Cryptographic result: " & item.IsValid)
If item.ErrorMessage <> "" Then Log(item.ErrorMessage)
Next
' This does not certify legal trust in a CA.
Return True
End Sub
Call from your B4J form
' passwordFromUI is collected from the application's protected field.
Dim ok As Boolean = SignContract( _
File.DirApp, "contract.pdf", "contract-signed.pdf", _
File.DirApp, "my-certificate.p12", passwordFromUI, _
File.DirApp, "stamp.png")
Log("Signing process completed: " & ok)
For an invisible signature, pass "" as StampFile.
3. Relevant methods
| Method | Purpose |
|---|---|
ValidateCertFile(P12Path, Password) |
Inspect a PKCS#12 certificate |
GetSignerName(KeystorePath, Password) |
Read the signer name when available |
SignPDF(...) |
Create an invisible digital signature |
SignPDFVisible(...) |
Add the signature and a visual image/text appearance |
ValidatePDFSignatures(PDFPath) |
Inspect PDF signature records |
Visible signature coordinates use PDF points (72 points per inch) from the bottom-left corner, and the page index starts at 0.
4. Cryptographic validity is not legal trust
PDFSignatureResult.IsValid reflects the result available from the built-in verifier. It is not, on its own, evidence of CA-chain trust, OCSP/CRL status, signing policy compliance or legal validity.
An expired or revoked certificate may require additional checks. Do not interpret IsValid=True as a complete legal certificate-verification result.
Use cases: signed invoices, administrative records, staff approval flows and controlled batch signing.
Next: Viewer · API reference.