Enclosing class:

PKCS7SignatureHandler
```
public static interface PKCS7SignatureHandler.SigningEngine
```
This interface defines the engine used to actually sign a PDF. The AcrobatSignatureHandlerFactory.createSigningEngine(java.security.KeyStore, java.lang.String, char[], java.lang.String) method will return an instance of this interface to do the signing. If a custom method of signing is required, for example on a remote server, this is the interface that will need implementing

Since:

2.22

Nested Class Summary

Nested Classes
Modifier and Type	Interface	Description
`static class`	`PKCS7SignatureHandler.SigningEngine.Type`	An enum that determine which type of PKCS7 Signature structure will be embedded with a SigningEngine

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`java.util.List<java.security.cert.X509Certificate>`	`getCertificates()`	Return the full list of X.509 certificates to be embedded into the signature.
`java.util.List<java.security.cert.X509CRL>`	`getCRLs()`	Return a list of X.509 CRL objects that should be used if required, or `null`.
`java.lang.String`	`getDigestEncryptionAlgorithm()`	Return the Digest Encryption algorithm of the signature returned from `sign(byte[])`, eg "SHA1withRSA", "SHA1withDSA", "SHA256withECDSA", or an ASN.1 OID representing the same, eg "1.2.840.113549.1.1.5".
`java.security.MessageDigest`	`getMessageDigest()`	Return a new MessageDigest to be used to compute the signature.
`java.util.List<PKCS7SignatureHandler.OCSPResponse>`	`getOCSPResponses()`	Return a list of OCSP responses that should be used if required, or `null`.
`byte[]`	`getTimeStampResp(byte[] digest)`	Return an ASN.1 encoded "TimeStampResp" (as defined in RFC3161) to be embedded in the PKCS#7 object, or `null` if no TimeStampResp is available.
`PKCS7SignatureHandler.SigningEngine.Type`	`getType()`	Return the type of object returned from the `sign(byte[])` method
`void`	`setPassword(javax.security.auth.callback.PasswordCallback callback)`	Set the password on the suppled PasswordCallback.
`byte[]`	`sign(byte[] digest)`	Actually sign the digest and returned the signature.

Method Detail

getType
```
PKCS7SignatureHandler.SigningEngine.Type getType()
```
Return the type of object returned from the sign(byte[]) method

getMessageDigest
```
java.security.MessageDigest getMessageDigest()
                                      throws java.security.NoSuchAlgorithmException
```
Return a new MessageDigest to be used to compute the signature. This will be called once per signature. Note in 2.28 the "throws NoSuchAlgorithmException" was added to the method signature

Throws:

java.security.NoSuchAlgorithmException

getCertificates
```
java.util.List<java.security.cert.X509Certificate> getCertificates()
                                                            throws java.io.IOException,
                                                                   java.security.GeneralSecurityException
```
Return the full list of X.509 certificates to be embedded into the signature. This must include any certificates required to certify the signature up to the root certificate, and includes Certificates for any OCSP responders that would be queried as part of the Certificate verification process. The signing Certificate must be item 0 in the list.
The one exception to this is if getType() returns PKCS7SignatureHandler.SigningEngine.Type.PKCS7_COMPLETE, in which case this method may return null.
This method will be called multiple times, so the object returned from this method should be stored locally.

Throws:

java.io.IOException

java.security.GeneralSecurityException

sign
```
byte[] sign(byte[] digest)
     throws java.io.IOException,
            java.security.GeneralSecurityException
```
Actually sign the digest and returned the signature.
The exact format of the returned item will vary depending on the getType(), but is typically the output of the Signature.sign() method. For RSA signatures this equates to rsa(pad(DigestInfo)), which is effectively rsa(pad(asn1sequence(asn1sequence(algorithm, NULL), digest))), where rsa is the RSA algorithm, pad is the PKCS#1 1.5 padding algorithm, algorithm is the hash algorithm OID, and digest is an ASN.1 Octet string representing the digest supplied to this method.
The one exception to this is if getType() returns PKCS7SignatureHandler.SigningEngine.Type.PKCS7_COMPLETE, in which case this method should return the entire PKCS#7 object to embed in the PDF.
This method may be called with a null argument for the digest, in which case the API is attempting to determine the size of the signed object for space allocation in the final PDF. If an accurate estimate can be made, the returned array should be of the correct length (the contents of the array do not matter in this case). If no estimate can be made this method should return a zero-length array.

Parameters:

digest - the digest to sign, or null if it's a test run to determine sie.

Returns:

the signed object, as determined by the mode of this object

Throws:

java.io.IOException

java.security.GeneralSecurityException

getTimeStampResp

byte[] getTimeStampResp(byte[] digest)
                 throws java.io.IOException,
                        java.security.GeneralSecurityException

Return an ASN.1 encoded "TimeStampResp" (as defined in RFC3161) to be embedded in the PKCS#7 object, or null if no TimeStampResp is available. Like sign(byte[]), this method may be called with a null digest - if so the size of the returned array will be used to estimate how much space to allocate in the PDF. If this is not known, a zero-byte array should be returned.

To help clarify this, here's a list of the possible inputs and outputs to this method, and what they mean.

input	output	explanation
null	null	the API is trying to find out how big a TimeStamp would be if we were signing, and the null response means "there will be no timestamp"
null	byte[0]	the API is trying to find out how big a TimeStamp would be if we were signing, and the zero-length response means "there will be a timestamp, but the only way to know how big it will be is it sign something"
null	byte[n]	the API is trying to find out how big a TimeStamp would be if we were signing, and the non-zero-length response means "there will be a timestamp, and it will be the same size as this byte array"
byte[n]	null	this is a real TimeStamp request. The null response means this signature is not timestamped
byte[n]	byte[n]	this is a real TimeStamp request. The non-zero-length response is the actual TimeStamp to embed

Parameters:: digest - the digest to sign, or null if it's a dummy.
Returns:: null to mean "no timestamp", a zero-byte array to mean "timestamp of unknown size", or a non-zero byte array which is the TimeStamp response
Throws:: java.io.IOException; java.security.GeneralSecurityException

getDigestEncryptionAlgorithm
```
java.lang.String getDigestEncryptionAlgorithm()
```
Return the Digest Encryption algorithm of the signature returned from sign(byte[]), eg "SHA1withRSA", "SHA1withDSA", "SHA256withECDSA", or an ASN.1 OID representing the same, eg "1.2.840.113549.1.1.5".

setPassword
```
void setPassword(javax.security.auth.callback.PasswordCallback callback)
```
Set the password on the suppled PasswordCallback. This is required because some types of PKCS#11 token require a second login immediately before the "sign" call. For SigningEngines unconcerned with PKCS#11, this method can be a no-op.

Since:

2.25

getOCSPResponses

java.util.List<PKCS7SignatureHandler.OCSPResponse> getOCSPResponses()
                                                             throws java.io.IOException,
                                                                    java.security.GeneralSecurityException

Return a list of OCSP responses that should be used if required, or null.

Throws:: java.io.IOException; java.security.GeneralSecurityException
Since:: 2.28

getCRLs

java.util.List<java.security.cert.X509CRL> getCRLs()
                                            throws java.io.IOException,
                                                   java.security.GeneralSecurityException

Return a list of X.509 CRL objects that should be used if required, or null.

Throws:: java.io.IOException; java.security.GeneralSecurityException
Since:: 2.28

Interface PKCS7SignatureHandler.SigningEngine

Nested Class Summary

Method Summary

Method Detail

getType

getMessageDigest

getCertificates

sign

getTimeStampResp

getDigestEncryptionAlgorithm

setPassword

getOCSPResponses

getCRLs