public class AcrobatSignatureHandlerFactory extends Object implements SignatureHandlerFactory
An implementation of
SignatureHandlerFactory that returns handlers
suitable for signing documents for use with Acrobat 6.0 or later.
use it's quite acceptable to use the
which is an instance of this factory. If advanced options need to be set
(such as setting a TimeStamp server or changing the hash algorithm) then you
can create an instance of this factory and set the options on that before
passing it in to the
Since 2.15.2 this class's factories can create
This stands for "PDF Advanced Electronic Signatures", and it's defined in both
ETSI TR 102 923 and in PDF 2.0. It's a particular application of CAdES signatures, which are
the modern variation of the standard PKCS#7 signatures used by Acrobat.
For our purposes the terms PAdES and CAdES are interchangeable, and when
verifying a digital signature with the BFO API the two are not distinguished.
When signing, to create a signature marked as PAdES you can call the
setPAdES(boolean) method on this factory:
AcrobatSignatureHandlerFactory factory = new AcrobatSignatureHandlerFactory(); factory.setDigestAlgorithm("SHA-256"); factory.setPAdES(true); ...
To ensure a signature meets the requirements for PAdES part 4 (long-term validation), the following conditions need to be met:
setUseSigningCertificateAttribute(boolean). This is the default.
setPAdES(boolean). Slightly ironically, this is recommended but not required
This last point needs further explaining. For a signature to be considered long-term validated, the entire
signature chain, up to and including any trusted root certificates, must be embedded in the PDF. This
includes the the certificates certifying any OCSP or CRL responses obtained as part of the valdation. The
root certificates may not be included as part of these responses, or it may not be included as an explicit
part of the
certificate-chain for the PrivateKey entry used when signing. However,
so long as all the required root certificates can be found somewhere in the
KeyStore supplied to the
FormSignature.sign() method, then they will be embedded in the signed object. If
they are not available (or if the OCSP or CRL requests fail for any reason), then a "PK3" warning will be
emitted during signing with details of the break in the
certificate chain. The signature will still be valid, but will not be considered "long-term" valid.
Here's an example showing how to apply a PAdES long-term valid signature to a PDF. The KeyStore supplied is assumed to have all the required root-certificates
KeyStore keystore = KeyStore.getInstance("JKS"); keystore.load(new FileInputStream("keystore.jks"), password); PDF pdf = new PDF(new PDFReader(new File("input.pdf"))); FormSignature sig = new FormSignature(); AcrobatSignatureHandlerFactory factory = new AcrobatSignatureHandlerFactory(); factory.setPAdES(true); factory.setValidateCertificatesOnSigning(true); factory.setTimeStampServer(new URL("http://timestamp.entrust.net/TSS/RFC3161sha1TS")); pdf.getForm().getElements().put("sig", sig); sig.sign(keystore, "myalias", password, factory); pdf.render(new FileOutputStream("output.pdf"));
|Constructor and Description|
Create a new SignatureHandlerFactory
|Modifier and Type||Method and Description|
Return the actual object that will do the signing.
Return the Digest Algorithm, as set by
Return a handler created by this factory
Return the TimeStamp Server, as set by
This method can be called to fix the space allocated for the "Contents" variable, which contains the encoded signature.
Set a custom appearance for this signature.
Set the message digest algorithm to use - one of MD5, SHA1, SHA-256, SHA-384, SHA-512 or RIPEMD160 The default since 2.20 is SHA256 - prior to that release it was SHA1.
Set whether the factory should use the PAdES signature idenfifier, as specified in PDF 2.0 and supported in Acrobat X and later.
Specify the URL of an RFC3161 Timestamp Server.
Specifies whether the PKCS#7 object should be generated with the
Specifies whether the certificates used during signing should be verified with their OCSP or CRL responders, if available.
public void setDigestAlgorithm(String algorithm)
algorithm- the message-digest algorithm to use.
public void setTimeStampServer(URL server)
server- The server to contact for the TimeStamp. May be
nullto turn off timestamping (the default). If a username/password are required they may be specified in the URL, eg "http://user:firstname.lastname@example.org".
public URL getTimeStampServer()
public String getDigestAlgorithm()
public void setValidateCertificatesOnSigning(boolean check)
Specifies whether the certificates used during signing should be verified
with their OCSP or CRL responders, if available. The responses are included
in the signature using the
(1.2.840.1135188.8.131.52) attribute, which will certify that the Certificates
used to sign the PDF were valid at the time of signing. This is required
for documents which need to meet the PAdES LTV (Long-Term Validation) specification.
Setting this value to true may result in 1 or more network requests during signing.
public void setUseSigningCertificateAttribute(boolean use)
id-aa-signingCertificateV2(1.2.840.1135184.108.40.206.2) attribute, as defined in RFC5035. This is recommended for all signatures and required for PAdES signatures, and is on by default since 2.15.2
public void setCustomAppearance(PDFCanvas canvas, float x1, float y1, float x2, float y2)
Set a custom appearance for this signature. This method allows you to add a signature, thumbprint, logo or any other form of custom image to your signature annotations (technically, this method sets the "n2" layer of the annotation). The canvas may be of any size, and will be scaled to fit the annotation on the page.
Care needs to be taken when setting this value. It's not recommended to use a canvas containing a bitmap image with an opaque background, as this may mask any layers behind this one. In particular, a "?" is typically used on a layer below this one to indicate the signature has not been verified. Specifying an opaque image may result in this being obscured.
As a optional convenience, by specifying non-zero coordinates for the x1,y1,x2 and y2 values, some text describing the signing certificate will be added to the canvas at the specified location. The format for this is fixed, but as it doesn't have to be included, the developer is free to add his or her own text if they don't like the result, simply by setting all four values to zero.
As an example, the default PKCS7 appearance is set with the following code which loads a pre-defined pattern from a resources file:
setCustomAppearance(new PDFCanvas("logo.Adobe", 1), 0, 35, 100, 65);
canvas- the canvas to display as the "n2" layer of the signature appearance.
x1- the left-most X co-ordinate to place the (optional) certificate text
y1- the bottom-most Y co-ordinate to place the (optional) certificate text
x2- the right-most X co-ordinate to place the (optional) certificate text
y2- the top-most Y co-ordinate to place the (optional) certificate text
public void setContentSize(int size)
This method can be called to fix the space allocated for the "Contents" variable,
which contains the encoded signature. If a value > 0 is supplied then the Contents
variable will have that much space allocated for it. If a value of <= 0 is supplied
SignatureHandler.getEstimatedContentSize(int) method will be called with the negative
of this value (so if you call
setContentSize(-100), this will result in
a call of
The intention of this is to allocate space in the Contents variable for external objects,
such as TimeStamps from a remote server. For instance, if you were using a
PKCS7SignatureHandler to digitally sign and an RFC3161 TimeStamp server was
specified, you could pass in
a value of "-1000" to this method to reserve 1000 bytes in the PKCS#7 object for the
size- the size of the Contents string in bytes, or <= 0 to determine automatically.
public void setPAdES(boolean pades)
pades- if true, use the PAdES standard, otherwise create regular Acrobat signatures.
public void setProvider(Provider provider)
Providerto be used for any signature operations created by this factory. If set the Provider will be asked first for any resource, but if it is unable to provide one the default provider will be used as a fallback. This will override the Provider of the
KeyStorepassed in to
FormSignature.sign(), which can also be used to set the Provider.
public PKCS7SignatureHandler.SigningEngine createSigningEngine(KeyStore keystore, String alias, char password, String subfilter) throws GeneralSecurityException
keystore- the KeyStore supplied to the sign method
alias- the alias supplied to the sign method
password- the password supplied to the sign method
subfilter- the subfilter
Copyright © 2001-2019 Big Faceless Organization