PdfSigner (iText 7 7.0.6 API)

java.lang.Object
- com.itextpdf.signatures.PdfSigner

```
public class PdfSigner
extends Object
```
Takes care of the cryptographic options and appearances that form a signature.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`PdfSigner.CryptoStandard` Enum containing the Cryptographic Standards.
`static interface`	`PdfSigner.ISignatureEvent` An interface to retrieve the signature dictionary for modification.

Field Summary

Fields
Modifier and Type	Field and Description
`protected PdfSignatureAppearance`	`appearance` The signature appearance.
`protected byte[]`	`bout` The bytes of the file right before the signature is added (if raf is null).
`protected int`	`certificationLevel` The certification level.
`static int`	`CERTIFIED_FORM_FILLING` Author signature, form filling allowed.
`static int`	`CERTIFIED_FORM_FILLING_AND_ANNOTATIONS` Author signature, form filling and annotations allowed.
`static int`	`CERTIFIED_NO_CHANGES_ALLOWED` Author signature, no changes allowed.
`protected boolean`	`closed` Boolean to check if this PdfSigner instance has been closed already or not.
`protected PdfSignature`	`cryptoDictionary` The crypto dictionary.
`protected PdfDocument`	`document` The PdfDocument.
`protected Map<PdfName,PdfLiteral>`	`exclusionLocations` Name and content of keys that can only be added in the close() method.
`protected PdfSigFieldLockDictionary`	`fieldLock` Signature field lock dictionary.
`protected String`	`fieldName` The name of the field.
`static int`	`NOT_CERTIFIED` Approval signature.
`protected OutputStream`	`originalOS` OutputStream for the bytes of the document.
`protected boolean`	`preClosed` Indicates if the pdf document has already been pre-closed.
`protected RandomAccessFile`	`raf` The file right before the signature is added (can be null).
`protected long[]`	`range` Array containing the byte positions of the bytes that need to be hashed.
`protected PdfSigner.ISignatureEvent`	`signatureEvent` Holds value of property signatureEvent.
`protected Calendar`	`signDate` Holds value of property signDate.
`protected File`	`tempFile` Tempfile to hold the output temporarily.
`protected ByteArrayOutputStream`	`temporaryOS` Outputstream that temporarily holds the output in memory.

Constructor Summary

Constructors
Constructor and Description
`PdfSigner(PdfReader reader, OutputStream outputStream, boolean append)` Creates a PdfSigner instance.
`PdfSigner(PdfReader reader, OutputStream outputStream, String path, boolean append)` Creates a PdfSigner instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`addDeveloperExtension(PdfDeveloperExtension extension)`
`protected void`	`addDocMDP(PdfSignature crypto)` Adds keys to the signature dictionary that define the certification level and the permissions.
`protected void`	`addFieldMDP(PdfSignature crypto, PdfSigFieldLockDictionary fieldLock)` Adds keys to the signature dictionary that define the field permissions.
`protected void`	`close(PdfDictionary update)` This is the last method to be called when using external signatures.
`int`	`getCertificationLevel()` Returns the document's certification level.
`PdfDocument`	`getDocument()` Gets the PdfDocument associated with this instance.
`PdfSigFieldLockDictionary`	`getFieldLockDict()` Getter for the field lock dictionary.
`String`	`getFieldName()` Gets the field name.
`String`	`getNewSigFieldName()` Gets a new signature field name that doesn't clash with any existing name.
`protected InputStream`	`getRangeStream()` Gets the document bytes that are hashable when using external signatures.
`PdfSignatureAppearance`	`getSignatureAppearance()` Provides access to a signature appearance object.
`PdfSignature`	`getSignatureDictionary()` Returns the user made signature dictionary.
`PdfSigner.ISignatureEvent`	`getSignatureEvent()` Getter for property signatureEvent.
`Calendar`	`getSignDate()` Gets the signature date.
`protected IRandomAccessSource`	`getUnderlyingSource()` Returns the underlying source.
`protected int`	`getWidgetPageNumber(PdfWidgetAnnotation widget)` Get the page number associated to the provided widget.
`protected Rectangle`	`getWidgetRectangle(PdfWidgetAnnotation widget)` Get the rectangle associated to the provided widget.
`protected boolean`	`isPreClosed()` Checks if the document is in the process of closing.
`protected void`	`preClose(Map<PdfName,Integer> exclusionSizes)` This is the first method to be called when using external signatures.
`protected Collection`	`processCrl(Certificate cert, Collection<ICrlClient> crlList)` Processes a CRL list.
`void`	`setCertificationLevel(int certificationLevel)` Sets the document's certification level.
`protected void`	`setDocument(PdfDocument document)` Sets the PdfDocument.
`void`	`setFieldLockDict(PdfSigFieldLockDictionary fieldLock)` Setter for the field lock dictionary.
`void`	`setFieldName(String fieldName)` Sets the name indicating the field to be signed.
`void`	`setOriginalOutputStream(OutputStream originalOS)` Setter for the OutputStream.
`void`	`setSignatureEvent(PdfSigner.ISignatureEvent signatureEvent)` Sets the signature event to allow modification of the signature dictionary.
`void`	`setSignDate(Calendar signDate)` Sets the signature date.
`static void`	`signDeferred(PdfDocument document, String fieldName, OutputStream outs, IExternalSignatureContainer externalSignatureContainer)` Signs a PDF where space was already reserved.
`void`	`signDetached(IExternalDigest externalDigest, IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype)` Signs the document using the detached mode, CMS or CAdES equivalent.
`void`	`signDetached(IExternalDigest externalDigest, IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype, org.bouncycastle.asn1.esf.SignaturePolicyIdentifier signaturePolicy)` Signs the document using the detached mode, CMS or CAdES equivalent.
`void`	`signDetached(IExternalDigest externalDigest, IExternalSignature externalSignature, Certificate[] chain, Collection<ICrlClient> crlList, IOcspClient ocspClient, ITSAClient tsaClient, int estimatedSize, PdfSigner.CryptoStandard sigtype, SignaturePolicyInfo signaturePolicy)` Signs the document using the detached mode, CMS or CAdES equivalent.
`void`	`signExternalContainer(IExternalSignatureContainer externalSignatureContainer, int estimatedSize)` Sign the document using an external container, usually a PKCS7.
`void`	`timestamp(ITSAClient tsa, String signatureName)` Signs a document with a PAdES-LTV Timestamp.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NOT_CERTIFIED
```
public static final int NOT_CERTIFIED
```
    Approval signature.
    
    See Also:
    
    Constant Field Values
  - CERTIFIED_NO_CHANGES_ALLOWED
```
public static final int CERTIFIED_NO_CHANGES_ALLOWED
```
    Author signature, no changes allowed.
    
    See Also:
    
    Constant Field Values
  - CERTIFIED_FORM_FILLING
```
public static final int CERTIFIED_FORM_FILLING
```
    Author signature, form filling allowed.
    
    See Also:
    
    Constant Field Values
  - CERTIFIED_FORM_FILLING_AND_ANNOTATIONS
```
public static final int CERTIFIED_FORM_FILLING_AND_ANNOTATIONS
```
    Author signature, form filling and annotations allowed.
    
    See Also:
    
    Constant Field Values
  - 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 PdfSigFieldLockDictionary 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 Detail
  - PdfSigner
```
public PdfSigner(PdfReader reader,
                 OutputStream outputStream,
                 boolean append)
          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
    
    append - boolean to indicate whether the signing should happen in append mode or not
    
    Throws:
    
    IOException
  - PdfSigner
```
public PdfSigner(PdfReader reader,
                 OutputStream outputStream,
                 String path,
                 boolean append)
          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
    
    append - boolean to indicate whether the signing should happen in append mode or not
    
    Throws:
    
    IOException
- Method Detail
  - 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
```
public PdfSignatureAppearance getSignatureAppearance()
```
    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.
  - 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.
    Parameters:
    certificationLevel - a new certification level for a document. Possible values are:
    
    NOT_CERTIFIED
    
    CERTIFIED_NO_CHANGES_ALLOWED
    
    CERTIFIED_FORM_FILLING
    
    CERTIFIED_FORM_FILLING_AND_ANNOTATIONS
  - 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.
  - setOriginalOutputStream
```
public void setOriginalOutputStream(OutputStream originalOS)
```
    Setter for the OutputStream.
  - getFieldLockDict
```
public PdfSigFieldLockDictionary getFieldLockDict()
```
    Getter for the field lock dictionary.
    
    Returns:
    
    Field lock dictionary.
  - setFieldLockDict
```
public void setFieldLockDict(PdfSigFieldLockDictionary 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
  - 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
    
    GeneralSecurityException
  - 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
    
    GeneralSecurityException
  - signDetached
```
public void signDetached(IExternalDigest externalDigest,
                         IExternalSignature externalSignature,
                         Certificate[] chain,
                         Collection<ICrlClient> crlList,
                         IOcspClient ocspClient,
                         ITSAClient tsaClient,
                         int estimatedSize,
                         PdfSigner.CryptoStandard sigtype,
                         org.bouncycastle.asn1.esf.SignaturePolicyIdentifier 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
    
    GeneralSecurityException
  - 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
    
    IOException
  - 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
    
    GeneralSecurityException
  - 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
    
    GeneralSecurityException
  - processCrl
```
protected Collection processCrl(Certificate cert,
                                        Collection<ICrlClient> crlList)
```
    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
  - addDeveloperExtension
```
protected void addDeveloperExtension(PdfDeveloperExtension extension)
```
  - 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
  - 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
  - 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
  - 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,
                           PdfSigFieldLockDictionary 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
  - 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

Class PdfSigner

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NOT_CERTIFIED

CERTIFIED_NO_CHANGES_ALLOWED

CERTIFIED_FORM_FILLING

CERTIFIED_FORM_FILLING_AND_ANNOTATIONS

certificationLevel

fieldName

raf

bout

range

document

cryptoDictionary

signatureEvent

originalOS

temporaryOS

tempFile

exclusionLocations

preClosed

fieldLock

appearance

signDate

closed

Constructor Detail

PdfSigner

PdfSigner

Method Detail

getSignDate

setSignDate

getSignatureAppearance

getCertificationLevel

setCertificationLevel

getFieldName

getSignatureDictionary

getSignatureEvent

setSignatureEvent

getNewSigFieldName

setFieldName

getDocument

setDocument

setOriginalOutputStream

getFieldLockDict

setFieldLockDict

signDetached

signDetached

signDetached

signExternalContainer

timestamp

signDeferred

processCrl

addDeveloperExtension

isPreClosed

preClose

getRangeStream

close

getUnderlyingSource

addDocMDP

addFieldMDP

getWidgetRectangle

getWidgetPageNumber