public abstract class SignatureHandler extends Object
This class is the baseline handler for all digital signatures - it could
theoretically be used for any type of signature, using biometrics, public/private
key and so on. The main implementation is the one returned by
AcrobatSignatureHandlerFactory
. Typically an object of this type will be a
PKCS7SignatureHandler
.
For 99% of users, it is enough to look at the examples in the FormSignature
API
documentation, which details how to sign and verify documents using the standard
handlers. For those wanting to write their own signature handlers however, read on.
The SignatureHandler class has several methods which need to be implemented by concrete
implementations of this class. They are at a minimum getFilter()
, the verify()
method (if the handler is to be used to verify signatures), and/or the
prepareToSign()
, getMessageDigest()
and sign()
methods
if the handler is to be used to sign signatures.
In addition, when signing if the signature is to have a visible appearance on the page,
something useful should be returned from getLayerNames()
and
getLayerAppearance()
.
The idea behind the handler is that when signing, first any annotations associated with the
signature are created and filled using the values returned from the
getLayerAppearance()
method. Then the prepareToSign()
method is
called, which should set all the values in the "V" dictionary and generally do everything
required to set up the signature in preparation for signing. Finally the sign()
method
is called, it's return value is stored in the "Contents" field.
The SignatureHandler works in a similar way to the EncryptionHandler
class. There
are a number of get...Value
and put...Value
methods which can
be used to get/set values in the "V" dictionary of the Signature dictionary. See the
discussion in the EncryptionHandler
class documentation for details on how these
methods work. As an example, the SelfSign handler includes the following lines in it's
prepareToSign()
method:
putNameValue("Filter", "Adobe.PPKLite"); putNameValue("SubFilter", "adbe.x509.rsa_sha1"); putNumericValue("R", 65539); putStringValue("Cert", certificatebytearray);
As a slightly more complicated example, to add
/MyArray [ 100 << /Type /MyHandler >> ]
to the "V" dictionary, just do:
putArrayValue("MyArray"); putNumericValue("MyArray.0", 100); putDictionaryValue("MyArray.1"); putNameValue("MyArray.1.Type", "MyHandler");
The getFilter()
method should return an appropriate value - so again, the SelfSign
handler will return the string "Adobe.PPKLite".
For a concrete example of a working, if somewhat brain-dead signature handler, see the
DummySignatureHandler.java
example, supplied with the download package.
FormSignature
,
SignatureHandlerFactory
Modifier and Type | Class and Description |
---|---|
static class |
SignatureHandler.Placeholder
A Placeholder can be used to mark a point in the PDF which
needs to be updated after the signature has been applied
|
Constructor and Description |
---|
SignatureHandler() |
Modifier and Type | Method and Description |
---|---|
protected boolean |
containsKey(String key)
Return true if the
V dictionary contains the specified key |
protected int |
getArrayValueSize(String key)
Return the size of the specified Array from the
V dictionary,
or -1 if no such field exists |
protected boolean |
getBooleanValue(String key)
Return a Boolean from the
V dictionary as a boolean
or false if no such field exists |
int |
getCertificationType()
Return the type of "Certification" the previously-signed signature
this handler is attached to (see
getFormSignature() attests to. |
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. |
protected Set<String> |
getDictionaryValueKeys(String key)
Return the Set of keys of the specified Dictionary from the
V dictionary,
or null if no such field exists. |
int |
getEstimatedContentSize(int contentsize)
Return the estimated size of the signature object to be embedded, or <= 0
if this cannot be determined.
|
abstract String |
getFilter()
Return the name of the filter, eg "Adobe.PPKLite".
|
FormSignature |
getFormSignature()
Get the
FormSignature this handler is attaached to |
String |
getHandlerName()
Return the human-readable name of this handler
|
abstract PDFCanvas |
getLayerAppearance(String layername,
PDFStyle style)
Return a
PDFCanvas for the specified layer. |
abstract 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.
|
protected abstract MessageDigest |
getMessageDigest()
Return a MessageDigest that will be used to calculate the digest of the PDF
for signing.
|
protected String |
getNameValue(String key)
Return a Name from the
V dictionary as a String
or null if no such field exists |
protected float |
getNumericValue(String key)
Return a Number from the
V dictionary as a float
or Float.NaN if no such field exists |
protected InputStream |
getStreamValue(String key)
Return the contents of a Stream from the
V dictionary,
or false if no such field exists |
protected byte[] |
getStringValue(String key)
Return a String from the
V dictionary as a byte array
or null if no such field exists |
protected String |
getTextStringValue(String key)
Return a Text String from the
V dictionary as a String
or null if no such field exists |
Map<String,SignatureHandler.Placeholder> |
getVariables()
Return the list of "variables" which will be set by the handler after the
PDF is rendered.
|
protected void |
postDigest(long filelength,
Map<String,SignatureHandler.Placeholder> variables)
Update any Variables that need to be updated after the Digest
is calculated (eg Contents).
|
protected void |
preDigest(long filelength,
Map<String,SignatureHandler.Placeholder> variables)
Update any Variables that need to be updated before the Digest
is calculated (eg ByteRange).
|
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.
|
protected void |
putArrayValue(String key)
Add (or replace) an Array to the
V dictionary. |
protected void |
putBooleanValue(String key,
boolean val)
Add (or replace) a Boolean to the
V dictionary. |
protected void |
putDictionaryValue(String key)
Add (or replace) a Dictionary to the
V dictionary. |
protected void |
putNameValue(String key,
String val)
Add (or replace) a Name to the
V dictionary. |
protected void |
putNumericValue(String key,
float val)
Add (or replace) a Number to the
V dictionary. |
protected void |
putStreamValue(String key,
byte[] val)
Add (or replace) the contents of a Stream in the
V dictionary. |
protected void |
putStringValue(String key,
byte[] val)
Add (or replace) a String to the
V dictionary. |
protected void |
putTextStringValue(String key,
String val)
Add (or replace) a Text String to the
V dictionary. |
protected byte[] |
sign()
Finish the digest calculation on the digest returned from
getMessageDigest()
and return a signature token the signs it. |
protected abstract boolean |
verify(InputStream in)
Return a boolean indicating whether or not the signature handler
can verify the specified
InputStream . |
protected boolean containsKey(String key)
V
dictionary contains the specified keyprotected final byte[] getStringValue(String key)
V
dictionary as a byte array
or null
if no such field existsprotected final String getTextStringValue(String key)
V
dictionary as a String
or null
if no such field existsprotected final String getNameValue(String key)
V
dictionary as a String
or null
if no such field existsprotected final float getNumericValue(String key)
V
dictionary as a float
or Float.NaN
if no such field existsprotected final boolean getBooleanValue(String key)
V
dictionary as a boolean
or false
if no such field existsprotected final int getArrayValueSize(String key)
V
dictionary,
or -1
if no such field existsprotected final Set<String> getDictionaryValueKeys(String key)
V
dictionary,
or null
if no such field exists.protected final InputStream getStreamValue(String key)
V
dictionary,
or false
if no such field existsprotected final void putStringValue(String key, byte[] val)
V
dictionary.
A value of null
removes the entry.protected final void putTextStringValue(String key, String val)
V
dictionary.
A value of null
removes the entryprotected final void putNumericValue(String key, float val)
V
dictionary.
A value of Float.NaN
removes the entry.protected final void putNameValue(String key, String val)
V
dictionary.
A value of null
removes the entry.protected final void putBooleanValue(String key, boolean val)
V
dictionary.protected final void putArrayValue(String key)
V
dictionary.protected final void putDictionaryValue(String key)
V
dictionary.protected final void putStreamValue(String key, byte[] val)
V
dictionary.public String getHandlerName()
public Map<String,SignatureHandler.Placeholder> getVariables() throws GeneralSecurityException
Return the list of "variables" which will be set by the handler after the
PDF is rendered. Entries in the returned map should have a String
as a key and a SignatureHandler.Placeholder
as a value. These placeholders will be
inserted into the PDF at the correct points.
For most SignatureHandlers, the only variables are the "ByteRange" and "Contents" array containing the signature token, which is what this method returns (it may be overridden if more variables are required).
This method was updated for a new signing architecture in release 2.11.12.
GeneralSecurityException
AcrobatSignatureHandlerFactory.setContentSize(int)
public int getEstimatedContentSize(int contentsize)
contentsize
- the negation of any value previously passed into setContentSize(int)
public abstract String getFilter()
protected void preDigest(long filelength, Map<String,SignatureHandler.Placeholder> variables) throws Exception
filelength
- the length of the PDF file, in bytesvariables
- the Map of variables, ordered by their position in the file.Exception
protected void postDigest(long filelength, Map<String,SignatureHandler.Placeholder> variables) throws Exception
filelength
- the length of the PDF file, in bytesvariables
- the Map of variables, ordered by their position in the file.Exception
protected byte[] sign() throws GeneralSecurityException, IOException
Finish the digest calculation on the digest returned from 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
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 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
getVariables()
method.
GeneralSecurityException
- if the signature cannot be applied for some cryptographic reasonIOException
- if the InputStream cannot be readgetMessageDigest()
internally)protected abstract MessageDigest getMessageDigest()
sign()
- see the API docs
for that method for more details.protected abstract boolean verify(InputStream in) throws GeneralSecurityException, IOException
InputStream
.GeneralSecurityException
- if the signature cannot be verified for some cryptographic reasonIOException
- if the InputStream cannot be readprotected void prepareToSign(KeyStore keystore, String alias, char[] password) throws GeneralSecurityException
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.
keystore
- the KeyStorealias
- which key to usepassword
- the password to use to decode the keyGeneralSecurityException
public abstract 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.
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" ]
.
getLayerAppearance(java.lang.String, org.faceless.pdf2.PDFStyle)
public abstract PDFCanvas getLayerAppearance(String layername, PDFStyle style)
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.layername
- the layer to create (from the list returned by getLayerNames()
)style
- the style in which to draw the text, if anyPDFCanvas
of any size containing the specified layer.getLayerNames()
public String getDefaultName()
FormSignature.setName(java.lang.String)
, or null
if no such name
is available.public FormSignature getFormSignature()
FormSignature
this handler is attaached topublic int getCertificationType()
getFormSignature()
attests to.
One of FormSignature.CERTIFICATION_UNCERTIFIED
, FormSignature.CERTIFICATION_NOCHANGES
,
FormSignature.CERTIFICATION_ALLOWFORMS
or FormSignature.CERTIFICATION_ALLOWCOMMENTS
.
By default this method returns the certification from the standard PDF
Signature certification dictionary, but subclasses can return their own
restriction if necessary by overriding this method.FormSignature.getCertificationType()
,
FormSignature.setCertificationType(int, java.lang.String)
Copyright © 2001-2017 Big Faceless Organization