PDFTron WebViewer

Class: DigitalSignatureField

PDFNet. DigitalSignatureField

new DigitalSignatureField( [mp_field_dict_obj])

The class DigitalSignatureField. A class representing a digital signature form field.
Parameters:
Name Type Argument Description
mp_field_dict_obj PDFNet.Obj <optional>
Properties:
Name Type Description
mp_field_dict_obj PDFNet.Obj

Members

<static> DocumentPermissions

Properties:
Name Type Description
e_no_changes_allowed number
e_formfilling_signing_allowed number
e_annotating_formfilling_signing_allowed number
e_unrestricted number

<static> FieldPermissions

Properties:
Name Type Description
e_lock_all number
e_include number
e_exclude number

<static> SubFilterType

Properties:
Name Type Description
e_adbe_x509_rsa_sha1 number
e_adbe_pkcs7_detached number
e_adbe_pkcs7_sha1 number
e_ETSI_CAdES_detached number
e_ETSI_RFC3161 number
e_unknown number
e_absent number

Methods

<static> createFromField(d)

Parameters:
Name Type Description
d PDFNet.Field
Returns:
A promise that resolves to an object of type: "PDFNet.DigitalSignatureField"
Type
Promise.<PDFNet.DigitalSignatureField>

certifyOnNextSave(in_pkcs12_keyfile_path, in_password)

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.
Parameters:
Name Type Description
in_pkcs12_keyfile_path string - The path to the PKCS #12 private keyfile to use to certify this digital signature.
in_password string - The password to use to parse the PKCS #12 keyfile.
Returns:
Type
Promise.<void>

certifyOnNextSaveFromBuffer(in_pkcs12_buffer, in_password)

Parameters:
Name Type Description
in_pkcs12_buffer ArrayBuffer | Int8Array | Uint8Array | Uint8ClampedArray
in_password string
Returns:
Type
Promise.<void>

certifyOnNextSaveWithCustomHandler(in_signature_handler_id)

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.
Parameters:
Name Type Description
in_signature_handler_id number - The unique id of the signature handler to use to certify this digital signature.
Returns:
Type
Promise.<void>

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 if saving after clearing was done incrementally. Clears the appearance as well.
Returns:
Type
Promise.<void>

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.
Returns:
A promise that resolves to an integer value the number of certificates in the Cert entry of the digital signature dictionary.
Type
Promise.<number>

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.
Returns:
A promise that resolves to a unicode string containing the contact information of the signer from within the digital signature dictionary. Empty if ContactInfo entry not present.
Type
Promise.<string>

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.
Returns:
A promise that resolves to an enumeration value representing the level of restrictions (potentially) placed on the document by this signature.
Type
Promise.<number>
Example
Return value enum:
<pre>
PDFNet.DigitalSignatureField.DocumentPermissions = {
	e_no_changes_allowed : 1
	e_formfilling_signing_allowed : 2
	e_annotating_formfilling_signing_allowed : 3
	e_unrestricted : 4
}
</pre>

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.
Returns:
A promise that resolves to a unicode string containing the signing location from within the digital signature dictionary. Empty if Location entry not present.
Type
Promise.<string>

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.
Returns:
A promise that resolves to a unicode string containing the reason for the signature from within the digital signature dictionary. Empty if Reason entry not present.
Type
Promise.<string>

getSDFObj()

Retrieves the SDF Obj of the digital signature field.
Returns:
A promise that resolves to the underlying SDF/Cos object.
Type
Promise.<PDFNet.Obj>

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.
Returns:
A promise that resolves to a unicode string containing the name of the signer from within the digital signature dictionary. Empty if Name entry not present.
Type
Promise.<string>

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.
Returns:
A promise that resolves to 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.
Type
Promise.<PDFNet.Date>

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.
Returns:
A promise that resolves to an enumeration describing what the SubFilter of the digital signature is from within the digital signature dictionary.
Type
Promise.<number>
Example
Return value enum:
<pre>
PDFNet.DigitalSignatureField.SubFilterType = {
	e_adbe_x509_rsa_sha1 : 0
	e_adbe_pkcs7_detached : 1
	e_adbe_pkcs7_sha1 : 2
	e_ETSI_CAdES_detached : 3
	e_ETSI_RFC3161 : 4
	e_unknown : 5
	e_absent : 6
}
</pre>

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).
Returns:
A promise that resolves to a boolean value representing whether the digital signature field has a digital signature dictionary with a Contents entry.
Type
Promise.<boolean>

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".
Returns:
A promise that resolves to a boolean representing whether or not the signature field has a visible signature.
Type
Promise.<boolean>

isLockedByDigitalSignature()

Returns whether this digital signature field is locked against modifications by any digital signatures. Can be called when this field is unsigned.
Returns:
A promise that resolves to a boolean representing whether this digital signature field is locked against modifications by any digital signatures in the document.
Type
Promise.<boolean>

setContactInfo(in_contact_info)

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.
Parameters:
Name Type Description
in_contact_info string - A string containing the ContactInfo to be set.
Returns:
Type
Promise.<void>

setDocumentPermissions(in_perms)

Sets the document locking permission level for this digital signature field. Call only on unsigned signatures, otherwise a valid hash will be invalidated.
Parameters:
Name Type Description
in_perms number 
PDFNet.DigitalSignatureField.DocumentPermissions = {
	e_no_changes_allowed : 1
	e_formfilling_signing_allowed : 2
	e_annotating_formfilling_signing_allowed : 3
	e_unrestricted : 4
}
-- An enumerated value representing the document locking permission level to set.
Returns:
Type
Promise.<void>

setLocation(in_location)

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.
Parameters:
Name Type Description
in_location string - A string containing the Location to be set.
Returns:
Type
Promise.<void>

setReason(in_reason)

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.
Parameters:
Name Type Description
in_reason string - A string containing the Reason to be set.
Returns:
Type
Promise.<void>

signOnNextSave(in_pkcs12_keyfile_path, in_password)

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.
Parameters:
Name Type Description
in_pkcs12_keyfile_path string - The path to the PKCS #12 private keyfile to use to sign this digital signature.
in_password string - The password to use to parse the PKCS #12 keyfile.
Returns:
Type
Promise.<void>

signOnNextSaveFromBuffer(in_pkcs12_buffer, in_password)

Parameters:
Name Type Description
in_pkcs12_buffer ArrayBuffer | Int8Array | Uint8Array | Uint8ClampedArray
in_password string
Returns:
Type
Promise.<void>

signOnNextSaveWithCustomHandler(in_signature_handler_id)

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.
Parameters:
Name Type Description
in_signature_handler_id number - The unique id of the signature handler to use to sign this digital signature.
Returns:
Type
Promise.<void>

verify(in_opts)

Verifies this cryptographic digital signature in the manner specified by the VerificationOptions. EXPERIMENTAL. Digital signature verification is undergoing active development, but currently does not support a number of features. If we are missing a feature that is important to you, or if you have files that do not act as expected, please contact us using one of the following forms: https://www.pdftron.com/form/trial-support/ or https://www.pdftron.com/form/request/
Parameters:
Name Type Description
in_opts PDFNet.VerificationOptions - The options specifying how to do the verification.
Returns:
A promise that resolves to a VerificationResult object containing various information about the verifiability of the cryptographic digital signature.
Type
Promise.<PDFNet.VerificationResult>