Show / Hide Table of Contents

# Class DigitalSignatureField

A class representing a digital signature form field.

##### Inheritance

object
DigitalSignatureField

##### Implements

IDisposable

##### Inherited Members

object.ToString()
object.Equals(object)
object.Equals(object, object)
object.ReferenceEquals(object, object)
object.GetHashCode()
object.GetType()

###### Namespace: pdftron.PDF

###### Assembly: PDFNet.dll

##### Syntax

    public sealed class DigitalSignatureField : IDisposable

### Constructors

#### DigitalSignatureField(Field)

Constructs a DigitalSignatureField from a Field.

##### Declaration

    public DigitalSignatureField(Field field)

##### Parameters

Type | Name | Description
--- | --- | ---
Field | field |

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

### Methods

#### CalculateDigest()

Calculates the digest of the relevant bytes of the document for this signature field, in order to allow the caller to perform custom signing/processing. Signature field must first be prepared using one of the non-sign overloads (CreateSigDictForCustomSigning/Certification), and then the document must be saved; after that, this function can be called. The ByteRanges that the most recent save has entered into the signature dictionary within this signature field will be used to calculate the digest. This overload uses a default algorithm -- SHA-256.

##### Declaration

    public byte[] CalculateDigest()

##### Returns

Type | Description
--- | ---
byte[] | an array of bytes containing the digest value

#### CalculateDigest(Type)

##### Declaration

    public byte[] CalculateDigest(DigestAlgorithm.Type in_digest_algorithm_type)

##### Parameters

Type | Name | Description
--- | --- | ---
DigestAlgorithm.Type | in_digest_algorithm_type |

##### Returns

Type | Description
--- | ---
byte[] |

#### CertifyOnNextSave(byte[], string)

Must be called to prepare a signature for certification, which is done afterwards by calling Save. Throws if document already certified. Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

##### Declaration

    public void CertifyOnNextSave(byte[] in_pkcs12_buffer, string in_password)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | in_pkcs12_buffer | A buffer of bytes containing the PKCS #12 private key certificate store to use to sign this digital signature.
string | in_password | The password to use to parse the PKCS #12 buffer.

#### CertifyOnNextSave(string, string)

Must be called to prepare a signature for certification, which is done afterwards by calling Save. Throws if document already certified. Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

##### Declaration

    public void CertifyOnNextSave(string in_pkcs12_keyfile_path, string in_password)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_pkcs12_keyfile_path | The path to the PKCS 12 keyfile to use to certify this digital signature.
string | in_password | The password to use to parse the PKCS 12 keyfile.

#### CertifyOnNextSaveWithCustomHandler(SignatureHandlerId)

Must be called to prepare a signature for certification, which is done afterwards by calling Save. Throws if document already certified. Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

##### Declaration

    public void CertifyOnNextSaveWithCustomHandler(SignatureHandlerId in_signature_handler_id)

##### Parameters

Type | Name | Description
--- | --- | ---
SignatureHandlerId | in_signature_handler_id | The unique id of the signature handler to use to certify this digital signature.

#### ClearSignature()

Clears cryptographic signature, if present. Otherwise, does nothing. Do not need to call HasCryptographicSignature before calling this. After clearing, other signatures should still pass validation. Clears the appearance as well.

##### Declaration

    public void ClearSignature()

#### CreateSigDictForCustomCertification(string, SubFilterType, uint)

##### Declaration

    public void CreateSigDictForCustomCertification(string in_filter_name, DigitalSignatureField.SubFilterType in_subfilter_type, uint in_contents_size_to_reserve)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_filter_name |
DigitalSignatureField.SubFilterType | in_subfilter_type |
uint | in_contents_size_to_reserve |

#### CreateSigDictForCustomSigning(string, SubFilterType, uint)

##### Declaration

    public void CreateSigDictForCustomSigning(string in_filter_name, DigitalSignatureField.SubFilterType in_subfilter_type, uint in_contents_size_to_reserve)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_filter_name |
DigitalSignatureField.SubFilterType | in_subfilter_type |
uint | in_contents_size_to_reserve |

#### Dispose()

##### Declaration

    public override sealed void Dispose()

#### Dispose(bool)

##### Declaration

    [HandleProcessCorruptedStateExceptions]
    protected void Dispose(bool A_0)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | A_0 |

#### EnableLTVOfflineVerification(VerificationResult)

Given a successful verification result that required online information to verify trust (trust verification must have been enabled and successful during the verification), embeds data into the PDF document that allows the signature to be verified offline. (This is accomplished using DSS and VRI dictionaries.) When this operation is successfully completed, one of the two components of secure long term validation (LTV) will be in place. The other necessary component of secure long term validation is to make sure to timestamp the document appropriately while the signature is still verifiable to maintain a chain of unexpired secure timestamps attesting to the integrity of the document.The verifiability of the signature should thereafter be maintainable in such a fashion despite any possible certificate expiry, algorithm compromise, or key compromise that would have otherwise rendered it invalid if it were to be verified using a time in the future rather than a securely - signed timestamp - derived time nearer the time of signing (at which which the signature was verifiable without extra data). This function, if given a good verification result, is also capable of making timestamp (DocTimeStamp ETSI.RFC3161) signatures LTV - enabled, which is necessary to do first when you intend to add another timestamp around an already - timestamped document to extend or enhance its verifiability (as described above), as per the PDF 2.0 and ETSI TS 102 778-4 (PAdES Level 4) specifications.

##### Declaration

    public bool EnableLTVOfflineVerification(VerificationResult in_verification_result)

##### Parameters

Type | Name | Description
--- | --- | ---
VerificationResult | in_verification_result | a successful verification result containing a successful TrustVerificationResult

##### Returns

Type | Description
--- | ---
bool | a boolean status that reflects whether offline verification information was added successfully

##### Remarks

It is necessary to save the document incrementally after this function completes successfully in order to actually write the LTV data into the document.

#### ~DigitalSignatureField()

Allows a DigitalSignatureField to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

##### Declaration

    protected ~DigitalSignatureField()

#### GenerateCMSSignature(X509Certificate, X509Certificate[], AlgorithmIdentifier, AlgorithmIdentifier, byte[], byte[])

##### Declaration

    public static byte[] GenerateCMSSignature(X509Certificate signer_cert, X509Certificate[] chain_certs_buf, AlgorithmIdentifier digest_algorithm_id, AlgorithmIdentifier signature_algorithm_id, byte[] signature_value, byte[] signedattributes)

##### Parameters

Type | Name | Description
--- | --- | ---
X509Certificate | signer_cert |
X509Certificate[] | chain_certs_buf |
AlgorithmIdentifier | digest_algorithm_id |
AlgorithmIdentifier | signature_algorithm_id |
byte[] | signature_value |
byte[] | signedattributes |

##### Returns

Type | Description
--- | ---
byte[] |

#### GenerateCMSSignature(X509Certificate, X509Certificate[], AlgorithmIdentifier, AlgorithmIdentifier, byte[], byte[], CMSSignatureOptions)

##### Declaration

    public static byte[] GenerateCMSSignature(X509Certificate signer_cert, X509Certificate[] chain_certs_buf, AlgorithmIdentifier digest_algorithm_id, AlgorithmIdentifier signature_algorithm_id, byte[] signature_value, byte[] signedattributes, CMSSignatureOptions cms_options)

##### Parameters

Type | Name | Description
--- | --- | ---
X509Certificate | signer_cert |
X509Certificate[] | chain_certs_buf |
AlgorithmIdentifier | digest_algorithm_id |
AlgorithmIdentifier | signature_algorithm_id |
byte[] | signature_value |
byte[] | signedattributes |
CMSSignatureOptions | cms_options |

##### Returns

Type | Description
--- | ---
byte[] |

#### GenerateCMSSignature(X509Certificate, X509Certificate[], ObjectIdentifier, ObjectIdentifier, byte[], byte[])

##### Declaration

    public static byte[] GenerateCMSSignature(X509Certificate in_signer_cert, X509Certificate[] in_chain_certs_buf, ObjectIdentifier in_digest_algorithm_oid, ObjectIdentifier in_signature_algorithm_oid, byte[] in_signature_value, byte[] in_signedattributes)

##### Parameters

Type | Name | Description
--- | --- | ---
X509Certificate | in_signer_cert |
X509Certificate[] | in_chain_certs_buf |
ObjectIdentifier | in_digest_algorithm_oid |
ObjectIdentifier | in_signature_algorithm_oid |
byte[] | in_signature_value |
byte[] | in_signedattributes |

##### Returns

Type | Description
--- | ---
byte[] |

#### GenerateCMSSignedAttributes(byte[])

Low-level function belonging to custom-signing APIs. Creates the signedAttributes component of Cryptographic Message Syntax (CMS). The result of this function can then be encrypted by a remote private key (cloud service, Hardware Security Module (HSM) device, etc.), using some external API that returns the bytes of a not-already-CMS-embedded signature value (e.g. RSA PKCS #1 v1.5 format). Following that, CMS generation can be performed using GenerateCMSSignature, after which the resulting signature can be inserted into a resulting signed version of the PDF document using the PDFDoc function SaveCustomSignature.

##### Declaration

    public static byte[] GenerateCMSSignedAttributes(byte[] in_digest)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | in_digest | a buffer containing the digest of the document within ByteRanges of this DigitalSignatureField (see CalculateDigest)

##### Returns

Type | Description
--- | ---
byte[] | the BER-encoded bytes of the future signedAttrs component of a CMS signature, with no surrounding constructed type

#### GenerateCMSSignedAttributes(byte[], byte[])

Low-level function belonging to custom-signing APIs. Creates the signedAttributes component of Cryptographic Message Syntax (CMS). The result of this function can then be encrypted by a remote private key (cloud service, Hardware Security Module (HSM) device, etc.), using some external API that returns the bytes of a not-already-CMS-embedded signature value (e.g. RSA PKCS #1 v1.5 format). Following that, CMS generation can be performed using GenerateCMSSignature, after which the resulting signature can be inserted into a resulting signed version of the PDF document using the PDFDoc function SaveCustomSignature.

##### Declaration

    public static byte[] GenerateCMSSignedAttributes(byte[] in_digest, byte[] in_custom_signedattributes)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | in_digest | a buffer containing the digest of the document within ByteRanges of this DigitalSignatureField (see CalculateDigest)
byte[] | in_custom_signedattributes | containing any optional custom BER-encoded signedAttributes to add, including potentially the PAdES one (see GenerateESSSigningCertPAdESAttribute). (Do not place an ASN.1 constructed type around all of the attributes.) Do not pass any of the normal attributes (content type or message digest) as custom attributes because otherwise they will be duplicated.

##### Returns

Type | Description
--- | ---
byte[] | the BER-encoded bytes of the future signedAttrs component of a CMS signature, with no surrounding constructed type

#### GenerateContentsWithEmbeddedTimestamp(TimestampingConfiguration, VerificationOptions)

##### Declaration

    public TimestampingResult GenerateContentsWithEmbeddedTimestamp(TimestampingConfiguration in_timestamping_config, VerificationOptions in_timestamp_response_verification_options)

##### Parameters

Type | Name | Description
--- | --- | ---
TimestampingConfiguration | in_timestamping_config | Configuration options to store for timestamping. These will include various items related to contacting a timestamping authority. Incorrect configuration will result in an exception being thrown. The usability of a combination of a TimestampingConfiguration and VerificationOptions can be checked ahead of time to prevent exceptions by calling TestConfiguration on TimestampingConfiguration and passing VerificationOptions.
VerificationOptions | in_timestamp_response_verification_options | Options for the timestamp response verification step (which is required by RFC 3161 to be done as part of timestamping). These response verification options should include the root certificate of the timestamp authority, so that the trust status of the timestamp signature can be verified. The options that should be passed are the same ones that one expects the timestamp to be verifiable with in the future (once it is embedded in the document), except the response verification requires online revocation information whereas the later verification may not (depending on whether LTV offline verification information for the embedded timestamp gets embedded into the document by that time). The timestamp response verification step makes sure that (a) the timestamp response has a success status, which is the only time that this is verified in the entire workflow, which prevents embedding an unsuccessful response; (b) that it digests the main signature digest correctly and is otherwise generally verifiable; and (c) that the nonce is correct (which is the only time that this is verifiable in the entire workflow) to prevent replay attacks (if it was not requested in the TimestampingConfiguration that the nonce mechanism should be disabled).

##### Returns

Type | Description
--- | ---
TimestampingResult | The result of the timestamp request, including the final document signature as DER-encoded CMS with a timestamp embedded

##### Remarks

This function does not insert the final CMS-type document signature into the document. You must retrieve it from the result using GetData and then pass that to PDFDoc SaveCustomSignature.

#### GenerateESSSigningCertPAdESAttribute(X509Certificate, Type)

##### Declaration

    public static byte[] GenerateESSSigningCertPAdESAttribute(X509Certificate in_signer_cert, DigestAlgorithm.Type in_digest_algorithm_type)

##### Parameters

Type | Name | Description
--- | --- | ---
X509Certificate | in_signer_cert |
DigestAlgorithm.Type | in_digest_algorithm_type |

##### Returns

Type | Description
--- | ---
byte[] |

#### GetByteRanges()

Retrieves the ranges of byte indices within the document over which this signature is intended to apply/be verifiable.

##### Declaration

    public ByteRange[] GetByteRanges()

##### Returns

Type | Description
--- | ---
ByteRange[] | a container of byte range objects

##### Remarks

This function does not verify that the signature is valid over its byte ranges. It merely returns them. This can be useful when a document consists of multiple incremental revisions, the latter of which may or may not have been signed, for telling which revisions were actually signed by which signature. The outputs of this function can also be used to truncate the document at the end of a signed byte range, in order that the signed document revision may be retrieved from a document with later incremental revisions. Of course, to be certain that the signature is valid, it must also then be verified using the verification API. Also, the caller is responsible for making sure that the byte ranges returned from this function actually make sense (i.e. fit inside the document).

#### GetCert(int)

Gets a certificate in the certificate chain (Cert entry) of the digital signature dictionary by index. Throws if Cert is not Array or String, throws if index is out of range and Cert is Array, throws if index is less than 1 and Cert is string, otherwise retrieves the certificate. Only to be used for old-style adbe.x509.rsa_sha1 signatures; for other signatures, use CMS getter functions instead.

##### Declaration

    public byte[] GetCert(int in_index)

##### Parameters

Type | Name | Description
--- | --- | ---
int | in_index | An integral index which must be greater than 0 and less than the cert count as retrieved using GetCertCount.

##### Returns

Type | Description
--- | ---
byte[] | A vector of bytes containing the certificate at the index. Returns empty vector if Cert is missing.

#### GetCertCount()

Gets number of certificates in certificate chain (Cert entry of digital signature dictionary). Must call HasCryptographicSignature first and use it to check whether the signature is signed. Only to be used for old-style adbe.x509.rsa_sha1 signatures; for other signatures, use CMS getter functions instead.

##### Declaration

    public int GetCertCount()

##### Returns

Type | Description
--- | ---
int | An integer value - the number of certificates in the Cert entry of the digital signature dictionary.

#### GetCertPathsFromCMS()

Retrieves all constructible certificate paths from an adbe.pkcs7.detached or ETSI.CAdES.detached digital signature. The signer will always be returned if the signature is CMS-based and not corrupt. Must only be called on signed adbe.pkcs7.detached signatures. The order of the certificates in each of the paths returned is as follows: the signer will be first, and issuers come after it in order of the issuer of the previous certificate. The default behaviour is to return a sub-path for each marginal issuer in a max-length path.

##### Declaration

    public X509Certificate[][] GetCertPathsFromCMS()

##### Returns

Type | Description
--- | ---
X509Certificate[][] | a container of X509Certificate objects.

##### Remarks

This function does not verify the paths. It merely extracts certificates and constructs paths. This function only works when the build has support for verification-related APIs.

#### GetContactInfo()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the contact information of the signer from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

##### Declaration

    public string GetContactInfo()

##### Returns

Type | Description
--- | ---
string | A unicode string containing the contact information of the signer from within the digital signature dictionary. Empty if ContactInfo entry not present.

#### GetDocumentPermissions()

If HasCryptographicSignature, returns most restrictive permissions found in any reference entries in this digital signature. Returns Lock-resident (i.e. tentative) permissions otherwise. Throws if invalid permission value is found.

##### Declaration

    public DigitalSignatureField.DocumentPermissions GetDocumentPermissions()

##### Returns

Type | Description
--- | ---
DigitalSignatureField.DocumentPermissions | An enumeration value representing the level of restrictions (potentially) placed on the document by this signature.

#### GetLocation()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the Location of the signature from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

##### Declaration

    public string GetLocation()

##### Returns

Type | Description
--- | ---
string | A unicode string containing the signing location from within the digital signature dictionary. Empty if Location entry not present.

#### GetLockedFields()

Returns the fully-qualified names of all fields locked by this signature using the field permissions feature. Retrieves from the digital signature dictionary if the form field HasCryptographicSignature. Otherwise, retrieves from the Lock entry of the digital signature form field. Result is invalidated by any field additions or removals. Does not take document permissions restrictions into account.

##### Declaration

    public string[] GetLockedFields()

##### Returns

Type | Description
--- | ---
string[] | An array of Strings representing the fully-qualified names of all fields locked by this signature.

#### GetReason()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the Reason for the signature from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

##### Declaration

    public string GetReason()

##### Returns

Type | Description
--- | ---
string | A unicode string containing the reason for the signature from within the digital signature dictionary. Empty if Reason entry not present.

#### GetSDFObj()

Gets the SDFObj.

##### Declaration

    public Obj GetSDFObj()

##### Returns

Type | Description
--- | ---
Obj | The underlying SDF/Cos object.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetSignatureName()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the name of the signer of the signature from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

##### Declaration

    public string GetSignatureName()

##### Returns

Type | Description
--- | ---
string | A unicode string containing the name of the signer from within the digital signature dictionary. Empty if Name entry not present.

#### GetSignerCertFromCMS()

Returns the signing certificate. Must only be called on signed adbe.pkcs7.detached or ETSI.CAdES.detached signatures.

##### Declaration

    public X509Certificate GetSignerCertFromCMS()

##### Returns

Type | Description
--- | ---
X509Certificate | An X509Certificate object

##### Remarks

This function does not verify the signature. It merely extracts the claimed signing certificate. This function only works when the build has support for verification-related APIs.

#### GetSigningTime()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the "M" entry from the digital signature dictionary, which represents the signing date/time. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

##### Declaration

    public Date GetSigningTime()

##### Returns

Type | Description
--- | ---
Date | A PDF::Date object holding the signing date/time from within the digital signature dictionary. Returns a default-constructed PDF::Date if no date is present.

#### GetSubFilter()

Returns the SubFilter type of the digital signature. Specification says that one must check the SubFilter before using various getters. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

##### Declaration

    public DigitalSignatureField.SubFilterType GetSubFilter()

##### Returns

Type | Description
--- | ---
DigitalSignatureField.SubFilterType | An enumeration describing what the SubFilter of the digital signature is from within the digital signature dictionary.

#### HasCryptographicSignature()

Returns whether the digital signature field has been cryptographically signed. Checks whether there is a digital signature dictionary in the field and whether it has a Contents entry. Must be called before using various digital signature dictionary-related functions. Does not check validity - will return true even if a valid hash has not yet been generated (which will be the case after [Certify/Sign]OnNextSave[WithCustomHandler] has been called on the signature but even before Save is called on the document).

##### Declaration

    public bool HasCryptographicSignature()

##### Returns

Type | Description
--- | ---
bool | A boolean value representing whether the digital signature field has a digital signature dictionary with a Contents entry.

#### HasVisibleAppearance()

Returns whether the field has a visible appearance. Can be called without checking HasCryptographicSignature first, since it operates on the surrounding Field dictionary, not the "V" entry (i.e. digital signature dictionary). Performs the zero-width+height check, the Hidden bit check, and the NoView bit check as described by the PDF 2.0 specification, section 12.7.5.5 "Signature fields".

##### Declaration

    public bool HasVisibleAppearance()

##### Returns

Type | Description
--- | ---
bool | A boolean representing whether or not the signature field has a visible signature.

#### IsCertification()

Returns whether or not this signature is a certification.

##### Declaration

    public bool IsCertification()

##### Returns

Type | Description
--- | ---
bool | a boolean value representing whether or not this signature is a certification

#### IsLockedByDigitalSignature()

Returns whether this digital signature field is locked against modifications by any digital signatures. Can be called when this field is unsigned.

##### Declaration

    public bool IsLockedByDigitalSignature()

##### Returns

Type | Description
--- | ---
bool | A boolean representing whether this digital signature field is locked against modifications by any digital signatures in the document.

#### Set(DigitalSignatureField)

Sets this DigitalSignatureField equal to a given DigitalSignatureField

##### Declaration

    public void Set(DigitalSignatureField p)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField | p | a DigitalSignatureField object

#### SetContactInfo(string)

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Sets the ContactInfo entry in the digital signature dictionary. Must create a digital signature dictionary first using [Certify/Sign]OnNextSave[WithCustomHandler]. If this function is called on a digital signature field that has already been cryptographically signed with a valid hash, the hash will no longer be valid, so do not call Save (to sign/create the hash) until after you call this function, if you need to call this function in the first place. Essentially, call this function after [Certify/Sign]OnNextSave[WithCustomHandler] and before Save.

##### Declaration

    public void SetContactInfo(string in_contact_info)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_contact_info | A string containing the ContactInfo to be set.

#### SetDigSigLogFilename(string)

Sets the digital signature logging filename, and enables the logging. This function is expected to be called only once. Subsequent calls to the function will have no effect.

##### Declaration

    public static bool SetDigSigLogFilename(string filename)

##### Parameters

Type | Name | Description
--- | --- | ---
string | filename | The name (and path) of the log file.

##### Returns

Type | Description
--- | ---
bool | True if this operation was successful and false if it failed because the logging process has already started.

#### SetDocumentPermissions(DocumentPermissions)

Sets the document locking permission level for this digital signature field. Call only on unsigned signatures, otherwise a valid hash will be invalidated.

##### Declaration

    public void SetDocumentPermissions(DigitalSignatureField.DocumentPermissions in_perms)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField.DocumentPermissions | in_perms | An enumerated value representing the document locking permission level to set.

#### SetFieldPermissions(FieldPermissions)

##### Declaration

    public void SetFieldPermissions(DigitalSignatureField.FieldPermissions in_action)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField.FieldPermissions | in_action |

#### SetFieldPermissions(FieldPermissions, string[])

Tentatively sets which fields are to be locked by this digital signature upon signing. It is not necessary to call HasCryptographicSignature before using this function. Throws if non-empty array of field names is passed along with FieldPermissions Action == e_lock_all.

##### Declaration

    public void SetFieldPermissions(DigitalSignatureField.FieldPermissions in_action, string[] in_field_names)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField.FieldPermissions | in_action | An enumerated value representing which sort of field locking should be done. Options are All (lock all fields), Include (lock listed fields), and Exclude (lock all fields except listed fields).
string[] | in_field_names | A list of field names; can be empty (and must be empty, if Action is set to All). Empty by default.

#### SetLocation(string)

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Sets the Location entry in the digital signature dictionary. Must create a digital signature dictionary first using [Certify/Sign]OnNextSave[WithCustomHandler]. If this function is called on a digital signature field that has already been cryptographically signed with a valid hash, the hash will no longer be valid, so do not call Save (to sign/create the hash) until after you call this function, if you need to call this function in the first place. Essentially, call this function after [Certify/Sign]OnNextSave[WithCustomHandler] and before Save.

##### Declaration

    public void SetLocation(string in_location)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_location | A string containing the Location to be set.

#### SetPreferredDigestAlgorithm(Type)

##### Declaration

    public void SetPreferredDigestAlgorithm(DigestAlgorithm.Type in_digest_algorithm_type)

##### Parameters

Type | Name | Description
--- | --- | ---
DigestAlgorithm.Type | in_digest_algorithm_type |

#### SetPreferredDigestAlgorithm(Type, bool)

##### Declaration

    public void SetPreferredDigestAlgorithm(DigestAlgorithm.Type in_digest_algorithm_type, bool in_make_mandatory)

##### Parameters

Type | Name | Description
--- | --- | ---
DigestAlgorithm.Type | in_digest_algorithm_type |
bool | in_make_mandatory |

#### SetReason(string)

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Sets the Reason entry in the digital signature dictionary. Must create a digital signature dictionary first using [Certify/Sign]OnNextSave[WithCustomHandler]. If this function is called on a digital signature field that has already been cryptographically signed with a valid hash, the hash will no longer be valid, so do not call Save (to sign/create the hash) until after you call this function, if you need to call this function in the first place. Essentially, call this function after [Certify/Sign]OnNextSave[WithCustomHandler] and before Save.

##### Declaration

    public void SetReason(string in_reason)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_reason | A string containing the Reason to be set.

#### SetSigDictTimeOfSigning(Date)

##### Declaration

    public void SetSigDictTimeOfSigning(Date in_date)

##### Parameters

Type | Name | Description
--- | --- | ---
Date | in_date |

#### SignDigest(byte[], byte[], string, bool, Type)

##### Declaration

    public static byte[] SignDigest(byte[] in_digest, byte[] in_pkcs12_buffer, string in_keyfile_password, bool in_pades_mode, DigestAlgorithm.Type in_digest_algorithm_type)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | in_digest |
byte[] | in_pkcs12_buffer |
string | in_keyfile_password |
bool | in_pades_mode |
DigestAlgorithm.Type | in_digest_algorithm_type |

##### Returns

Type | Description
--- | ---
byte[] |

#### SignDigest(byte[], string, string, bool, Type)

##### Declaration

    public static byte[] SignDigest(byte[] in_digest, string in_pkcs12_keyfile_path, string in_keyfile_password, bool in_pades_mode, DigestAlgorithm.Type in_digest_algorithm_type)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | in_digest |
string | in_pkcs12_keyfile_path |
string | in_keyfile_password |
bool | in_pades_mode |
DigestAlgorithm.Type | in_digest_algorithm_type |

##### Returns

Type | Description
--- | ---
byte[] |

#### SignOnNextSave(byte[], string)

Must be called to prepare a signature for signing, which is done afterwards by calling Save. Cannot sign two signatures during one save (throws). Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

##### Declaration

    public void SignOnNextSave(byte[] in_pkcs12_buffer, string in_password)

##### Parameters

Type | Name | Description
--- | --- | ---
byte[] | in_pkcs12_buffer | A buffer of bytes containing the PKCS #12 private key certificate store to use to sign this digital signature.
string | in_password | The password to use to parse the PKCS #12 buffer.

#### SignOnNextSave(string, string)

Must be called to prepare a signature for signing, which is done afterwards by calling Save. Cannot sign two signatures during one save (throws). Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

##### Declaration

    public void SignOnNextSave(string in_pkcs12_keyfile_path, string in_password)

##### Parameters

Type | Name | Description
--- | --- | ---
string | in_pkcs12_keyfile_path | The path to the PKCS 12 keyfile to use to sign this digital signature.
string | in_password | The password to use to parse the PKCS 12 keyfile.

#### SignOnNextSaveWithCustomHandler(SignatureHandlerId)

Must be called to prepare a signature for signing, which is done afterwards by calling Save. Cannot sign two signatures during one save (throws). Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

##### Declaration

    public void SignOnNextSaveWithCustomHandler(SignatureHandlerId in_signature_handler_id)

##### Parameters

Type | Name | Description
--- | --- | ---
SignatureHandlerId | in_signature_handler_id | The unique id of the signature handler to use to sign this digital signature.

#### TimestampOnNextSave(TimestampingConfiguration, VerificationOptions)

Must be called to prepare a secure PDF-embedded timestamp signature (RFC 3161 DocTimeStamp) for signing, which is done afterwards by calling Save on the document with an e_incremental flag. Throws if document is locked by other signatures, if signature is already signed, or if another signature has already been prepared for signing on the next save (because only one signing operation can be done per incremental save). Default document permission level is e_annotating_formfilling_signing_allowed.

##### Declaration

    public void TimestampOnNextSave(TimestampingConfiguration in_timestamping_config, VerificationOptions in_timestamp_response_verification_options)

##### Parameters

Type | Name | Description
--- | --- | ---
TimestampingConfiguration | in_timestamping_config | Configuration options to store for timestamping. These will include various items related to contacting a timestamping authority. Incorrect configuration will result in document Save throwing an exception. The usability of a combination of a TimestampingConfiguration and VerificationOptions can be checked ahead of time to prevent exceptions by calling TestConfiguration on TimestampingConfiguration and passing VerificationOptions.
VerificationOptions | in_timestamp_response_verification_options | Options for the timestamp response verification step (which is required by RFC 3161 to be done as part of timestamping). These response verification options should include the root certificate of the timestamp authority, so that the trust status of the timestamp signature can be verified. The options that should be passed are the same ones that one expects the timestamp to be verifiable with in the future (once it is embedded in the document), except the response verification requires online revocation information whereas the later verification may not (depending on whether LTV offline verification information for the timestamp signature gets embedded into the document by that time). The timestamp response verification step makes sure that (a) the timestamp response has a success status, which is the only time that this is verified in the entire workflow, which prevents embedding an unsuccessful response; (b) that it digests the document correctly and is otherwise generally verifiable; and (c) that the nonce is correct (which is the only time that this is verifiable in the entire workflow) to prevent replay attacks (if it was not requested in the TimestampingConfiguration that the nonce mechanism should be disabled).

##### Remarks

A failure in timestamp response verification will result in document Save throwing an exception. It is recommended to use TimestampingConfiguration.TestConfiguration with the VerificationOptions ahead of time to avoid this.

#### UseSubFilter(SubFilterType)

##### Declaration

    public void UseSubFilter(DigitalSignatureField.SubFilterType in_subfilter_type)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField.SubFilterType | in_subfilter_type |

#### UseSubFilter(SubFilterType, bool)

##### Declaration

    public void UseSubFilter(DigitalSignatureField.SubFilterType in_subfilter_type, bool in_make_mandatory)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField.SubFilterType | in_subfilter_type |
bool | in_make_mandatory |

#### Verify(VerificationOptions)

Verifies this cryptographic digital signature in the manner specified by the VerificationOptions.

##### Declaration

    public VerificationResult Verify(VerificationOptions in_verification_options)

##### Parameters

Type | Name | Description
--- | --- | ---
VerificationOptions | in_verification_options | The options specifying how to do the verification.

##### Returns

Type | Description
--- | ---
VerificationResult | A VerificationResult object containing various information about the verifiability of the cryptographic digital signature.

#### op_Assign(DigitalSignatureField)

Assignment operator

##### Declaration

    public DigitalSignatureField op_Assign(DigitalSignatureField r)

##### Parameters

Type | Name | Description
--- | --- | ---
DigitalSignatureField | r | a DigitalSignatureField object

##### Returns

Type | Description
--- | ---
DigitalSignatureField | a DigitalSignatureField object equal to the one passed in

### Implements

IDisposable