public abstract class PKCS7SignatureHandler extends SignatureHandler
This class represents the subclass of digital signatures that rely on Public/Private key pairs and that meet the requirements laid down in the document "PDF Public-Key Digital Signature and Encryption Specification", published by Adobe. As of 2016 almost all security handlers used by Acrobat will be an instance of this class: it works with signatures created by the Adobe.PPKMS and Adobe.PPKLite engines in Acrobat, as well as Document level timestamps introduced in PDF 2.0, and many older, legacy public-key based signature handlers as well.
Instances of this class are created by both the AcrobatSignatureHandlerFactory
and TimeStampHandlerFactory
.
AcrobatSignatureHandlerFactory
Modifier and Type | Class and Description |
---|---|
static class |
PKCS7SignatureHandler.OCSPResponse
An OCSP response relating to the validity of a digital signature.
|
class |
PKCS7SignatureHandler.ValidationInformation
This class represents long-term validation information, as described in
PAdES part 4.
|
SignatureHandler.Placeholder
Modifier | Constructor and Description |
---|---|
protected |
PKCS7SignatureHandler() |
Modifier and Type | Method and Description |
---|---|
boolean |
addValidationInformation(KeyStore keystore)
Add Long Term Validation information for this signature to the PDF.
|
X509Certificate[] |
getCertificates()
Return the list of certificates included in this signature.
|
String |
getDefaultName()
Returns an optional default value that can be used to initialize
FormSignature.setName(java.lang.String) , or null if no such name
is available. |
int |
getEstimatedContentSize(int additional)
Return the estimated size of the signature object to be embedded, or <= 0
if this cannot be determined.
|
String |
getFilter()
Return the name of the filter, eg "Adobe.PPKLite".
|
String |
getHandlerName()
The handler name for a
Document TimeStamp is "ETSI.RFC3161",
otherwise it is "PKCS7" |
String |
getHashAlgorithm()
Return the Hash algorithm used by the PKCS#7 object when signing.
|
PDFCanvas |
getLayerAppearance(String layername,
PDFStyle textstyle)
Return a
PDFCanvas for the specified layer. |
String[] |
getLayerNames()
Return the list of appearance layer names used by this Signature Handler to
create a visible appearance on the page, in the order they should be drawn.
|
MessageDigest |
getMessageDigest()
Return a MessageDigest that will be used to calculate the digest of the PDF
for signing.
|
Provider |
getProvider()
Return the
Provider to be used by all operations in this
class, or null to use the default. |
abstract String |
getSubFilter()
Return the SubFilter field, which determines how the PKCS#7 object
is encoded.
|
X509Certificate[] |
getTimeStampCertificates()
If the PKCS#7 object was digitally time-stamped using an RFC3161 time-stamp
server, this method verifies and returns the list of X.509 certificates that
verify the timestamp, with the actual signing certificate first and the rest
in no particular order.
|
List<PKCS7SignatureHandler.ValidationInformation> |
getValidationInformation()
Returns the long-term validation details for the signature that are embedded in the PDF.
|
protected void |
prepareToSign(KeyStore keystore,
String alias,
char[] password)
This method initialized the handler using the specified values into a state where
it's ready to sign.
|
void |
setCustomAppearance(PDFCanvas canvas,
float x1,
float y1,
float x2,
float y2)
Set a custom appearance for this signature.
|
byte[] |
sign()
Finish the digest calculation on the digest returned from
SignatureHandler.getMessageDigest()
and return a signature token the signs it. |
boolean |
verify(InputStream in)
Return a boolean indicating whether or not the signature handler
can verify the specified
InputStream . |
containsKey, getArrayValueSize, getBooleanValue, getCertificationType, getDictionaryValueKeys, getFormSignature, getNameValue, getNumericValue, getStreamValue, getStringValue, getTextStringValue, getVariables, postDigest, preDigest, putArrayValue, putBooleanValue, putDictionaryValue, putNameValue, putNumericValue, putStreamValue, putStringValue, putTextStringValue
public String getHashAlgorithm()
public String getFilter()
SignatureHandler
getFilter
in class SignatureHandler
public abstract String getSubFilter()
public String getHandlerName()
Document TimeStamp
is "ETSI.RFC3161",
otherwise it is "PKCS7"getHandlerName
in class SignatureHandler
public Provider getProvider()
Provider
to be used by all operations in this
class, or null to use the default. Note that default will always
be used as a fallback if the selected provider is unable to provide
a resource (such as a digest algorithm). The default is null
AcrobatSignatureHandlerFactory.setProvider(java.security.Provider)
protected void prepareToSign(KeyStore keystore, String alias, char[] password) throws GeneralSecurityException
SignatureHandler
This method initialized the handler using the specified values into a state where it's ready to sign. This method should be used to set any additional fields in the Signature dictionary, for example "Certs" for the Self-Sign handler.
Those overriding this method must call super.prepareToSign()
before doing anything else.
prepareToSign
in class SignatureHandler
keystore
- the KeyStorealias
- which key to usepassword
- the password to use to decode the keyGeneralSecurityException
public int getEstimatedContentSize(int additional)
SignatureHandler
getEstimatedContentSize
in class SignatureHandler
additional
- the negation of any value previously passed into SignatureHandler.setContentSize(int)
public MessageDigest getMessageDigest()
SignatureHandler
SignatureHandler.sign()
- see the API docs
for that method for more details.getMessageDigest
in class SignatureHandler
public byte[] sign() throws GeneralSecurityException, IOException
SignatureHandler
Finish the digest calculation on the digest returned from SignatureHandler.getMessageDigest()
and return a signature token the signs it. The returned byte array will be stored
as the "Contents" value of the Signature dictionary.
As well as being called to perform the actual signing, the default behaviour of the
SignatureHandler.getVariables()
method is also to call this method with an empty digest, to
determine the size of the token to store in the PDF (the SignatureHandler.getMessageDigest()
method is called twice as well). This can be overridden, by calling
AcrobatSignatureHandlerFactory.setContentSize(int)
for handlers created by that
factory or, if you're implementing a custom signature handler, by writing your own
SignatureHandler.getVariables()
method.
sign
in class SignatureHandler
GeneralSecurityException
- if the signature cannot be applied for some cryptographic reasonIOException
- if the InputStream cannot be readpublic final boolean verify(InputStream in) throws GeneralSecurityException, IOException
SignatureHandler
InputStream
.verify
in class SignatureHandler
GeneralSecurityException
- if the signature cannot be verified for some cryptographic reasonIOException
- if the InputStream cannot be readpublic X509Certificate[] getCertificates() throws CertificateException
CertificateException
public String[] getLayerNames()
SignatureHandler
Return the list of appearance layer names used by this Signature Handler to
create a visible appearance on the page, in the order they should be drawn.
This method is called internally by the FormSignature
class
when drawing the signature annotations on the page.
For more information see the document "Digital Signature Appearances for Public-Key Interoperability", from Adobes website.
As an example, both the Verisign and the SelfSign handlers return the array
[ "n0", "n1", "n2", "n3" ]
.
getLayerNames
in class SignatureHandler
SignatureHandler.getLayerAppearance(java.lang.String, org.faceless.pdf2.PDFStyle)
public PDFCanvas getLayerAppearance(String layername, PDFStyle textstyle)
SignatureHandler
PDFCanvas
for the specified layer.
This method is called internally by the FormSignature
class
when drawing the signature annotations on the page.
For more information see the document "Digital Signature Appearances for Public-Key Interoperability", from Adobes website.getLayerAppearance
in class SignatureHandler
layername
- the layer to create (from the list returned by SignatureHandler.getLayerNames()
)textstyle
- the style in which to draw the text, if anyPDFCanvas
of any size containing the specified layer.SignatureHandler.getLayerNames()
public void setCustomAppearance(PDFCanvas canvas, float x1, float y1, float x2, float y2)
Set a custom appearance for this signature. See the AcrobatSignatureHandlerFactory.setCustomAppearance(org.faceless.pdf2.PDFCanvas, float, float, float, float)
method for more details -
unless you're manually overriding this class, that's the method you
should be calling.
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 texty1
- the bottom-most Y co-ordinate to place the (optional) certificate textx2
- the right-most X co-ordinate to place the (optional) certificate texty2
- the top-most Y co-ordinate to place the (optional) certificate textpublic X509Certificate[] getTimeStampCertificates() throws GeneralSecurityException, IOException
If the PKCS#7 object was digitally time-stamped using an RFC3161 time-stamp
server, this method verifies and returns the list of X.509 certificates that
verify the timestamp, with the actual signing certificate first and the rest
in no particular order. If this method succeeds, then the date returned by
FormSignature.getSignDate()
is the date guaranteed by the time-stamp.
If the signature was time-stamped but the timestamp is corrupt or invalid,
thie method will throw either a GeneralSecurityException
or a
IOException
detailing why.
If the signature was not timestamped, this method returns null
.
If the signature is, in itself, an RFC 3161 document-level TimeStamp as
would be created by TimeStampHandlerFactory
, then this method
return the same list as getCertificates()
X509Certificate
objects that authorized the timestamp, or null
if there isn't a timestamp.GeneralSecurityException
- if the TimeStamp is invalidIOException
- if the TimeStamp is corrupt or can't be parsedpublic String getDefaultName()
SignatureHandler
FormSignature.setName(java.lang.String)
, or null
if no such name
is available.getDefaultName
in class SignatureHandler
public boolean addValidationInformation(KeyStore keystore) throws GeneralSecurityException, IOException
Add Long Term Validation information for this signature to the PDF.
This will perform an OCSP check on the signature, and add the response
to the PDF (and, therefore, to the list of responses included in
getValidationInformation()
). It may be called on any previously signed
PKCS#7 signature, including document-level Timestamps. Validation information
will be ignored in Acrobat prior to Acrobat XI.
For validation information to be considered complete
,
the entire certificate chain, including any trusted roots, must be embedded in the PDF.
The trusted root certificates are often not included with the original signature, so if
a KeyStore is supplied it will be searched for any missing root certificates
to be embedded in the PDF. A suitable KeyStore for this purpose is the one returned by
FormSignature.loadDefaultKeyStore()
.
The signature must be signed
and
verified
, otherwise an IllegalStateException
will be thrown.
Here's an example showing how to add validation information to all the signatures in a PDF.
PDF pdf = new PDF(new PDFReader(new File("input.pdf"))); KeyStore rootkeystore = FormSignature.loadDefaultKeyStore(); for (FormElement elt : pdf.getForm().getElements().values()) { if (elt instanceof FormSignature) { FormSignature sig = (FormSignature)elt; if (sig.getHandler() instanceof PKCS7SignatureHandler) { PKCS7SignatureHandler handler = (PKCS7SignatureHandler)sig.getSignatureHandler(); handler.addValidationInformation(rootkeystore); } } } pdf.render(new FileOutputStream("output.pdf"));
keystore
- the KeyStore to query for any additional root certificates, or null to not perform this step.GeneralSecurityException
IOException
getValidationInformation()
,
TimeStampHandlerFactory
,
AcrobatSignatureHandlerFactory
public List<PKCS7SignatureHandler.ValidationInformation> getValidationInformation() throws GeneralSecurityException, IOException
addValidationInformation(java.security.KeyStore)
method). If LTV information is available from either of these
stores, then this method returns a List of one or more PKCS7SignatureHandler.ValidationInformation
objects with the details.
If no long-term details are included, this method returns null
.IllegalStateException
- if the associated signature is not FormSignature.STATE_SIGNED
GeneralSecurityException
- if a signature or certificate exception is encountered while extracting
this informationIOException
- if the object embedded in the PDF that contain this data are malformed and can't be parsed.Copyright © 2001-2017 Big Faceless Organization