public class

DigitalSignatureField

extends Object
implements __Delete
java.lang.Object
   ↳ com.pdftron.pdf.DigitalSignatureField

Class Overview

A class representing a digital signature form field.

Summary

Nested Classes
enum DigitalSignatureField.DocumentPermissions  
enum DigitalSignatureField.FieldPermissions  
enum DigitalSignatureField.SubFilterType  
Public Constructors
DigitalSignatureField(Field in_field)
Constructs a DigitalSignatureField from a Field.
Public Methods
static DigitalSignatureField __Create(long impl, Object ref)
long __GetHandle()
Object __GetRefHandle()
byte[] calculateDigest(DigestAlgorithm in_digest_algorithm_type)
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.
byte[] 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.
void certifyOnNextSave(String in_pkcs12_keyfile_path, String in_password)
Must be called to prepare a signature for certification, which is done afterwards by calling Save.
void certifyOnNextSave(byte[] in_pkcs12_buffer, String in_password)
Must be called to prepare a signature for certification, which is done afterwards by calling Save.
void certifyOnNextSaveWithCustomHandler(long in_signature_handler_id)
Must be called to prepare a signature for certification, which is done afterwards by calling Save.
void clearSignature()
Clears cryptographic signature, if present.
void createSigDictForCustomCertification(String in_filter_name, DigitalSignatureField.SubFilterType in_subfilter_type, int in_contents_size_to_reserve)
Prepares the field for certification without actually performing certification.
void createSigDictForCustomSigning(String in_filter_name, DigitalSignatureField.SubFilterType in_subfilter_type, int in_contents_size_to_reserve)
Prepares the field for approval signing without actually performing signing.
void destroy()
Frees the native memory of the object.
boolean enableLTVOfflineVerification(VerificationResult in_verification_result)
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.
TimestampingResult generateContentsWithEmbeddedTimestamp(TimestampingConfiguration in_timestamping_config, VerificationOptions in_timestamp_response_verification_options)
Contacts a remote timestamp authority over network, sends CMS digest, receives and verifies timestamp token, combines the timestamp token and the data of an existing CMS-type (adbe.pkcs7.detached or ETSI.CAdES.detached subfilter) main document signature, and then returns that data to the user.
ByteRange[] getByteRanges()
Retrieves the ranges of byte indices within the document over which this signature is intended to apply/be verifiable.
byte[] getCert(int in_index)
Gets a certificate in the certificate chain (Cert entry) of the digital signature dictionary by index.
int getCertCount()
Gets number of certificates in certificate chain (Cert entry of digital signature dictionary).
X509Certificate[][] getCertPathsFromCMS()
Retrieves all constructible certificate paths from an adbe.pkcs7.detached digital signature.
String getContactInfo()
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
DigitalSignatureField.DocumentPermissions getDocumentPermissions()
If HasCryptographicSignature, returns most restrictive permissions found in any reference entries in this digital signature.
String getLocation()
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
String[] getLockedFields()
Returns the fully-qualified names of all fields locked by this signature using the field permissions feature.
String getReason()
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
Obj getSDFObj()
Retrieves the SDF Obj of the digital signature field.
String getSignatureName()
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
X509Certificate getSignerCertFromCMS()
Returns the signing certificate.
Date getSigningTime()
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
DigitalSignatureField.SubFilterType getSubFilter()
Returns the SubFilter type of the digital signature.
boolean hasCryptographicSignature()
Returns whether the digital signature field has been cryptographically signed.
boolean hasVisibleAppearance()
Returns whether the field has a visible appearance.
boolean isCertification()
Returns whether or not this signature is a certification.
boolean isLockedByDigitalSignature()
Returns whether this digital signature field is locked against modifications by any digital signatures.
void setContactInfo(String in_contact_info)
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
void setDocumentPermissions(DigitalSignatureField.DocumentPermissions in_perms)
Sets the document locking permission level for this digital signature field.
void setFieldPermissions(DigitalSignatureField.FieldPermissions in_action)
void setFieldPermissions(DigitalSignatureField.FieldPermissions in_action, String[] in_field_names)
Tentatively sets which fields are to be locked by this digital signature upon signing.
void setLocation(String in_location)
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
void setPreferredDigestAlgorithm(DigestAlgorithm in_digest_algorithm_type, boolean in_make_mandatory)
Sets the preferred digest algorithm to use when signing this field.
void setPreferredDigestAlgorithm(DigestAlgorithm in_digest_algorithm_type)
void setReason(String in_reason)
Should not be called when SubFilter is ETSI.RFC3161 (i.e.
void setSigDictTimeOfSigning(Date in_date)
Adds the "M" key and value, representing the PDF-time-of-signing (not to be confused with embedded timestamps, DocTimeStamps, or CMS signing time), to the digital signature dictionary.
static byte[] signDigest(byte[] in_digest, byte[] in_pkcs12_buffer, String in_keyfile_password, boolean in_pades_mode, DigestAlgorithm in_digest_algorithm_type)
Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key buffer (.pfx).
static byte[] signDigest(byte[] in_digest, String in_pkcs12_keyfile_path, String in_keyfile_password, boolean in_pades_mode, DigestAlgorithm in_digest_algorithm_type)
Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key file (.pfx).
void signOnNextSave(String in_pkcs12_keyfile_path, String in_password)
Must be called to prepare a signature for signing, which is done afterwards by calling Save.
void signOnNextSave(byte[] in_pkcs12_buffer, String in_password)
Must be called to prepare a signature for signing, which is done afterwards by calling Save.
void signOnNextSaveWithCustomHandler(long in_signature_handler_id)
Must be called to prepare a signature for signing, which is done afterwards by calling Save.
void timestampOnNextSave(TimestampingConfiguration in_timestamping_config, VerificationOptions in_timestamp_response_verification_options)
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.
void useSubFilter(DigitalSignatureField.SubFilterType in_subfilter_type, boolean in_make_mandatory)
Sets the requested SubFilter value (which identifies a signature type) as the only one to use during future signing, overwriting all such previous settings.
void useSubFilter(DigitalSignatureField.SubFilterType in_subfilter_type)
VerificationResult verify(VerificationOptions in_verification_options)
Verifies this cryptographic digital signature in the manner specified by the VerificationOptions.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.pdftron.pdf.__Delete

Public Constructors

public DigitalSignatureField (Field in_field)

Constructs a DigitalSignatureField from a Field.

Public Methods

public static DigitalSignatureField __Create (long impl, Object ref)

public long __GetHandle ()

public Object __GetRefHandle ()

public byte[] calculateDigest (DigestAlgorithm in_digest_algorithm_type)

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.

Parameters
in_digest_algorithm_type -- the enumerated type of digest algorithm to use for the calculation.
Returns
  • an array of bytes containing the digest value

public byte[] 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.

Returns
  • an array of bytes containing the digest value

public void certifyOnNextSave (String in_pkcs12_keyfile_path, String 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
in_pkcs12_keyfile_path -- The path to the PKCS #12 private keyfile to use to certify this digital signature.
in_password -- The password to use to parse the PKCS #12 keyfile.

public void certifyOnNextSave (byte[] in_pkcs12_buffer, String 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
in_pkcs12_buffer -- A buffer of bytes containing the PKCS #12 private key certificate store to use to certify this digital signature.
in_password -- The password to use to parse the PKCS #12 buffer.

public void certifyOnNextSaveWithCustomHandler (long 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
in_signature_handler_id -- The unique id of the signature handler to use to certify this digital signature.

public 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. Clears the appearance as well.

public void createSigDictForCustomCertification (String in_filter_name, DigitalSignatureField.SubFilterType in_subfilter_type, int in_contents_size_to_reserve)

Prepares the field for certification without actually performing certification. Useful for custom signing workflows. It is not necessary to call HasCryptographicSignature before calling this function.

Parameters
in_filter_name the Filter name to use, representing the name of the signature handler that will be used to sign and verify the signature (e.g. Adobe.PPKLite)
in_subfilter_type the SubFilter name to use, representing an interoperable signature type identifier for third-party verification (e.g. adbe.pkcs7.detached, ETSI.CAdES.detached, etc.)
in_contents_size_to_reserve The size of the empty Contents entry to create. For security reasons, set the contents size to a value greater than but as close as possible to the size you expect your final signature to be.

public void createSigDictForCustomSigning (String in_filter_name, DigitalSignatureField.SubFilterType in_subfilter_type, int in_contents_size_to_reserve)

Prepares the field for approval signing without actually performing signing. Useful for custom signing workflows. It is not necessary to call HasCryptographicSignature before calling this function.

Parameters
in_filter_name the Filter name to use, representing the name of the signature handler that will be used to sign and verify the signature (e.g. Adobe.PPKLite)
in_subfilter_type the SubFilter name to use, representing an interoperable signature type identifier for third-party verification (e.g. adbe.pkcs7.detached, ETSI.CAdES.detached, etc.)
in_contents_size_to_reserve The size of the empty Contents entry to create. For security reasons, set the contents size to a value greater than but as close as possible to the size you expect your final signature to be.

public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

public boolean enableLTVOfflineVerification (VerificationResult in_verification_result)

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.

Parameters
in_verification_result -- a successful verification result containing a successful TrustVerificationResult
Returns
  • a boolean status that reflects whether offline verification information was added successfully

public TimestampingResult generateContentsWithEmbeddedTimestamp (TimestampingConfiguration in_timestamping_config, VerificationOptions in_timestamp_response_verification_options)

Contacts a remote timestamp authority over network, sends CMS digest, receives and verifies timestamp token, combines the timestamp token and the data of an existing CMS-type (adbe.pkcs7.detached or ETSI.CAdES.detached subfilter) main document signature, and then returns that data to the user.

Parameters
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.
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
  • The result of the timestamp request, including the final document signature as DER-encoded CMS with a timestamp embedded

public ByteRange[] getByteRanges ()

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

Returns
  • a container of byte range objects

public byte[] getCert (int in_index)

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

Parameters
in_index -- An integral index which must be greater than 0 and less than the cert count as retrieved using GetCertCount.
Returns
  • A vector of bytes containing the certificate at the index. Returns empty vector if Cert is missing.

public int 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.

Returns
  • An integer value - the number of certificates in the Cert entry of the digital signature dictionary.

public X509Certificate[][] getCertPathsFromCMS ()

Retrieves all constructible certificate paths from an adbe.pkcs7.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.

Returns
  • a container of X509Certificate objects

public String 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 String containing the contact information of the signer from within the digital signature dictionary. Empty if ContactInfo entry not present.

public DigitalSignatureField.DocumentPermissions 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
  • An enumeration value representing the level of restrictions (potentially) placed on the document by this signature.

public String 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 String containing the signing location from within the digital signature dictionary. Empty if Location entry not present.

public String[] 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.

Returns
  • A vector of Strings representing the fully-qualified names of all fields locked by this signature.

public 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 String containing the reason for the signature from within the digital signature dictionary. Empty if Reason entry not present.

public Obj getSDFObj ()

Retrieves the SDF Obj of the digital signature field.

Returns
  • the underlying SDF/Cos object.

public String 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 String containing the name of the signer from within the digital signature dictionary. Empty if Name entry not present.

public X509Certificate getSignerCertFromCMS ()

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

Returns
  • An X509Certificate object.

public Date 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 Date object holding the signing date/time from within the digital signature dictionary. Returns a default-constructed Date if no date is present.

public DigitalSignatureField.SubFilterType 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
  • An enumeration describing what the SubFilter of the digital signature is from within the digital signature dictionary

public boolean 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 boolean value representing whether the digital signature field has a digital signature dictionary with a Contents entry.

public 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 boolean representing whether or not the signature field has a visible signature.

public boolean isCertification ()

Returns whether or not this signature is a certification.

Returns
  • a boolean value representing whether or not this signature is a certification

public 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 boolean representing whether this digital signature field is locked against modifications by any digital signatures in the document.

public void setContactInfo (String 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
in_contact_info -- A String containing the ContactInfo to be set.

public void setDocumentPermissions (DigitalSignatureField.DocumentPermissions 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
in_perms -- An enumerated value representing the document locking permission level to set.

public void setFieldPermissions (DigitalSignatureField.FieldPermissions in_action)

public void setFieldPermissions (DigitalSignatureField.FieldPermissions in_action, String[] in_field_names)

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.

Parameters
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).
in_field_names -- A list of field names; can be empty (and must be empty, if Action is set to All). Empty by default.

public void setLocation (String 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
in_location -- A String containing the Location to be set.

public void setPreferredDigestAlgorithm (DigestAlgorithm in_digest_algorithm_type, boolean in_make_mandatory)

Sets the preferred digest algorithm to use when signing this field. This is done by setting DigestMethod in the Seed Value dictionary. This function can be called before a signature field is even prepared for signing.

Parameters
in_digest_algorithm_type -- the digest algorithm to use
in_make_mandatory -- whether to tell signing software to give up if the preferred algorithm is unsupported. Default value for this parameter is true.

public void setPreferredDigestAlgorithm (DigestAlgorithm in_digest_algorithm_type)

public void setReason (String 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
in_reason -- A String containing the Reason to be set.

public void setSigDictTimeOfSigning (Date in_date)

Adds the "M" key and value, representing the PDF-time-of-signing (not to be confused with embedded timestamps, DocTimeStamps, or CMS signing time), to the digital signature dictionary. The digital signature field must have been prepared for signing first. This function should only be used if no secure embedded timestamping support is available from your signing provider. Useful for custom signing workflows, where signing time is not set automatically by the PDFTron SDK, unlike in the usual standard handler signing workflow.

Parameters
in_date the PDF Date datetime value to set

public static byte[] signDigest (byte[] in_digest, byte[] in_pkcs12_buffer, String in_keyfile_password, boolean in_pades_mode, DigestAlgorithm in_digest_algorithm_type)

Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key buffer (.pfx).

Parameters
in_digest -- the digest value to use
in_pkcs12_buffer -- a buffer containing the PKCS #12 key (as usually stored in .pfx files) to use for signing
in_keyfile_password -- the password to use to decrypt the PKCS #12 key file data in the buffer
in_pades_mode -- whether to create a PAdES-type signature (PDF Advanced Electronic Signatures standards)
in_digest_algorithm_type -- the identifier to use to write the digest algorithm
Returns
  • the DER-serialized bytes of a CMS detached signature (CMS ContentInfo)

public static byte[] signDigest (byte[] in_digest, String in_pkcs12_keyfile_path, String in_keyfile_password, boolean in_pades_mode, DigestAlgorithm in_digest_algorithm_type)

Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key file (.pfx).

Parameters
in_digest -- the digest value to use
in_pkcs12_keyfile_path -- the path to the PKCS #12 key file (usually has a .pfx extension) to use for signing
in_keyfile_password -- the password to use to decrypt the PKCS #12 key file
in_pades_mode -- whether to create a PAdES-type signature (PDF Advanced Electronic Signatures standards)
in_digest_algorithm_type -- the identifier to use to write the digest algorithm
Returns
  • the DER-serialized bytes of a CMS detached signature (CMS ContentInfo)

public void signOnNextSave (String in_pkcs12_keyfile_path, String 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
in_pkcs12_keyfile_path -- The path to the PKCS #12 private keyfile to use to sign this digital signature.
in_password -- The password to use to parse the PKCS #12 keyfile.

public void signOnNextSave (byte[] in_pkcs12_buffer, String 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
in_pkcs12_buffer -- A buffer of bytes containing the PKCS #12 private key certificate store to use to sign this digital signature.
in_password -- The password to use to parse the PKCS #12 buffer.

public void signOnNextSaveWithCustomHandler (long 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
in_signature_handler_id -- The unique id of the signature handler to use to sign this digital signature.

public void timestampOnNextSave (TimestampingConfiguration in_timestamping_config, VerificationOptions in_timestamp_response_verification_options)

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.

Parameters
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.
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).

public void useSubFilter (DigitalSignatureField.SubFilterType in_subfilter_type, boolean in_make_mandatory)

Sets the requested SubFilter value (which identifies a signature type) as the only one to use during future signing, overwriting all such previous settings. It is not necessary to call HasCryptographicSignature before calling this function. For example, this function can be used to switch to PAdES signing mode.

Parameters
in_subfilter_type -- The SubFilter type to set.
in_make_mandatory -- Whether to make usage of this SubFilter mandatory for future signing applications. Default value for this parameter is true.

public void useSubFilter (DigitalSignatureField.SubFilterType in_subfilter_type)

public VerificationResult verify (VerificationOptions in_verification_options)

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/

Returns
  • A VerificationResult object containing various information about the verifiability of the cryptographic digital signature.