org.faceless.pdf2.viewer2.feature

## Class KeyStoreSignatureProvider

- java.lang.Object
- - org.faceless.pdf2.viewer2.ViewerFeature
  - - org.faceless.pdf2.viewer2.SignatureProvider
    - - org.faceless.pdf2.viewer2.feature.KeyStoreSignatureProvider

-     public class KeyStoreSignatureProvider
      extends SignatureProvider

  A `SignatureProvider` that signs and verifies signatures from a `KeyStoreManager` (ie from a local `KeyStore`. It can verify signatures using any `PKCS7SignatureHandler`, and it can sign PDFs using any `AcrobatSignatureHandlerFactory`.

  By default this class will prompt the user for the name, reason etc., and let the user choose a private key from the `KeyStore` to sign the PDF. Developers who want to pre-set this information can do so by specifying the values as initialization parameters for the PDFViewer.

  The following initialization parameters can be specified to configure this feature, as well as those parameters specified in the `SignatureProvider` API documentation.

  alias | The default value returned by the `getDefaultAlias()` method
  password | The default value returned by the `getDefaultPassword()` method
  digestAlgorithm | The default value returned by the `getDefaultDigestAlgorithm()` method
  timeStampServer | The default value returned by the `getDefaultTimeStampServer()` method
  contentSize | The default value returned by the `getDefaultContentSize()` method

  As an example, when deploying the PDFViewer as an applet here's how to ensure every signature applied with this class has the location specified is cryptographically time-stamped using an RFC 3161 server. To save making two requests to the time-stamp server, we're pre-allocating 8KB to store the PKCS#7 signature in the PDF. The `AcrobatSignatureHandlerFactory` class has more information on these parameters.

       <applet code="org.faceless.pdf2.viewer2.PDFViewerApplet" name="pdfapplet" archive="bfopdf.jar">
        <param name="feature.KeyStoreSignatureProvider.location" value="Signed using demo application" />
        <param name="feature.KeyStoreSignatureProvider.timeStampServer" value="https://tsa.aloaha.com/" />
        <param name="feature.KeyStoreSignatureProvider.contentSize" value="8192" />
       </applet>

  The name of this feature is KeyStoreSignatureProvider

  This code is copyright the Big Faceless Organization. You're welcome to use, modify and distribute it in any form in your own projects, provided those projects continue to make use of the Big Faceless PDF library.

  Since:
    2.11
  See Also:
    `AcrobatSignatureHandlerFactory`, `PKCS7SignatureHandler`, `KeyStoreManager`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `KeyStoreSignatureProvider.X509SignatureState` A subclass of SignatureState that references an X.509 Certificate.

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

      `SignatureProvider.SignatureState`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeyStoreSignatureProvider()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canSign(FormSignature field)` Return true if this SignatureProvider can sign the specified field
    `boolean` | `canVerify(FormSignature field)` Return true if this SignatureProvider can verify the specified field
    `protected JComponent` | `getCertificatePanel(X509Certificate cert)` Return a JComponent that contains information about a single X.509 certificate.
    `protected JComponent` | `getCertificatesPanel(KeyStoreSignatureProvider.X509SignatureState state, DocumentPanel root, X509Certificate[] certs, X509Certificate cert, JTabbedPane tabbedpane)` Return a JComponent that contains information about the X.509 certificates used in the signature.
    `String` | `getDefaultAlias()` Return the KeyStore alias to use when signing a PDF using this SignatureProvider.
    `int` | `getDefaultContentSize()` Return the "Content Size" to be used by the default `AcrobatSignatureHandlerFactory`.
    `String` | `getDefaultDigestAlgorithm()` Return the Digest Algorithm to be used by the default `AcrobatSignatureHandlerFactory`.
    `char[]` | `getDefaultPassword()` Return the password to use when signing a PDF using this SignatureProvider.
    `URL` | `getDefaultTimeStampServer()` Return the URL of an RFC 3161 TimeStamp server to be used by the default `AcrobatSignatureHandlerFactory`.
    `String` | `getDisplayName()` Return the "user friendly" name of this SignatureProvider, to use in dialogs and menus.
    `KeyStoreManager` | `getKeyStoreManager()` Return the `KeyStoreManager` used by this class - either the value returned by `PDFViewer.getKeyStoreManager()` (the default) or a value previously set by a call to `setKeyStoreManager()`.
    `protected PDFCanvas` | `getSignatureAppearance(KeyStoreManager manager, KeyStore keystore, String alias, float width, float height)` Return the PDFCanvas to be used as a SignatureAppearance for this signature, or null to use the default
    `protected SignatureHandlerFactory` | `getSignatureHandlerFactory()` Get the `SignatureHandlerFactory` used to sign fields using this class.
    `protected JComponent` | `getSignatureStatePanel(KeyStoreSignatureProvider.X509SignatureState state, DocumentPanel root)` Return a JComponent that contains information about the SignatureState.
    `protected JComponent` | `getTimestampPanel(KeyStoreSignatureProvider.X509SignatureState state, DocumentPanel root)` Return a JComponent that contains information about the timestamp of the signature.
    `void` | `setKeyStoreManager(KeyStoreManager keyStoreManager)` Set the `KeyStoreManager` used by this class, which will override the default.
    `void` | `setSignatureHandlerFactory(SignatureHandlerFactory factory)` Set the `SignatureHandlerFactory` used to sign fields using this class.
    `void` | `showSignDialog(JComponent root, FormSignature field)` Display the signing dialog for the specified field, and assuming all goes well sign the field at the end.
    `void` | `showVerifyDialog(JComponent jroot, FormSignature field)` Show a dialog displaying information about the specified (signed) digital signature field.
    `SignatureProvider.SignatureState` | `verify(JComponent root, FormSignature field)` Verify the field.

    - ### Methods inherited from class org.faceless.pdf2.viewer2.SignatureProvider

      `getDefaultCertificationType, getDefaultLocation, getDefaultName, getDefaultReason, getIcon, getSignatureState, getViewer, initialize, selectSignProvider, selectVerifyProvider, setSignatureState`

    - ### Methods inherited from class org.faceless.pdf2.viewer2.ViewerFeature

      `getAllEnabledFeatures, getAllFeatures, getCustomJavaScript, getFeatureProperty, getFeatureURLProperty, getName, isEnabledByDefault, setFeatureName, teardown, toString`

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

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

- - ### Constructor Detail

    - #### KeyStoreSignatureProvider

          public KeyStoreSignatureProvider()

  - ### Method Detail

    - #### getDisplayName

          public String getDisplayName()

      Description copied from class: `SignatureProvider`
      Return the "user friendly" name of this SignatureProvider, to use in dialogs and menus.
      Specified by:
        `getDisplayName` in class `SignatureProvider`

    - #### setSignatureHandlerFactory

          public void setSignatureHandlerFactory(SignatureHandlerFactory factory)

      Set the `SignatureHandlerFactory` used to sign fields using this class.
      Parameters:
        `factory` - the SignatureHandlerFactory to use when signing

    - #### getSignatureHandlerFactory

          protected SignatureHandlerFactory getSignatureHandlerFactory()

      Get the `SignatureHandlerFactory` used to sign fields using this class. This is either set by `setSignatureHandlerFactory()`, or a new `AcrobatSignatureHandlerFactory` which has been initialized using the `getDefaultContentSize()`, `getDefaultDigestAlgorithm()` and `getDefaultTimeStampServer()` methods.

    - #### getKeyStoreManager

          public KeyStoreManager getKeyStoreManager()

      Return the `KeyStoreManager` used by this class - either the value returned by `PDFViewer.getKeyStoreManager()` (the default) or a value previously set by a call to `setKeyStoreManager()`.

    - #### setKeyStoreManager

          public void setKeyStoreManager(KeyStoreManager keyStoreManager)

      Set the `KeyStoreManager` used by this class, which will override the default.
      Parameters:
        `keyStoreManager` - the KeyStoreManager to use, or `null` to use the default.

    - #### canSign

          public boolean canSign(FormSignature field)

      Description copied from class: `SignatureProvider`
      Return true if this SignatureProvider can sign the specified field
      Specified by:
        `canSign` in class `SignatureProvider`

    - #### canVerify

          public boolean canVerify(FormSignature field)

      Description copied from class: `SignatureProvider`
      Return true if this SignatureProvider can verify the specified field
      Specified by:
        `canVerify` in class `SignatureProvider`

    - #### getDefaultAlias

          public String getDefaultAlias()

      Return the KeyStore alias to use when signing a PDF using this SignatureProvider. By default this method checks the "alias" `feature property` for this class - if specified, it must be a valid alias from the KeyStore, and the user won't be prompted to select one from the list. You will almost certainly want to specify the `password` too.
      Returns:
        the alias to use from the KeyStore, or `null` to let the user select one from the KeyStore.

    - #### getDefaultPassword

          public char[] getDefaultPassword()

      Return the password to use when signing a PDF using this SignatureProvider.
      Returns:
        the password to use to unlock the alias returned by `getDefaultAlias()`, or `null` to let the user enter one.
      See Also:
        `getDefaultAlias()`

    - #### getDefaultTimeStampServer

          public URL getDefaultTimeStampServer()

      Return the URL of an RFC 3161 TimeStamp server to be used by the default `AcrobatSignatureHandlerFactory`. See that class for more information.
      Returns:
        the URL of an RFC 3161 TimeStamp server, or `null` not to specify one.

    - #### getDefaultDigestAlgorithm

          public String getDefaultDigestAlgorithm()

      Return the Digest Algorithm to be used by the default `AcrobatSignatureHandlerFactory`. See that class for more information.
      Returns:
        the digest algorithm to use, or `null` for the factory default.

    - #### getDefaultContentSize

          public int getDefaultContentSize()

      Return the "Content Size" to be used by the default `AcrobatSignatureHandlerFactory`. See that class for more information.
      Returns:
        the contet size to pass to the factory, or `0` for the factory default.

    - #### showSignDialog

          public void showSignDialog(JComponent root,
                                     FormSignature field)
                              throws IOException,
                                     GeneralSecurityException

      Description copied from class: `SignatureProvider`
      Display the signing dialog for the specified field, and assuming all goes well sign the field at the end.
      Specified by:
        `showSignDialog` in class `SignatureProvider`
      Parameters:
        `root` - the JCompoment the dialog should be relative to - typically this is the `DocumentPanel`
        `field` - the field to be signed
      Throws:
        `IOException`
        `GeneralSecurityException`

    - #### getSignatureAppearance

          protected PDFCanvas getSignatureAppearance(KeyStoreManager manager,
                                                     KeyStore keystore,
                                                     String alias,
                                                     float width,
                                                     float height)

      Return the PDFCanvas to be used as a SignatureAppearance for this signature, or null to use the default
      Parameters:
        `manager` - the KeyStoreManager
        `keystore` - the KeyStore
        `alias` - the alias being used
        `width` - the width of the annotation
        `height` - the height of the annotation
      Since:
        2.11.25

    - #### verify

          public SignatureProvider.SignatureState verify(JComponent root,
                                                         FormSignature field)

      Description copied from class: `SignatureProvider`
      Verify the field. Must be overridden by any SignatureProvider that returns true from `canVerify()`. This method may provide visual feedback to the user, but it's primary purpose is to verify the field and return its state so it should not block user progress unless it's unavoidable.
      Overrides:
        `verify` in class `SignatureProvider`
      Parameters:
        `root` - the component that should be used as a root for
        `field` - the signed field

    - #### showVerifyDialog

          public void showVerifyDialog(JComponent jroot,
                                       FormSignature field)

      Description copied from class: `SignatureProvider`
      Show a dialog displaying information about the specified (signed) digital signature field. The dialog should display the signatures verification state, which may be determined by this method or retrieved from a previous verification
      Specified by:
        `showVerifyDialog` in class `SignatureProvider`
      Parameters:
        `jroot` - the JCompoment the dialog should be relative to - typically this is the `DocumentPanel`
        `field` - the field to be verified

    - #### getSignatureStatePanel

          protected JComponent getSignatureStatePanel(KeyStoreSignatureProvider.X509SignatureState state,
                                                      DocumentPanel root)

      Return a JComponent that contains information about the SignatureState. This method is used internally by the `showVerifyDialog()` method, and there's generally no reason to call it directly.
      Parameters:
        `state` - the X509SignatureState to display
        `root` - the DocumentPanel containing the PDF
      Returns:
        the panel to be added to the Signature Information dialog

    - #### getCertificatesPanel

          protected JComponent getCertificatesPanel(KeyStoreSignatureProvider.X509SignatureState state,
                                                    DocumentPanel root,
                                                    X509Certificate[] certs,
                                                    X509Certificate cert,
                                                    JTabbedPane tabbedpane)
                                             throws CertificateException

      Return a JComponent that contains information about the X.509 certificates used in the signature. This method is used internally by the `getSignatureStatePanel()` method, and there's generally no reason to call it directly.
      Parameters:
        `state` - the X509SignatureState
        `root` - the DocumentPanel containing the PDF
        `certs` - the chain of X.509 Certificates that signed the PDF, for display
        `cert` - the X.509 certificate that signed the PDF, but is untrusted. If the certificate is trusted this parameter should be null
        `tabbedpane` - the JTabbedPane to add the panel to.
      Returns:
        the panel to be added to the Signature Information dialog
      Throws:
        `CertificateException`

    - #### getCertificatePanel

          protected JComponent getCertificatePanel(X509Certificate cert)

      Return a JComponent that contains information about a single X.509 certificate. This method is used internally by the `getSignatureStatePanel()` method, and there's generally no reason to call it directly.
      Parameters:
        `cert` - the Certificate to display
      Returns:
        the component to be displayed

    - #### getTimestampPanel

          protected JComponent getTimestampPanel(KeyStoreSignatureProvider.X509SignatureState state,
                                                 DocumentPanel root)

      Return a JComponent that contains information about the timestamp of the signature. For Signatures not timestamped according to RFC3161, this panel will simply display the signature time from the computer clock. This method is used internally by the `getSignatureStatePanel()` method, and there's generally no reason to call it directly.
      Parameters:
        `state` - the X509SignatureState
        `root` - the DocumentPanel containing the PDF

Copyright © 2001-2015 Big Faceless Organization