All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::PDF::DigitalSignatureField Class Reference

#include <DigitalSignatureField.h>

Public Types

enum  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
}
 
enum  DocumentPermissions { e_no_changes_allowed = 1, e_formfilling_signing_allowed = 2, e_annotating_formfilling_signing_allowed = 3, e_unrestricted = 4 }
 
enum  FieldPermissions { e_lock_all = 0, e_include = 1, e_exclude = 2 }
 

Public Member Functions

 DigitalSignatureField (const DigitalSignatureField &other)
 
DigitalSignatureFieldoperator= (const DigitalSignatureField &other)
 
 DigitalSignatureField (const PDF::Field &in_field)
 
bool HasCryptographicSignature () const
 
SubFilterType GetSubFilter () const
 
UString GetSignatureName () const
 
Date GetSigningTime () const
 
UString GetLocation () const
 
UString GetReason () const
 
UString GetContactInfo () const
 
std::vector< unsigned char > GetCert (UInt32 in_index) const
 
UInt32 GetCertCount () const
 
bool HasVisibleAppearance () const
 
void SetContactInfo (const UString &in_contact_info)
 
void SetLocation (const UString &in_location)
 
void SetReason (const UString &in_reason)
 
void SetFieldPermissions (const FieldPermissions in_action, const std::vector< UString > &in_field_names=std::vector< UString >())
 
void SetFieldPermissions (const FieldPermissions in_action, const UString *in_field_names, const size_t in_field_names_num_elems)
 
void SetDocumentPermissions (DocumentPermissions in_perms)
 
void SignOnNextSave (const UString &in_pkcs12_keyfile_path, const UString &in_password)
 
void SignOnNextSave (const std::vector< unsigned char > &in_pkcs12_buffer, const UString &in_password)
 
void SignOnNextSaveWithCustomHandler (const SDF::SignatureHandlerId in_signature_handler_id)
 
void CertifyOnNextSave (const UString &in_pkcs12_keyfile_path, const UString &in_password)
 
void CertifyOnNextSave (const std::vector< unsigned char > &in_pkcs12_buffer, const UString &in_password)
 
void CertifyOnNextSaveWithCustomHandler (const SDF::SignatureHandlerId in_signature_handler_id)
 
SDF::Obj GetSDFObj () const
 
bool IsLockedByDigitalSignature () const
 
std::vector< UStringGetLockedFields () const
 
DocumentPermissions GetDocumentPermissions () const
 
void ClearSignature ()
 
VerificationResult Verify (const VerificationOptions &in_opts) const
 

Detailed Description

The class DigitalSignatureField. A class representing a digital signature form field.

Definition at line 25 of file DigitalSignatureField.h.

Member Enumeration Documentation

Enumerator
e_no_changes_allowed 
e_formfilling_signing_allowed 
e_annotating_formfilling_signing_allowed 
e_unrestricted 

Definition at line 39 of file DigitalSignatureField.h.

Enumerator
e_lock_all 
e_include 
e_exclude 

Definition at line 49 of file DigitalSignatureField.h.

Enumerator
e_adbe_x509_rsa_sha1 
e_adbe_pkcs7_detached 
e_adbe_pkcs7_sha1 
e_ETSI_CAdES_detached 
e_ETSI_RFC3161 
e_unknown 
e_absent 

Definition at line 30 of file DigitalSignatureField.h.

Constructor & Destructor Documentation

pdftron::PDF::DigitalSignatureField::DigitalSignatureField ( const DigitalSignatureField other)
pdftron::PDF::DigitalSignatureField::DigitalSignatureField ( const PDF::Field in_field)

Constructs a PDF::DigitalSignatureField from a PDF::Field.

Parameters
in_field– the PDF::Field to construct the DigitalSignatureField from.

Member Function Documentation

void pdftron::PDF::DigitalSignatureField::CertifyOnNextSave ( const UString in_pkcs12_keyfile_path,
const UString 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.
void pdftron::PDF::DigitalSignatureField::CertifyOnNextSave ( const std::vector< unsigned char > &  in_pkcs12_buffer,
const UString 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.
void pdftron::PDF::DigitalSignatureField::CertifyOnNextSaveWithCustomHandler ( const SDF::SignatureHandlerId  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.
void pdftron::PDF::DigitalSignatureField::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.

std::vector<unsigned char> pdftron::PDF::DigitalSignatureField::GetCert ( UInt32  in_index) const

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.

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.
UInt32 pdftron::PDF::DigitalSignatureField::GetCertCount ( ) const

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
An integer value - the number of certificates in the Cert entry of the digital signature dictionary.
UString pdftron::PDF::DigitalSignatureField::GetContactInfo ( ) const

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 unicode string containing the contact information of the signer from within the digital signature dictionary. Empty if ContactInfo entry not present.
DocumentPermissions pdftron::PDF::DigitalSignatureField::GetDocumentPermissions ( ) const

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.
UString pdftron::PDF::DigitalSignatureField::GetLocation ( ) const

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 unicode string containing the signing location from within the digital signature dictionary. Empty if Location entry not present.
std::vector<UString> pdftron::PDF::DigitalSignatureField::GetLockedFields ( ) const

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 UStrings representing the fully-qualified names of all fields locked by this signature.
UString pdftron::PDF::DigitalSignatureField::GetReason ( ) const

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 unicode string containing the reason for the signature from within the digital signature dictionary. Empty if Reason entry not present.
SDF::Obj pdftron::PDF::DigitalSignatureField::GetSDFObj ( ) const

Retrieves the SDF Obj of the digital signature field.

Returns
the underlying SDF/Cos object.
UString pdftron::PDF::DigitalSignatureField::GetSignatureName ( ) const

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 unicode string containing the name of the signer from within the digital signature dictionary. Empty if Name entry not present.
Date pdftron::PDF::DigitalSignatureField::GetSigningTime ( ) const

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 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.
SubFilterType pdftron::PDF::DigitalSignatureField::GetSubFilter ( ) const

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.
bool pdftron::PDF::DigitalSignatureField::HasCryptographicSignature ( ) const

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.
bool pdftron::PDF::DigitalSignatureField::HasVisibleAppearance ( ) const

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.
bool pdftron::PDF::DigitalSignatureField::IsLockedByDigitalSignature ( ) const

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.
DigitalSignatureField& pdftron::PDF::DigitalSignatureField::operator= ( const DigitalSignatureField other)
void pdftron::PDF::DigitalSignatureField::SetContactInfo ( const UString 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.
void pdftron::PDF::DigitalSignatureField::SetDocumentPermissions ( 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.
void pdftron::PDF::DigitalSignatureField::SetFieldPermissions ( const FieldPermissions  in_action,
const std::vector< UString > &  in_field_names = std::vector< UString >() 
)

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.
void pdftron::PDF::DigitalSignatureField::SetFieldPermissions ( const FieldPermissions  in_action,
const UString in_field_names,
const size_t  in_field_names_num_elems 
)
void pdftron::PDF::DigitalSignatureField::SetLocation ( const UString 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.
void pdftron::PDF::DigitalSignatureField::SetReason ( const UString 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.
void pdftron::PDF::DigitalSignatureField::SignOnNextSave ( const UString in_pkcs12_keyfile_path,
const UString 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.
void pdftron::PDF::DigitalSignatureField::SignOnNextSave ( const std::vector< unsigned char > &  in_pkcs12_buffer,
const UString 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.
void pdftron::PDF::DigitalSignatureField::SignOnNextSaveWithCustomHandler ( const SDF::SignatureHandlerId  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.
VerificationResult pdftron::PDF::DigitalSignatureField::Verify ( const VerificationOptions in_opts) const

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
in_opts– The options specifying how to do the verification.
Returns
A VerificationResult object containing various information about the verifiability of the cryptographic digital signature.

The documentation for this class was generated from the following file: