PdfSignatureField Class

Namespace:
GemBox.Pdf.Forms
Assembly:
GemBox.Pdf.dll

Represents a signature field (PDF 1.3) which is a form field that contains a digital signature (see 12.8, "Digital Signatures").

public sealed class PdfSignatureField : PdfField
Public NotInheritable Class PdfSignatureField
    Inherits PdfField
Inheritance:
System.Object
PdfSignatureField

Properties

Appearance

Gets the appearance settings for this PdfSignatureField.

public PdfSignatureAppearance Appearance { get; }
Public ReadOnly Property Appearance As PdfSignatureAppearance
Property Value
PdfSignatureAppearance

The appearance settings for this PdfSignatureField.

FieldType

Gets the Signature value.

public override PdfFieldType FieldType { get; }
Public Overrides ReadOnly Property FieldType As PdfFieldType
Property Value
PdfFieldType

The Signature value.

Overrides

LockedFields

Gets or sets the set of form fields whose change invalidate the signature.

public PdfSignatureLockedFieldCollection LockedFields { get; set; }
Public Property LockedFields As PdfSignatureLockedFieldCollection
Property Value
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.InvalidOperationException

The LockedFields can be set to null only (thus removing the entry from the PdfSignatureField). To set a non-null value, use any SetLockedFields() method instead.

See Also

Required

If set, the field shall have a value at the time it is exported by a submit-form action (see 12.7.5.2, "Submit-Form Action").

public bool Required { get; set; }
Public Property Required As Boolean
Property Value
System.Boolean

If set, the field shall have a value at the time it is exported by a submit-form action.

See Also

Value

Gets or sets the PdfSignatureField value as an instance of the PdfSignature type.

Setting this property, Appearance gets automatically updated.

public PdfSignature Value { get; set; }
Public Property Value As PdfSignature
Property Value
PdfSignature

The PdfSignatureField value as an instance of the PdfSignature type.

Exceptions
System.InvalidOperationException

The Value can be set to null only (thus removing the PdfSignature from the PdfSignatureField). To set a non-null value, use any Sign(PdfSigner) method instead.

Methods

SetLockedFields()

Sets the set of form fields whose change invalidate the signature to a predefined value that represents all fields in the document.

public PdfSignatureLockedFieldCollection SetLockedFields()
Public Function SetLockedFields As PdfSignatureLockedFieldCollection
Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

SetLockedFields(PdfField[])

Sets the set of form fields whose change invalidate the signature to those specified in the fields.

public PdfSignatureLockedFieldCollection SetLockedFields(params PdfField[] fields)
Public Function SetLockedFields(ParamArray fields As PdfField()) As PdfSignatureLockedFieldCollection
Parameters
fields
PdfField[]

The fields.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fields is either null or an empty sequence.

SetLockedFields(Boolean, PdfField[])

Sets the set of form fields whose change invalidate the signature to either those specified in the fields (if excluded is false) or all fields except those specified in the fields (if excluded is true).

public PdfSignatureLockedFieldCollection SetLockedFields(bool excluded, params PdfField[] fields)
Public Function SetLockedFields(excluded As Boolean, ParamArray fields As PdfField()) As PdfSignatureLockedFieldCollection
Parameters
excluded
System.Boolean

if set to true, then the set of form fields whose change invalidate the signature is set to all fields except those specified in the fields; otherwise, it is set to those specified in the fields.

fields
PdfField[]

The fields.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fields is either null or an empty sequence.

SetLockedFields(Boolean, IEnumerable<PdfField>)

Sets the set of form fields whose change invalidate the signature to either those specified in the fields (if excluded is false) or all fields except those specified in the fields (if excluded is true).

public PdfSignatureLockedFieldCollection SetLockedFields(bool excluded, IEnumerable<PdfField> fields)
Public Function SetLockedFields(excluded As Boolean, fields As IEnumerable(Of PdfField)) As PdfSignatureLockedFieldCollection
Parameters
excluded
System.Boolean

if set to true, then the set of form fields whose change invalidate the signature is set to all fields except those specified in the fields; otherwise, it is set to those specified in the fields.

fields
System.Collections.Generic.IEnumerable<PdfField>

The fields.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fields is either null or an empty sequence.

SetLockedFields(Boolean, IEnumerable<String>)

Sets the set of form fields whose change invalidate the signature to either those specified in the fieldNames (if excluded is false) or all fields except those specified in the fieldNames (if excluded is true).

public PdfSignatureLockedFieldCollection SetLockedFields(bool excluded, IEnumerable<string> fieldNames)
Public Function SetLockedFields(excluded As Boolean, fieldNames As IEnumerable(Of String)) As PdfSignatureLockedFieldCollection
Parameters
excluded
System.Boolean

if set to true, then the set of form fields whose change invalidate the signature is set to all fields except those specified in the fieldNames; otherwise, it is set to those specified in the fieldNames.

fieldNames
System.Collections.Generic.IEnumerable<System.String>

The field names.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fieldNames is either null or an empty sequence.

SetLockedFields(Boolean, String[])

Sets the set of form fields whose change invalidate the signature to either those specified in the fieldNames (if excluded is false) or all fields except those specified in the fieldNames (if excluded is true).

public PdfSignatureLockedFieldCollection SetLockedFields(bool excluded, params string[] fieldNames)
Public Function SetLockedFields(excluded As Boolean, ParamArray fieldNames As String()) As PdfSignatureLockedFieldCollection
Parameters
excluded
System.Boolean

if set to true, then the set of form fields whose change invalidate the signature is set to all fields except those specified in the fieldNames; otherwise, it is set to those specified in the fieldNames.

fieldNames
System.String[]

The field names.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fieldNames is either null or an empty sequence.

SetLockedFields(IEnumerable<PdfField>)

Sets the set of form fields whose change invalidate the signature to those specified in the fields.

public PdfSignatureLockedFieldCollection SetLockedFields(IEnumerable<PdfField> fields)
Public Function SetLockedFields(fields As IEnumerable(Of PdfField)) As PdfSignatureLockedFieldCollection
Parameters
fields
System.Collections.Generic.IEnumerable<PdfField>

The fields.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fields is either null or an empty sequence.

SetLockedFields(IEnumerable<String>)

Sets the set of form fields whose change invalidate the signature to those specified in the fieldNames.

public PdfSignatureLockedFieldCollection SetLockedFields(IEnumerable<string> fieldNames)
Public Function SetLockedFields(fieldNames As IEnumerable(Of String)) As PdfSignatureLockedFieldCollection
Parameters
fieldNames
System.Collections.Generic.IEnumerable<System.String>

The field names.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fieldNames is either null or an empty sequence.

SetLockedFields(String[])

Sets the set of form fields whose change invalidate the signature to those specified in the fieldNames.

public PdfSignatureLockedFieldCollection SetLockedFields(params string[] fieldNames)
Public Function SetLockedFields(ParamArray fieldNames As String()) As PdfSignatureLockedFieldCollection
Parameters
fieldNames
System.String[]

The field names.

Returns
PdfSignatureLockedFieldCollection

The set of form fields whose change invalidate the signature.

Exceptions
System.ArgumentNullException

The parameter fieldNames is either null or an empty sequence.

Sign(PdfSigner)

Initiate signing of a PDF file using the specified PdfSigner that does the actual signing in a format specified by SignatureFormat.

The length of the signature returned by the signer must be less than EstimatedSignatureContentsLength.

The name of the preferred signature handler to use when validating the signature (Filter entry) is Adobe.PPKLite, the Format of the returned PdfSignature instance is SignatureFormat and the ContentsLength is EstimatedSignatureContentsLength bytes.

To finish the signing, call any of the Save(). Next signing cannot be initiated before the current one is not finished.

The returned PdfSignature is set to the Value thus automatically updating the Appearance.

note

If the Value is not null, then the method re-signs the PDF file directly and the Save() should not be called. This behavior enables delay-sign and re-sign scenarios.

public PdfSignature Sign(PdfSigner signer)
Public Function Sign(signer As PdfSigner) As PdfSignature
Parameters
signer
PdfSigner

The signer whose ComputeSignature(Stream) method is called when saving the PDF file that takes the PDF file stream (without Content entry) as an input and returns the signature that will be set as the value of the Content entry.

Returns
PdfSignature

A PdfSignature instance that contains signature properties (the Date, the Name, the Reason, the Location); key information (the signing certificate used to verify the signature value and, optionally, other certificates used to verify the authenticity of the signing certificate); reference (describes the exact byte range for the digest calculation); and signature value (usually a DER-encoded PKCS#7 binary data object that conforms to RFC 5652 Cryptographic Message Syntax).

Exceptions
System.ArgumentNullException

signer is null.

System.InvalidOperationException

This PdfSignatureField is not contained in the Fields of this PDF document. -or- Signing/timestamping of the PDF file has already been initiated on some PdfSignatureField in this PDF document. Finish that signing/timestamping by calling any of the Save() before initiating a new signing/timestamping on this PdfSignatureField.

Sign(Func<Stream, Byte[]>, PdfSignatureFormat, Int32)

Initiate signing of a PDF file using the specified delegate that does the actual signing in a format specified by signatureFormat.

The length of the signature returned by the signer delegate must be less than estimatedSignatureContentsLength.

The name of the preferred signature handler to use when validating the signature (Filter entry) is Adobe.PPKLite, the Format of the returned PdfSignature instance is signatureFormat and the ContentsLength is estimatedSignatureContentsLength bytes.

To finish the signing, call any of the Save(). Next signing cannot be initiated before the current one is not finished.

The returned PdfSignature is set to the Value thus automatically updating the Appearance.

note

If the Value is not null, then the method re-signs the PDF file directly and the Save() should not be called. This behavior enables delay-sign and re-sign scenarios.

public PdfSignature Sign(Func<Stream, byte[]> signer, PdfSignatureFormat signatureFormat, int estimatedSignatureContentsLength)
Public Function Sign(signer As Func(Of Stream, Byte()), signatureFormat As PdfSignatureFormat, estimatedSignatureContentsLength As Integer) As PdfSignature
Parameters
signer
System.Func<System.IO.Stream, System.Byte[]>

The signer delegate called when saving the PDF file that takes the PDF file stream (without Content entry) as an input and returns the signature that will be set as the value of the Content entry.

signatureFormat
PdfSignatureFormat

The encoding of the signature value and key information in the signature dictionary.

estimatedSignatureContentsLength
System.Int32

The estimated length of the Content entry (in bytes) that should be large enough to contain the entire data returned by the signer delegate.

Returns
PdfSignature

A PdfSignature instance that contains signature properties (the Date, the Name, the Reason, the Location); key information (the signing certificate used to verify the signature value and, optionally, other certificates used to verify the authenticity of the signing certificate); reference (describes the exact byte range for the digest calculation); and signature value (usually a DER-encoded PKCS#7 binary data object that conforms to RFC 5652 Cryptographic Message Syntax).

Exceptions
System.ArgumentNullException

signer is null.

System.InvalidOperationException

This PdfSignatureField is not contained in the Fields of this PDF document. -or- Signing/timestamping of the PDF file has already been initiated on some PdfSignatureField in this PDF document. Finish that signing/timestamping by calling any of the Save() before initiating a new signing/timestamping on this PdfSignatureField.

Sign(Object)

Initiate signing of a PDF file with a digital ID from the specified source.

The digital ID source is either an instance of a System.Security.Cryptography.X509Certificates.X509Certificate2 with a private key or an instance of a System.Security.Cryptography.CspParameters.

The name of the preferred signature handler to use when validating the signature (Filter entry) is Adobe.PPKLite, the Format of the returned PdfSignature instance is PKCS7 and the ContentsLength is set to the internally estimated size.

To finish the signing, call any of the Save(). Next signing cannot be initiated before the current one is not finished.

The returned PdfSignature is set to the Value thus automatically updating the Appearance.

If your project doesn't target Windows platform, to use this method, make sure your project references NuGet package System.Security.Cryptography.Pkcs.

note

If the Value is not null, then the method re-signs the PDF file directly and the Save() should not be called. This behavior enables delay-sign and re-sign scenarios.

public PdfSignature Sign(object digitalIdSource)
Public Function Sign(digitalIdSource As Object) As PdfSignature
Parameters
digitalIdSource
System.Object

The digital ID source that is either an instance of a System.Security.Cryptography.X509Certificates.X509Certificate2 with a private key or an instance of a System.Security.Cryptography.CspParameters.

Returns
PdfSignature

A PdfSignature instance that contains signature properties (the Date, the Name, the Reason, the Location); key information (the signing certificate used to verify the signature value and, optionally, other certificates used to verify the authenticity of the signing certificate); reference (describes the exact byte range for the digest calculation); and signature value (usually a DER-encoded PKCS#7 binary data object that conforms to RFC 5652 Cryptographic Message Syntax).

Exceptions
System.ArgumentException

The digitalIdSource parameter is not an instance of a System.Security.Cryptography.X509Certificates.X509Certificate2 or a System.Security.Cryptography.CspParameters.

System.InvalidOperationException

This PdfSignatureField is not contained in the Fields of this PDF document. -or- Signing/timestamping of the PDF file has already been initiated on some PdfSignatureField in this PDF document. Finish that signing/timestamping by calling any of the Save() before initiating a new signing/timestamping on this PdfSignatureField.

Sign(String, String)

Initiate signing of a PDF file with a digital ID available as a file with the specified file name and the password protecting the private key.

The most common format for such files is a PKCS#12 file, which uses .pfx or .p12 file extension and is a password protected storage container for digital IDs containing the public key (Certificate) and the associated private key.

The name of the preferred signature handler to use when validating the signature (Filter entry) is Adobe.PPKLite, the Format of the returned PdfSignature instance is PKCS7 and the ContentsLength is set to the internally estimated size.

To finish the signing, call any of the Save(). Next signing cannot be initiated before the current one is not finished.

The returned PdfSignature is set to the Value thus automatically updating the Appearance.

If your project doesn't target Windows platform, to use this method, make sure your project references NuGet package System.Security.Cryptography.Pkcs.

note

If the Value is not null, then the method re-signs the PDF file directly and the Save() should not be called. This behavior enables delay-sign and re-sign scenarios.

public PdfSignature Sign(string digitalIdFileName, string digitalIdPassword)
Public Function Sign(digitalIdFileName As String, digitalIdPassword As String) As PdfSignature
Parameters
digitalIdFileName
System.String

The name of a digital ID file that contains the public key (Certificate) and the associated private key.

digitalIdPassword
System.String

The password protecting the private key.

Returns
PdfSignature

A PdfSignature instance that contains signature properties (the Date, the Name, the Reason, the Location); key information (the signing certificate used to verify the signature value and, optionally, other certificates used to verify the authenticity of the signing certificate); reference (describes the exact byte range for the digest calculation); and signature value (usually a DER-encoded PKCS#7 binary data object that conforms to RFC 5652 Cryptographic Message Syntax).

Exceptions
System.InvalidOperationException

This PdfSignatureField is not contained in the Fields of this PDF document. -or- Signing/timestamping of the PDF file has already been initiated on some PdfSignatureField in this PDF document. Finish that signing/timestamping by calling any of the Save() before initiating a new signing/timestamping on this PdfSignatureField.

Timestamp(PdfTimestamper)

Initiate timestamping of a PDF file using the specified PdfTimestamper that does the actual timestamping.

The length of the timestamp token returned by the timestamper must be less than GemBox.Pdf.Security.PdfTimestamper.EstimatedTimestampTokenLength.

The name of the preferred signature handler to use when validating the signature (Filter entry) is Adobe.PPKLite, the Format of the returned PdfSignature instance is RFC3161 and the ContentsLength is GemBox.Pdf.Security.PdfTimestamper.EstimatedTimestampTokenLength bytes.

To finish the timestamping, call any of the Save(). Next signing or timestamping cannot be initiated before the current one is not finished.

public PdfSignature Timestamp(PdfTimestamper timestamper)
Public Function Timestamp(timestamper As PdfTimestamper) As PdfSignature
Parameters
timestamper
PdfTimestamper

The timestamper whose GemBox.Pdf.Security.PdfTimestamper.GetTimestampToken(System.IO.Stream) method is called when saving the PDF file that takes the PDF file stream (without Content entry) as an input and returns the timestamp token that will be set as the value of the Content entry.

Returns
PdfSignature

A PdfSignature instance that will contain TimeStampToken as specified in RFC 3161 as updated by RFC 5816. The value of the messageImprint field within the TimeStampToken shall be a hash of the bytes of the document indicated by the ByteRange and the ByteRange shall specify the complete PDF file contents (excepting the Content value).

Exceptions
System.ArgumentNullException

timestamper is null.

System.InvalidOperationException

This PdfSignatureField is not contained in the Fields of this PDF document. -or- Signing/timestamping of the PDF file has already been initiated on some PdfSignatureField in this PDF document. Finish that signing/timestamping by calling any of the Save() before initiating a new signing/timestamping on this PdfSignatureField.

Inherited Properties

Actions

(Optional; PDF 1.1) An action that shall be performed when the field's annotation is activated (see 12.6, "Actions").

(Inherited from PdfField)

AnnotationType

Gets the Widget value.

(Inherited from PdfField)

AssociatedFiles

(Optional; PDF 2.0) An array of one or more PdfFileSpecifications which denote the associated files for this PdfAnnotation.

(Inherited from PdfAnnotation)

Bounds

(Required) The annotation bounds, defining the location and the size of the annotation on the page in default user space units.

(Inherited from PdfAnnotation)

DefaultValue

(Optional; inheritable) The default value to which the field reverts when a reset-form action is executed. The format of this value is the same as that of Value.

(Inherited from PdfField)

Hidden

(PDF 1.2) If set, do not display the annotation on the screen or allow it to interact with the user.

The annotation may be printed (depending on the setting of the Print flag) but should be considered hidden for purposes of on-screen display and user interaction.

(Inherited from PdfField)

Locked

(PDF 1.4) If set, do not allow the annotation to be deleted or its properties (including position and size) to be modified by the user. However, this flag does not restrict changes to the annotation's contents, such as the value of a form field.

(Inherited from PdfAnnotation)

Metadata

(Optional; PDF 1.4) A metadata stream containing metadata for the component.

(Inherited from PdfObject)

Name

Gets the (fully qualified) field name.

(Inherited from PdfField)

Page

Gets the page with which this annotation is associated.

(Inherited from PdfAnnotation)

Print

(PDF 1.2) If set, print the annotation when the page is printed. If clear, never print the annotation, regardless of whether it is displayed on the screen.

note

This can be useful for annotations representing interactive pushbuttons, which would serve no meaningful purpose on the printed page.

(Inherited from PdfField)

ReadOnly

If set, the user may not change the value of the field. Any associated widget annotations will not interact with the user; that is, they will not respond to mouse clicks or change their appearance in response to mouse motions. This flag is useful for fields whose values are computed or imported from a database.

(Inherited from PdfField)

Tooltip

(Optional; PDF 1.3) An alternate field name that shall be used in place of the actual field name wherever the field shall be identified in the user interface (such as in error or status messages referring to the field). This text is also useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, "Alternate Descriptions").

(Inherited from PdfField)

Inherited Methods

SetBounds(System.Double, System.Double)

Sets the size of the Bounds.

(Inherited from PdfAnnotation)

SetBounds(System.Double, System.Double, System.Double, System.Double)

Sets the Bounds.

(Inherited from PdfAnnotation)

ToString()

Returns a System.String that represents this PdfField instance.

(Inherited from PdfField)

Extension Methods

Examples