Package com.itextpdf.signatures

Class PdfSigner

java.lang.Object
com.itextpdf.signatures.PdfSigner
public class PdfSigner extends Object
Takes care of the cryptographic options and appearances that form a signature.

  • Field Details

    • NOT_CERTIFIED

      public static final int NOT_CERTIFIED
      Approval signature.
      See Also:

    • CERTIFIED_NO_CHANGES_ALLOWED

      public static final int CERTIFIED_NO_CHANGES_ALLOWED
      Author signature, no changes allowed.
      See Also:

    • CERTIFIED_FORM_FILLING

      public static final int CERTIFIED_FORM_FILLING
      Author signature, form filling allowed.
      See Also:

    • CERTIFIED_FORM_FILLING_AND_ANNOTATIONS

      public static final int CERTIFIED_FORM_FILLING_AND_ANNOTATIONS
      Author signature, form filling and annotations allowed.
      See Also:

    • certificationLevel

      protected int certificationLevel
      The certification level.

    • fieldName

      protected String fieldName
      The name of the field.

    • raf

      protected RandomAccessFile raf
      The file right before the signature is added (can be null).

    • bout

      protected byte[] bout
      The bytes of the file right before the signature is added (if raf is null).

    • range

      protected long[] range
      Array containing the byte positions of the bytes that need to be hashed.

    • document

      protected PdfDocument document
      The PdfDocument.

    • cryptoDictionary

      protected PdfSignature cryptoDictionary
      The crypto dictionary.

    • signatureEvent

      protected PdfSigner.ISignatureEvent signatureEvent
      Holds value of property signatureEvent.

    • originalOS

      protected OutputStream originalOS
      OutputStream for the bytes of the document.

    • temporaryOS

      protected ByteArrayOutputStream temporaryOS
      Outputstream that temporarily holds the output in memory.

    • tempFile

      protected File tempFile
      Tempfile to hold the output temporarily.

    • exclusionLocations

      protected Map<PdfName,PdfLiteral> exclusionLocations
      Name and content of keys that can only be added in the close() method.

    • preClosed

      protected boolean preClosed
      Indicates if the pdf document has already been pre-closed.

    • fieldLock

      protected PdfSigFieldLock fieldLock
      Signature field lock dictionary.

    • appearance

      protected PdfSignatureAppearance appearance
      The signature appearance.

    • signDate

      protected Calendar signDate
      Holds value of property signDate.

    • closed

      protected boolean closed
      Boolean to check if this PdfSigner instance has been closed already or not.

  • Constructor Details

    • PdfSigner

      public PdfSigner (PdfReader reader, OutputStream outputStream, StampingProperties properties) throws IOException
      Creates a PdfSigner instance. Uses a ByteArrayOutputStream instead of a temporary file.
      Parameters:
      reader - PdfReader that reads the PDF file
      outputStream - OutputStream to write the signed PDF file
      properties - StampingProperties for the signing document. Note that encryption will be preserved regardless of what is set in properties.
      Throws:
      IOException - if some I/O problem occurs

    • PdfSigner

      public PdfSigner (PdfReader reader, OutputStream outputStream, String path, StampingProperties stampingProperties, SignerProperties signerProperties) throws IOException
      Creates a PdfSigner instance. Uses a ByteArrayOutputStream instead of a temporary file.
      Parameters:
      reader - PdfReader that reads the PDF file
      outputStream - OutputStream to write the signed PDF file
      path - File to which the output is temporarily written
      stampingProperties - StampingProperties for the signing document. Note that encryption will be preserved regardless of what is set in properties.
      signerProperties - SignerProperties bundled properties to be used in signing operations.
      Throws:
      IOException - if some I/O problem occurs

    • PdfSigner

      public PdfSigner (PdfReader reader, OutputStream outputStream, String path, StampingProperties properties) throws IOException
      Creates a PdfSigner instance. Uses a ByteArrayOutputStream instead of a temporary file.
      Parameters:
      reader - PdfReader that reads the PDF file
      outputStream - OutputStream to write the signed PDF file
      path - File to which the output is temporarily written
      properties - StampingProperties for the signing document. Note that encryption will be preserved regardless of what is set in properties.
      Throws:
      IOException - if some I/O problem occurs

  • Method Details

    • initDocument

      protected PdfDocument initDocument (PdfReader reader, PdfWriter writer, StampingProperties properties)
      Initialize new PdfDocument instance by using provided parameters.
      Parameters:
      reader - PdfReader to be used as a reader in the new document
      writer - PdfWriter to be used as a writer in the new document
      properties - StampingProperties to be provided in the new document
      Returns:
      new PdfDocument instance

    • getSignDate

      public Calendar getSignDate()
      Gets the signature date.
      Returns:
      Calendar set to the signature date

    • setSignDate

      public void setSignDate (Calendar signDate)
      Sets the signature date.
      Parameters:
      signDate - the signature date

    • getSignatureAppearance

      @Deprecated public PdfSignatureAppearance getSignatureAppearance()
      Deprecated.
      Provides access to a signature appearance object. Use it to customize the appearance of the signature.

      Be aware:

      • If you create new signature field (either use setFieldName(java.lang.String) with the name that doesn't exist in the document or don't specify it at all) then the signature is invisible by default.
      • If you sign already existing field, then the signature appearance object is modified to have all the properties (page num., rect etc.) consistent with the state of the field (if you customized the appearance object before the setFieldName(java.lang.String) call you'll have to do it again)

      Returns:
      PdfSignatureAppearance object.

    • setSignatureAppearance

      public void setSignatureAppearance (SignatureFieldAppearance appearance)
      Sets the signature field layout element to customize the appearance of the signature. Signer's sign date will be set.
      Parameters:
      appearance - the SignatureFieldAppearance layout element.

    • getCertificationLevel

      public int getCertificationLevel()
      Returns the document's certification level. For possible values see setCertificationLevel(int).
      Returns:
      The certified status.

    • setCertificationLevel

      public void setCertificationLevel (int certificationLevel)
      Sets the document's certification level. This method overrides the value set by setCertificationLevel(AccessPermissions).
      Parameters:
      certificationLevel - a new certification level for a document. Possible values are:

    • setCertificationLevel

      public void setCertificationLevel (AccessPermissions accessPermissions)
      Sets the document's certification level. This method overrides the value set by setCertificationLevel(int).
      Parameters:
      accessPermissions - AccessPermissions enum which specifies which certification level shall be used

    • getFieldName

      public String getFieldName()
      Gets the field name.
      Returns:
      the field name

    • getSignatureDictionary

      public PdfSignature getSignatureDictionary()
      Returns the user made signature dictionary. This is the dictionary at the /V key of the signature field.
      Returns:
      The user made signature dictionary.

    • getSignatureEvent

      public PdfSigner.ISignatureEvent getSignatureEvent()
      Getter for property signatureEvent.
      Returns:
      Value of property signatureEvent.

    • setSignatureEvent

      public void setSignatureEvent (PdfSigner.ISignatureEvent signatureEvent)
      Sets the signature event to allow modification of the signature dictionary.
      Parameters:
      signatureEvent - the signature event

    • getNewSigFieldName

      public String getNewSigFieldName()
      Gets a new signature field name that doesn't clash with any existing name.
      Returns:
      A new signature field name.

    • setFieldName

      public void setFieldName (String fieldName)
      Sets the name indicating the field to be signed. The field can already be presented in the document but shall not be signed. If the field is not presented in the document, it will be created.
      Parameters:
      fieldName - The name indicating the field to be signed.

    • getDocument

      public PdfDocument getDocument()
      Gets the PdfDocument associated with this instance.
      Returns:
      the PdfDocument associated with this instance

    • setDocument

      protected void setDocument (PdfDocument document)
      Sets the PdfDocument.
      Parameters:
      document - The PdfDocument

    • getPageNumber

      public int getPageNumber()
      Provides the page number of the signature field which this signature appearance is associated with.
      Returns:
      The page number of the signature field which this signature appearance is associated with.

    • setPageNumber

      public PdfSigner setPageNumber (int pageNumber)
      Sets the page number of the signature field which this signature appearance is associated with. Implicitly calls setPageRect(com.itextpdf.kernel.geom.Rectangle) which considers page number to process the rectangle correctly.
      Parameters:
      pageNumber - The page number of the signature field which this signature appearance is associated with.
      Returns:
      this instance to support fluent interface.

    • getPageRect

      public Rectangle getPageRect()
      Provides the rectangle that represent the position and dimension of the signature field in the page.
      Returns:
      the rectangle that represent the position and dimension of the signature field in the page

    • setPageRect

      public PdfSigner setPageRect (Rectangle pageRect)
      Sets the rectangle that represent the position and dimension of the signature field in the page.
      Parameters:
      pageRect - The rectangle that represents the position and dimension of the signature field in the page.
      Returns:
      this instance to support fluent interface.

    • setOriginalOutputStream

      public void setOriginalOutputStream (OutputStream originalOS)
      Setter for the OutputStream.
      Parameters:
      originalOS - OutputStream for the bytes of the document

    • getFieldLockDict

      public PdfSigFieldLock getFieldLockDict()
      Getter for the field lock dictionary.
      Returns:
      Field lock dictionary.

    • setFieldLockDict

      public void setFieldLockDict (PdfSigFieldLock fieldLock)
      Setter for the field lock dictionary.

      Be aware: if a signature is created on an existing signature field, then its /Lock dictionary takes the precedence (if it exists).

      Parameters:
      fieldLock - Field lock dictionary

    • getSignatureCreator

      public String getSignatureCreator()
      Returns the signature creator.
      Returns:
      The signature creator.

    • setSignatureCreator

      public PdfSigner setSignatureCreator (String signatureCreator)
      Sets the name of the application used to create the signature.
      Parameters:
      signatureCreator - A new name of the application signing a document.
      Returns:
      this instance to support fluent interface.

    • getContact

      public String getContact()
      Returns the signing contact.
      Returns:
      The signing contact.

    • setContact

      public PdfSigner setContact (String contact)
      Sets the signing contact.
      Parameters:
      contact - A new signing contact.
      Returns:
      this instance to support fluent interface.

    • getReason

      public String getReason()
      Returns the signing reason.
      Returns:
      The signing reason.

    • setReason

      public PdfSigner setReason (String reason)
      Sets the signing reason.
      Parameters:
      reason - A new signing reason.
      Returns:
      this instance to support fluent interface.

    • getLocation

      public String getLocation()
      Returns the signing location.
      Returns:
      The signing location.

    • setLocation

      public PdfSigner setLocation (String location)
      Sets the signing location.
      Parameters:
      location - A new signing location.
      Returns:
      this instance to support fluent interface.

    • getSignatureField

      public PdfSignatureFormField getSignatureField()
      Gets the signature field to be signed. The field can already be presented in the document. If the field is not presented in the document, it will be created.

      This field instance is expected to be used for setting appearance related properties such as PdfSignatureFormField.setReuseAppearance(boolean), PdfSignatureFormField.setBackgroundLayer(com.itextpdf.kernel.pdf.xobject.PdfFormXObject) and PdfSignatureFormField.setSignatureAppearanceLayer(com.itextpdf.kernel.pdf.xobject.PdfFormXObject).

      Returns:
      the PdfSignatureFormField instance.

    • signDetached

      public void signDetached (IExternalDigest externalDigest, IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype) throws IOException, GeneralSecurityException
      Signs the document using the detached mode, CMS or CAdES equivalent.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignature - the interface providing the actual signing
      chain - the certificate chain
      crlList - the CRL list
      ocspClient - the OCSP client
      tsaClient - the Timestamp client
      externalDigest - an implementation that provides the digest
      estimatedSize - the reserved size for the signature. It will be estimated if 0
      sigtype - Either Signature.CMS or Signature.CADES
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signDetached

      public void signDetached (IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype) throws IOException, GeneralSecurityException
      Signs the document using the detached mode, CMS or CAdES equivalent.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignature - the interface providing the actual signing
      chain - the certificate chain
      crlList - the CRL list
      ocspClient - the OCSP client
      tsaClient - the Timestamp client
      estimatedSize - the reserved size for the signature. It will be estimated if 0
      sigtype - Either Signature.CMS or Signature.CADES
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signDetached

      public void signDetached (IExternalDigest externalDigest, IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype, SignaturePolicyInfo signaturePolicy) throws IOException, GeneralSecurityException
      Signs the document using the detached mode, CMS or CAdES equivalent.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignature - the interface providing the actual signing
      chain - the certificate chain
      crlList - the CRL list
      ocspClient - the OCSP client
      tsaClient - the Timestamp client
      externalDigest - an implementation that provides the digest
      estimatedSize - the reserved size for the signature. It will be estimated if 0
      sigtype - Either Signature.CMS or Signature.CADES
      signaturePolicy - the signature policy (for EPES signatures)
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signDetached

      public void signDetached (IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype, SignaturePolicyInfo signaturePolicy) throws IOException, GeneralSecurityException
      Signs the document using the detached mode, CMS or CAdES equivalent.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignature - the interface providing the actual signing
      chain - the certificate chain
      crlList - the CRL list
      ocspClient - the OCSP client
      tsaClient - the Timestamp client
      estimatedSize - the reserved size for the signature. It will be estimated if 0
      sigtype - Either Signature.CMS or Signature.CADES
      signaturePolicy - the signature policy (for EPES signatures)
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signDetached

      public void signDetached (IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype, ISignaturePolicyIdentifier signaturePolicy) throws IOException, GeneralSecurityException
      Signs the document using the detached mode, CMS or CAdES equivalent.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignature - the interface providing the actual signing
      chain - the certificate chain
      crlList - the CRL list
      ocspClient - the OCSP client
      tsaClient - the Timestamp client
      estimatedSize - the reserved size for the signature. It will be estimated if 0
      sigtype - Either Signature.CMS or Signature.CADES
      signaturePolicy - the signature policy (for EPES signatures)
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signDetached

      public void signDetached (IExternalDigest externalDigest, IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype, ISignaturePolicyIdentifier signaturePolicy) throws IOException, GeneralSecurityException
      Signs the document using the detached mode, CMS or CAdES equivalent.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignature - the interface providing the actual signing
      chain - the certificate chain
      crlList - the CRL list
      ocspClient - the OCSP client
      tsaClient - the Timestamp client
      externalDigest - an implementation that provides the digest
      estimatedSize - the reserved size for the signature. It will be estimated if 0
      sigtype - Either Signature.CMS or Signature.CADES
      signaturePolicy - the signature policy (for EPES signatures)
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signExternalContainer

      public void signExternalContainer (IExternalSignatureContainer externalSignatureContainer, int estimatedSize) throws GeneralSecurityException, IOException
      Sign the document using an external container, usually a PKCS7. The signature is fully composed externally, iText will just put the container inside the document.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      externalSignatureContainer - the interface providing the actual signing
      estimatedSize - the reserved size for the signature
      Throws:
      GeneralSecurityException - if some problem during apply security algorithms occurs
      IOException - if some I/O problem occurs

    • timestamp

      public void timestamp (ITSAClient tsa, String signatureName) throws IOException, GeneralSecurityException
      Signs a document with a PAdES-LTV Timestamp. The document is closed at the end.

      NOTE: This method closes the underlying pdf document. This means, that current instance of PdfSigner cannot be used after this method call.
      Parameters:
      tsa - the timestamp generator
      signatureName - the signature name or null to have a name generated automatically
      Throws:
      IOException - if some I/O problem occurs or estimation for timestamp signature, provided with ITSAClient.getTokenSizeEstimate(), is not big enough
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • signDeferred

      public static void signDeferred (PdfDocument document, String fieldName, OutputStream outs, IExternalSignatureContainer externalSignatureContainer) throws IOException, GeneralSecurityException
      Signs a PDF where space was already reserved.
      Parameters:
      document - the original PDF
      fieldName - the field to sign. It must be the last field
      outs - the output PDF
      externalSignatureContainer - the signature container doing the actual signing. Only the method ExternalSignatureContainer.sign is used
      Throws:
      IOException - if some I/O problem occurs
      GeneralSecurityException - if some problem during apply security algorithms occurs

    • processCrl

      protected Collection processCrl (Certificate cert, Collection<ICrlClient> crlList) throws CertificateEncodingException
      Processes a CRL list.
      Parameters:
      cert - a Certificate if one of the CrlList implementations needs to retrieve the CRL URL from it.
      crlList - a list of CrlClient implementations
      Returns:
      a collection of CRL bytes that can be embedded in a PDF
      Throws:
      CertificateEncodingException - if an encoding error occurs in Certificate.

    • addDeveloperExtension

      protected void addDeveloperExtension (PdfDeveloperExtension extension)
      Add developer extension to the current PdfDocument.
      Parameters:
      extension - PdfDeveloperExtension to be added

    • isPreClosed

      protected boolean isPreClosed()
      Checks if the document is in the process of closing.
      Returns:
      true if the document is in the process of closing, false otherwise

    • preClose

      protected void preClose (Map<PdfName,Integer> exclusionSizes) throws IOException
      This is the first method to be called when using external signatures. The general sequence is: preClose(), getDocumentBytes() and close().

      exclusionSizes must contain at least the PdfName.CONTENTS key with the size that it will take in the document. Note that due to the hex string coding this size should be byte_size*2+2.

      Parameters:
      exclusionSizes - Map with names and sizes to be excluded in the signature calculation. The key is a PdfName and the value an Integer. At least the /Contents must be present
      Throws:
      IOException - on error

    • populateExistingSignatureFormField

      protected PdfSigFieldLock populateExistingSignatureFormField (PdfAcroForm acroForm) throws IOException
      Populates already existing signature form field in the acroForm object. This method is called during the preClose(Map) method if the signature field already exists.
      Parameters:
      acroForm - PdfAcroForm object in which the signature field will be populated
      Returns:
      signature field lock dictionary
      Throws:
      IOException - if font for the appearance dictionary cannot be created

    • createNewSignatureFormField

      protected PdfSigFieldLock createNewSignatureFormField (PdfAcroForm acroForm, String name) throws IOException
      Creates new signature form field and adds it to the acroForm object. This method is called during the preClose(Map) method if the signature field doesn't exist.
      Parameters:
      acroForm - PdfAcroForm object in which new signature field will be added
      name - the name of the field
      Returns:
      signature field lock dictionary
      Throws:
      IOException - if font for the appearance dictionary cannot be created

    • getRangeStream

      protected InputStream getRangeStream() throws IOException
      Gets the document bytes that are hashable when using external signatures. The general sequence is: preClose(Map), getRangeStream() and close(PdfDictionary).
      Returns:
      The InputStream of bytes to be signed.
      Throws:
      IOException - if some I/O problem occurs

    • close

      protected void close (PdfDictionary update) throws IOException
      This is the last method to be called when using external signatures. The general sequence is: preClose(), getDocumentBytes() and close().

      update is a PdfDictionary that must have exactly the same keys as the ones provided in preClose(Map).

      Parameters:
      update - a PdfDictionary with the key/value that will fill the holes defined in preClose(Map)
      Throws:
      IOException - on error

    • getUnderlyingSource

      protected IRandomAccessSource getUnderlyingSource() throws IOException
      Returns the underlying source.
      Returns:
      the underlying source
      Throws:
      IOException - if some I/O problem occurs

    • addDocMDP

      protected void addDocMDP (PdfSignature crypto)
      Adds keys to the signature dictionary that define the certification level and the permissions. This method is only used for Certifying signatures.
      Parameters:
      crypto - the signature dictionary

    • addFieldMDP

      protected void addFieldMDP (PdfSignature crypto, PdfSigFieldLock fieldLock)
      Adds keys to the signature dictionary that define the field permissions. This method is only used for signatures that lock fields.
      Parameters:
      crypto - the signature dictionary
      fieldLock - the PdfSigFieldLock instance specified the field lock to be set

    • documentContainsCertificationOrApprovalSignatures

      protected boolean documentContainsCertificationOrApprovalSignatures()
      Check if current document instance already contains certification or approval signatures.
      Returns:
      true if document contains certification or approval signatures, false otherwise

    • getWidgetRectangle

      protected Rectangle getWidgetRectangle (PdfWidgetAnnotation widget)
      Get the rectangle associated to the provided widget.
      Parameters:
      widget - PdfWidgetAnnotation to extract the rectangle from
      Returns:
      Rectangle

    • getWidgetPageNumber

      protected int getWidgetPageNumber (PdfWidgetAnnotation widget)
      Get the page number associated to the provided widget.
      Parameters:
      widget - PdfWidgetAnnotation from which to extract the page number
      Returns:
      page number