PdfSigner Class

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

Represents a signer that computes the Content in a format specified by SignatureFormat.

public class PdfSigner
Public Class PdfSigner
Inheritance:
System.Object
PdfSigner

Constructors

PdfSigner(PdfDigitalId)

Initializes a new instance of the PdfSigner class with the specified digital ID.

public PdfSigner(PdfDigitalId id)
Public Sub New(id As PdfDigitalId)
Parameters
id
PdfDigitalId

The digital ID used to sign documents. The certificate that comes with your digital ID is sent to others so that they can verify your signature.

Exceptions
System.ArgumentNullException

id is null.

System.ArgumentException

The Certificate of the id is null.

PdfSigner(Object)

Initializes a new instance of the PdfSigner class 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.

public PdfSigner(object digitalIdSource)
Public Sub New(digitalIdSource As Object)
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.

Exceptions
System.ArgumentException

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

PdfSigner(String, String)

Initializes a new instance of the PdfSigner class 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.

public PdfSigner(string digitalIdFileName, string digitalIdPassword)
Public Sub New(digitalIdFileName As String, digitalIdPassword As String)
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.

Properties

ApplicationName

(Optional; PDF 1.5) The name of the software module used to create the signature. When used as an entry in the data dictionary of the Filter attribute (Table 2.1), the value is the name of the signature handler. The value is normally equal to the value of the Filter attribute in the signature dictionary.

Default value: Title.

public string ApplicationName { get; set; }
Public Property ApplicationName As String
Property Value
System.String

The name of the software module used to create the signature.

Remarks

ApplicationName is shown in 'Acrobat Reader' when 'Advanced Properties...' button in 'Signature Properties' dialog window is clicked.

See Also

ApplicationVersion

(Optional; PDF 1.6) A text string indicating the version of the application implementation, as described by the Name attribute in this dictionary. When set by Adobe Acrobat, this entry is in the format: major.minor.micro (for example 7.0.7).

Default value: Version.

public string ApplicationVersion { get; set; }
Public Property ApplicationVersion As String
Property Value
System.String

A text string indicating the version of the application implementation, as described by the Name attribute in this dictionary.

Remarks

ApplicationVersion is shown in 'Acrobat Reader' when 'Advanced Properties...' button in 'Signature Properties' dialog window is clicked.

See Also

AuthorPermission

Gets or sets the permitted actions after certifying the document with this PdfSigner.

If set to a null value, then the signature created by this PdfSigner is a regular, approval signature (also known as a recipient signature).

Otherwise, the signature created by this PdfSigner is a certification signature (also known as an author signature) (PDF 1.5). A document can contain only one signature field that contains a certification signature; it shall be the first signed field in the document. It enables the author to specify what changes shall be permitted to be made to the document and what changes invalidate the author's signature. The AuthorPermission in any of the Locks shall indicate the author's specification of which changes to the document will invalidate the signature. These changes to the document shall also be prevented if the PdfSignature is referred from the AuthorSignature property. A value of None indicates that the document shall be final; that is, any changes shall invalidate the signature. The values FillForm and CommentAndFillForm shall permit modifications that are appropriate for form field or comment workflows. Setting the value to any other PdfUserAccessPermissions is not supported and throws System.NotSupportedException.

Default value: null.

public PdfUserAccessPermissions? AuthorPermission { get; set; }
Public Property AuthorPermission As PdfUserAccessPermissions?
Property Value
System.Nullable<PdfUserAccessPermissions>

The permitted actions after certifying the document with this PdfSigner.

Exceptions
System.NotSupportedException
See Also

ContactInfo

Gets or sets the information provided by the signer to enable a recipient to contact the signer to verify the signature.

Default value: null.

public string ContactInfo { get; set; }
Public Property ContactInfo As String
Property Value
System.String

The information provided by the signer to enable a recipient to contact the signer to verify the signature.

Date

Gets or sets the time of signing.

The Date must be specified if SignatureLevel is set to PAdES_B_B or higher.

Default value: System.DateTimeOffset.Now.

public DateTimeOffset? Date { get; set; }
Public Property Date As DateTimeOffset?
Property Value
System.Nullable<System.DateTimeOffset>

The time of signing.

Exceptions
System.InvalidOperationException

Value is null and SignatureLevel is PAdES_B_B or higher.

DistinguishedName

Gets or sets the distinguished name of the person or authority signing the document.

Default value: System.String.Empty so that distinguished name is not automatically added to the signature's appearance. If set to null, default value is Subject distinguished name of a certificate associated with Id.

public string DistinguishedName { get; set; }
Public Property DistinguishedName As String
Property Value
System.String

The distinguished name of the person or authority signing the document.

EstimatedSignatureContentsLength

Gets the estimated length of the Content entry (in bytes) that should be large enough to contain the entire data returned by the ComputeSignature(Stream) method.

note

This property supports the GemBox product infrastructure and is not intended to be used directly from your code.

public virtual int EstimatedSignatureContentsLength { get; }
Public Overridable ReadOnly Property EstimatedSignatureContentsLength As Integer
Property Value
System.Int32

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

HashAlgorithm

Gets or sets the hash algorithm that hashes the bytes of the document indicated by the ByteRange and the ByteRange shall specify the complete PDF file contents (excepting the Content value).

Default value: SHA256.

public PdfHashAlgorithm HashAlgorithm { get; set; }
Public Property HashAlgorithm As PdfHashAlgorithm
Property Value
PdfHashAlgorithm

The hash algorithm that hashes the bytes of the document indicated by the ByteRange.

Exceptions
System.ArgumentException

The specified hash algorithm value is not supported for creating a digital signature or signer's certificate has a 'DSA' public key and the specified value is not GemBox.Pdf.Security.PdfHashAlgorithm.SHA1.

Id

Gets the digital ID used to sign documents. The certificate that comes with your digital ID is sent to others so that they can verify your signature.

public PdfDigitalId Id { get; }
Public ReadOnly Property Id As PdfDigitalId
Property Value
PdfDigitalId

The digital ID used to sign documents.

Location

Gets or sets the CPU host name or physical location of the signing.

Default value: null.

public string Location { get; set; }
Public Property Location As String
Property Value
System.String

The CPU host name or physical location of the signing.

Name

Gets or sets the name of the person or authority signing the document.

Default value: SubjectCommonName of a certificate associated with Id.

public string Name { get; set; }
Public Property Name As String
Property Value
System.String

The name of the person or authority signing the document.

Reason

Gets or sets the reason for the signing.

The Reason and SignaturePolicyIdentifier cannot both be specified if SignatureLevel is set to PAdES_B_B or higher.

Default value: null.

public string Reason { get; set; }
Public Property Reason As String
Property Value
System.String

The reason for the signing.

Exceptions
System.InvalidOperationException

Value cannot be set if SignaturePolicyIdentifier is specified and SignatureLevel is PAdES_B_B or higher.

RSASignaturePadding

Gets or sets the RSA signature padding to use if signer's certificate has an 'RSA' public key.

Default value: null. If signer's certificate has an 'RSA' public key, Pkcs1 is used.

public PdfRSASignaturePadding RSASignaturePadding { get; set; }
Public Property RSASignaturePadding As PdfRSASignaturePadding
Property Value
PdfRSASignaturePadding

The RSA signature padding to use if signer's certificate has an 'RSA' public key.

Exceptions
System.ArgumentException

Signer's certificate doesn't have an 'RSA' public key so RSA signature padding must be null or signature format is GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1 so RSA signature padding must be Pkcs1.

SignatureFormat

Gets or sets the format of the Content that this signer produces.

The SignatureFormat must be CAdES if SignatureLevel is set to PAdES_B_B or higher.

Default value: PKCS7.

public PdfSignatureFormat SignatureFormat { get; set; }
Public Property SignatureFormat As PdfSignatureFormat
Property Value
PdfSignatureFormat

The format of the Content that this signer produces.

Exceptions
System.InvalidOperationException

Value must be GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1, PKCS7, GemBox.Pdf.Forms.PdfSignatureFormat.PKCS7_SHA1 or CAdES (required if SignatureLevel is PAdES_B_B or higher). Values GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1 and GemBox.Pdf.Forms.PdfSignatureFormat.PKCS7_SHA1 are deprecated. Instead of value RFC3161, method Timestamp(PdfTimestamper) should be used.

System.ArgumentException

Signer's certificate doesn't have an 'RSA' public key so value cannot be GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1.

SignatureLevel

Gets or sets the level of the PDF Advanced Electronic Signature (PAdES) that signature created by this signer must satisfy.

Default value: None.

If SignatureLevel is set to:

  • PAdES_B_B or higher, then SignatureFormat must be CAdES, Date must be specified, SignaturePolicyIdentifier and Reason cannot both be specified and ValidationInfo, if specified, cannot contain any CRL or OCSP response (because this information is added to the signature as 'adbe-revocationInfoArchival' signed attribute which PAdES_B_B or higher doesn't allow).
  • PAdES_B_T or higher, then Timestamper must be specified.
  • PAdES_B_LT or higher, then check that validation data is added to the security store is not performed since that can be done only after signing finishes.
  • PAdES_B_LTA or higher, then check that validation data is added to the security store and that validation data is protected by document timestamp is not performed since that can be done only after signing finishes.
public PdfSignatureLevel SignatureLevel { get; set; }
Public Property SignatureLevel As PdfSignatureLevel
Property Value
PdfSignatureLevel

The level of the PDF Advanced Electronic Signature that signature created by this signer must satisfy.

Exceptions
System.InvalidOperationException

One of the conditions specified in the description of this member is not satisfied.

SignaturePolicyIdentifier

Gets or sets the signature policy identifier to use when creating PAdES Enhanced Explicit Policy Electronic Signature (PAdES-E-EPES and legacy PAdES-E-EPES).

The SignaturePolicyIdentifier and Reason cannot both be specified if SignatureLevel is set to PAdES_B_B or higher.

The SignaturePolicyIdentifier is ignored if SignatureFormat is set to GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1.

Default value: null.

public PdfSignaturePolicyIdentifier SignaturePolicyIdentifier { get; set; }
Public Property SignaturePolicyIdentifier As PdfSignaturePolicyIdentifier
Property Value
PdfSignaturePolicyIdentifier

The signature policy identifier.

Exceptions
System.InvalidOperationException

Value cannot be set if Reason is specified and SignatureLevel is PAdES_B_B or higher.

Timestamper

Gets or sets the timestamper used to retrieve the TimeStampToken as specified in RFC 3161 as updated by RFC 5816 for the signature field within SignerInfo for the CMS-based Content that will be added as a unsigned attribute to the SignerInfo.

The Timestamper must be specified if SignatureLevel is set to PAdES_B_T or higher.

The Timestamper is ignored if SignatureFormat is set to GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1.

Default value: null (no timestamp will be embedded in the signature).

public PdfTimestamper Timestamper { get; set; }
Public Property Timestamper As PdfTimestamper
Property Value
PdfTimestamper

The timestamper used to retrieve the TimeStampToken as specified in RFC 3161 as updated by RFC 5816 for the signature field within SignerInfo for the CMS-based Content that will be added as a unsigned attribute to the SignerInfo.

Exceptions
System.InvalidOperationException

Value is null and SignatureLevel is PAdES_B_T or higher.

UpdateDate

Gets or sets a value indicating whether to update Date, Date and Date before the PdfDocument is saved to a PDF file.

Default value: true.

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

true to update Date, Date and Date before the PdfDocument is saved to a PDF file; otherwise, false.

ValidationInfo

Gets or sets the (potentially partial) validation-related information (certificates, certificate revocation lists and Online Certificate Status Protocol responses) that should be embedded in the signature.

The ValidationInfo cannot contain any CRL or OCSP response if SignatureLevel is set to PAdES_B_B or higher.

The ValidationInfo CRLs and OCSP responses are ignored if SignatureFormat is set to GemBox.Pdf.Forms.PdfSignatureFormat.PKCS1.

Default value: null (only signing certificate will be embedded in the signature).

public PdfSignatureValidationInfo ValidationInfo { get; set; }
Public Property ValidationInfo As PdfSignatureValidationInfo
Property Value
PdfSignatureValidationInfo

The (potentially partial) validation-related information (certificates, certificate revocation lists and Online Certificate Status Protocol responses) that should be embedded in the signature.

Exceptions
System.InvalidOperationException

Value contains at least one CRL or OCSP response and SignatureLevel is PAdES_B_B or higher.

Methods

ComputeSignature(Stream)

A method 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.

note

This method supports the GemBox product infrastructure and is not intended to be used directly from your code.

public virtual byte[] ComputeSignature(Stream pdfFileStream)
Public Overridable Function ComputeSignature(pdfFileStream As Stream) As Byte()
Parameters
pdfFileStream
System.IO.Stream

The PDF file stream (without Content entry) for which the signature should be computed.

Returns
System.Byte[]

The signature that will be set as the value of the Content entry.

Examples

See Also