Package se.idsec.signservice.integration

Interface ExtendedSignServiceIntegrationService

All Superinterfaces:
SignServiceIntegrationService
public interface ExtendedSignServiceIntegrationService extends SignServiceIntegrationService
An extension to the interface describing the API for the SignService Integration Service.

This extension is optional to implement, but its purpose is to supply the user of the API with utility methods that are useful during signature processing.

Author:
Martin Lindström (martin@idsec.se), Stefan Santesson (stefan@idsec.se)

  • Method Details

    • preparePdfDocument

      PreparedPdfDocument preparePdfDocument(@Nullable String policy, @Nonnull byte[] pdfDocument, @Nullable PdfSignaturePagePreferences signaturePagePreferences, @Nullable Boolean returnDocumentReference, @Nullable String callerId) throws InputValidationException, PdfSignaturePageFullException, PdfAConsistencyCheckException, PdfContainsAcroformException, PdfContainsEncryptionDictionaryException, SignServiceIntegrationException
      A utility method that can be used to prepare a PDF document for signing.

      The main purpose is to prepare a document that is to be signed with a PDF signature page holding the signature image(s), but the method may also be used to ensure that the document is correct with respect to its format, and also have the document "fixed" (see below).

      Signature pages and visible signatures

      A PDF signature image can be inserted into a signed PDF document to make the signature information "visible". The image along with the coordinates that tell where in the PDF document the image should be inserted is represented using a VisiblePdfSignatureRequirement object. See TbsDocument.getVisiblePdfSignatureRequirement().

      However, for the generic case, where we may not always know how the PDF document that we are signing looks like it may be tricky to determine where in the document the PDF signature image should be inserted. For those cases, a dedicated "PDF signature page" may be added to the PDF document before it is added to a TbsDocument object and sent as input in a signature operation. By using a PDF signature page whose structure and constitution is well known it is easy to include a PDF signature image into any PDF document being signed.

      Also, since a PDF document can be signed several times, using a PDF signature page it is easy to include signature images for all signatures of the document.

      The preparePdfSignaturePage method should invoked before each call to SignServiceIntegrationService.createSignRequest(SignRequestInput) where PDF documents with PDF signature pages is to be used. If a PDF document is to be signed is signed more than once and the PDF signature page supports several signature images, no new PDF signature page is added. Instead, the preparePdfSignaturePage method calculates where in the already existing PDF signature page the next signature image will be inserted.

      If the policy states that PDF/A constistence checks should be done (see PdfPrepareSettings.isEnforcePdfaConsistency(), the method will enforce that sign pages are PDF/A if the document being signed is PDF/A.

      Fixing PDF Issues

      Depending on the settings of the profile configuration's PdfPrepareSettings the method may adjust the document being signed by:

      • Flattening any present Acroforms from the document.
      • Removing the encryption dictionary from the document, if present.
      A note about the returnDocumentReference parameter

      If the backend service is running in "stateful" mode, meaning that it maintains a state of ongoing operations in the service itself, the processed (prepared) document may be saved in the state, and later be referenced in a call to createSignRequest. This way a potentially large document only has to be "uploaded" once.

      By setting the returnDocumentReference parameter to true the method will not return the (potentially updated) document, but instead a reference to it (see PreparedPdfDocument.getPdfDocumentReference()).

      In "stateful" more the default value for the returnDocumentReference parameter is true. In stateless mode, the value of the parameter is ignored.

      Parameters:
      policy - the policy under which the operation is performed (see SignRequestInput.getPolicy()). If null, the default policy is used.
      pdfDocument - the contents of the PDF document that is to be prepared
      signaturePagePreferences - the PDF signature page preferences (if null, no sign page is used)
      returnDocumentReference - whether to use document references (see above)
      callerId - the identity for the calling entity (only needed if the implementation is a stand-alone service running in stateful mode)
      Returns:
      a PreparedPdfDocument object containing the modified PDF document (if a sign page was added) and the VisiblePdfSignatureRequirement telling how a signature image should be added
      Throws:
      InputValidationException - for input validation errors
      PdfSignaturePageFullException - if the PDF document contains more signatures than there is room for in the PDF signature page (and PdfSignaturePagePreferences.isFailWhenSignPageFull() evaluates to true)
      PdfAConsistencyCheckException - if the policy is configured to enforce PDF/A consistency, and a sign page that is not PDF/A is attempted to be added to a PDF/A document
      PdfContainsAcroformException - the PDF document contains an Acroform (and policy is not configured to flatten such forms)
      PdfContainsEncryptionDictionaryException - the PDF document contains an encryption dictionary (and policy is not configured to remove these)
      SignServiceIntegrationException - for other processing errors