org.faceless.pdf2

## Class PKCS7SignatureHandler

- java.lang.Object
- - org.faceless.pdf2.SignatureHandler
  - - org.faceless.pdf2.PKCS7SignatureHandler

-     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. Currently we know of three handlers that meet this requirement - the general purpose PKCS#7 handler supplied with Acrobat 6.0 and later, or (for earlier versions) the Adobe "Self-Sign" handler and the plugin supplied by VeriSign.

  See Also:
    `AcrobatSignatureHandlerFactory`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.faceless.pdf2.SignatureHandler

      `SignatureHandler.Placeholder`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.faceless.pdf2.PKCS7` | `pkcs7`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `PKCS7SignatureHandler()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `protected abstract 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.
    `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.
    `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`.

    - ### Methods inherited from class org.faceless.pdf2.SignatureHandler

      `containsKey, getArrayValueSize, getBooleanValue, getCertificationType, getDictionaryValueKeys, getFilter, getFormSignature, getNameValue, getNumericValue, getStreamValue, getStringValue, getTextStringValue, getVariables, postDigest, preDigest, putArrayValue, putBooleanValue, putDictionaryValue, putNameValue, putNumericValue, putStreamValue, putStringValue, putTextStringValue`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### pkcs7

          protected org.faceless.pdf2.PKCS7 pkcs7

  - ### Constructor Detail

    - #### PKCS7SignatureHandler

          protected PKCS7SignatureHandler()

  - ### Method Detail

    - #### getHashAlgorithm

          protected abstract String getHashAlgorithm()

      Return the Hash algorithm used by the PKCS#7 object when signing. Valid values are currently SHA1, SHA256, SHA384, SHA512 or MD5

    - #### getSubFilter

          public abstract String getSubFilter()

      Return the SubFilter field, which determines how the PKCS#7 object is encoded. Valid values are "adbe.pkcs7.detached", "adbe.pkcs7.sha1" "adbe.x509.rsa_sha1" or "ETSI.CAdES.detached"

    - #### prepareToSign

          protected void prepareToSign(KeyStore keystore,
                                       String alias,
                                       char[] password)
                                throws GeneralSecurityException

      Description copied from class: `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.

      Overrides:
        `prepareToSign` in class `SignatureHandler`
      Parameters:
        `keystore` - the KeyStore
        `alias` - which key to use
        `password` - the password to use to decode the key
      Throws:
        `GeneralSecurityException`

    - #### getEstimatedContentSize

          public int getEstimatedContentSize(int additional)

      Description copied from class: `SignatureHandler`
      Return the estimated size of the signature object to be embedded, or <= 0 if this cannot be determined. The default implementation returns 0.
      Overrides:
        `getEstimatedContentSize` in class `SignatureHandler`
      Parameters:
        `additional` - the negation of any value previously passed into `SignatureHandler.setContentSize(int)`

    - #### getMessageDigest

          public MessageDigest getMessageDigest()

      Description copied from class: `SignatureHandler`
      Return a MessageDigest that will be used to calculate the digest of the PDF for signing. This message will be called before `SignatureHandler.sign()` - see the API docs for that method for more details.
      Specified by:
        `getMessageDigest` in class `SignatureHandler`

    - #### sign

          public byte[] sign()
                      throws GeneralSecurityException,
                             IOException

      Description copied from class: `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.

      Overrides:
        `sign` in class `SignatureHandler`
      Returns:
        a byte array representing the signature token
      Throws:
        `GeneralSecurityException` - if the signature cannot be applied for some cryptographic reason
        `IOException` - if the InputStream cannot be read

    - #### verify

          public final boolean verify(InputStream in)
                               throws GeneralSecurityException,
                                      IOException

      Description copied from class: `SignatureHandler`
      Return a boolean indicating whether or not the signature handler can verify the specified `InputStream`.
      Specified by:
        `verify` in class `SignatureHandler`
      Returns:
        true if the signature matches the specified InputStream
      Throws:
        `GeneralSecurityException` - if the signature cannot be verified for some cryptographic reason
        `IOException` - if the InputStream cannot be read

    - #### getCertificates

          public X509Certificate[] getCertificates()
                                            throws CertificateException

      Return the list of certificates included in this signature. The first certificate is the X.509 certificate used to sign the PDF, and the optional additional certificates are those used to validate the earlier certificates, in no particular order.
      Returns:
        a list of one or more X.509 Certificates
      Throws:
        `CertificateException`

    - #### getLayerNames

          public String[] getLayerNames()

      Description copied from class: `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" ]`.

      Specified by:
        `getLayerNames` in class `SignatureHandler`
      Returns:
        the ordered list of layer names that should to used to create a visible representation of this signature on a page.
      See Also:
        `SignatureHandler.getLayerAppearance(java.lang.String, org.faceless.pdf2.PDFStyle)`

    - #### getLayerAppearance

          public PDFCanvas getLayerAppearance(String layername,
                                              PDFStyle textstyle)

      Description copied from class: `SignatureHandler`
      Return a `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.
      Specified by:
        `getLayerAppearance` in class `SignatureHandler`
      Parameters:
        `layername` - the layer to create (from the list returned by `SignatureHandler.getLayerNames()`)
        `textstyle` - the style in which to draw the text, if any
      Returns:
        a new `PDFCanvas` of any size containing the specified layer.
      See Also:
        `SignatureHandler.getLayerNames()`

    - #### setCustomAppearance

          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.

      Parameters:
        `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
      Since:
        2.0

    - #### getTimeStampCertificates

          public 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`.
      Returns:
        an array of `X509Certificate` objects that authorized the timestamp, or `null` if there isn't a timestamp.
      Throws:
        `GeneralSecurityException` - if the TimeStamp is invalid
        `IOException` - if the TimeStamp is corrupt or can't be parsed
      Since:
        2.7.1

    - #### getDefaultName

          public String getDefaultName()

      Description copied from class: `SignatureHandler`
      Returns an optional default value that can be used to initialize `FormSignature.setName(java.lang.String)`, or `null` if no such name is available.
      Overrides:
        `getDefaultName` in class `SignatureHandler`

Copyright © 2001-2015 Big Faceless Organization