DigitalSignatureField.h

Go to the documentation of this file.

//---------------------------------------------------------------------------------------
// Copyright (c) 2001-2025 by Apryse Software Inc. All Rights Reserved.
// Consult legal.txt regarding legal and license information.
//---------------------------------------------------------------------------------------
 
#ifndef PDFTRON_H_CPPPDFDigitalSignatureField
#define PDFTRON_H_CPPPDFDigitalSignatureField
#include <C/PDF/TRN_DigitalSignatureField.h>
#include <C/PDF/TRN_VerificationResult.h>
 
#include <PDF/VerificationOptions.h>
#include <PDF/VerificationResult.h>
#include <PDF/TimestampingConfiguration.h>
#include <Common/BasicTypes.h>
#include <Common/UString.h>
#include <PDF/PDFDoc.h>
#include <Crypto/X509Certificate.h>
#include <Common/ByteRange.h>
#include <PDF/CMSSignatureOptions.h>
#include <Crypto/AlgorithmIdentifier.h>
#include <vector>
 
namespace pdftron { namespace PDF { 
 

class DigitalSignatureField
{
public:
    //enums:
 
    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 {
        // No changes to the document shall be permitted; any change to the document shall invalidate the signature.
        e_no_changes_allowed = 1,
        // Permitted changes shall be filling in forms, instantiating page templates, and signing; other changes shall invalidate the signature.
        e_formfilling_signing_allowed = 2,
        // Permitted changes shall be the same as for 2, as well as annotation creation, deletion, and modification; other changes shall invalidate the signature.
        e_annotating_formfilling_signing_allowed = 3,
        // Represents the absence of any document permissions during retrieval; not to be used during setting
        e_unrestricted = 4
    };
    enum FieldPermissions {
        // Locks all form fields.
        e_lock_all = 0,
        // Locks only those form fields specified.
        e_include = 1,
        // Locks only those form fields not specified.
        e_exclude = 2
    };
 
    DigitalSignatureField(const DigitalSignatureField& other);
    DigitalSignatureField& operator= (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<UChar> 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);
    
#ifdef SWIG
// We use an std::vector of UTF-8 std::strings for SWIG, because SWIG has trouble with mapping UString to string when it's in a vector<UString>.
    void SetFieldPermissions(const FieldPermissions in_action, const std::vector<std::string>& in_field_names = std::vector<std::string>());
#else
    void SetFieldPermissions(const FieldPermissions in_action, const std::vector<UString>& in_field_names_list = std::vector<UString>());
    void SetFieldPermissions(const FieldPermissions in_action, const UString* in_field_names_list, const size_t in_field_names_list_size);
#endif
    
    void SetDocumentPermissions(DocumentPermissions in_perms);
    
    void SignOnNextSave(const UString& in_pkcs12_keyfile_path, const UString& in_password);
    
    void SignOnNextSave(const UChar* in_pkcs12_buffer, size_t in_buf_size, 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 UChar* in_pkcs12_buffer, size_t in_buf_size, const UString& in_password);
    
    void CertifyOnNextSaveWithCustomHandler(const SDF::SignatureHandlerId in_signature_handler_id);
    
    SDF::Obj GetSDFObj() const;
    
    bool IsLockedByDigitalSignature() const;
    
#ifdef SWIG
// We use an std::vector of UTF-8 std::strings for SWIG, because SWIG has trouble with mapping UString to string when it's in a vector<UString>.
    std::vector<std::string> GetLockedFields() const;
#else
    std::vector<UString> GetLockedFields() const;
#endif
    
    DocumentPermissions GetDocumentPermissions() const;
    
    void ClearSignature();
    
    VerificationResult Verify(const VerificationOptions& in_opts) const;

    bool IsCertification() const;
    
    Crypto::X509Certificate GetSignerCertFromCMS() const;

    std::vector<Common::ByteRange> GetByteRanges() const;
    
    std::vector<std::vector<Crypto::X509Certificate> > GetCertPathsFromCMS() const;

    bool EnableLTVOfflineVerification(const VerificationResult& in_verification_result) const;    

    void TimestampOnNextSave(const TimestampingConfiguration& in_timestamping_config,
        const VerificationOptions& in_timestamp_response_verification_options);

    TimestampingResult GenerateContentsWithEmbeddedTimestamp(const TimestampingConfiguration& in_timestamping_config,
        const VerificationOptions& in_timestamp_response_verification_options);
        
    void UseSubFilter(const SubFilterType in_subfilter_type, const bool in_make_mandatory = true);

    std::vector<UChar> CalculateDigest(const Crypto::DigestAlgorithm::Type in_digest_algorithm_type = Crypto::DigestAlgorithm::e_SHA256) const;

    void SetPreferredDigestAlgorithm(Crypto::DigestAlgorithm::Type in_digest_algorithm_type,
        const bool in_make_mandatory = true);

    void CreateSigDictForCustomCertification(const UString& in_filter_name,
        const SubFilterType& in_subfilter_type,
        const UInt32 in_contents_size_to_reserve);

    void CreateSigDictForCustomSigning(const UString& in_filter_name,
        const SubFilterType& in_subfilter_type,
        const UInt32 in_contents_size_to_reserve);

    void SetSigDictTimeOfSigning(const PDF::Date& in_date);
 

    static std::vector<UChar> SignDigest(
        const std::vector<UChar>& in_digest,
        const UString& in_pkcs12_keyfile_path,
        const UString& in_keyfile_password,
        const bool in_pades_mode,
        const Crypto::DigestAlgorithm::Type in_digest_algorithm_type);

    static std::vector<UChar> SignDigest(
        const std::vector<UChar>& in_digest,
        const std::vector<UChar>& in_pkcs12_buffer,
        const UString& in_keyfile_password,
        const bool in_pades_mode,
        const Crypto::DigestAlgorithm::Type in_digest_algorithm_type);
#ifndef SWIG
    static std::vector<UChar> SignDigest(
        const UChar* in_digest,
        const size_t in_digest_size,
        const UString& in_pkcs12_keyfile_path,
        const UString& in_keyfile_password,
        const bool in_pades_mode,
        const Crypto::DigestAlgorithm::Type in_digest_algorithm_type);

    static std::vector<UChar> SignDigest(
        const UChar* in_digest,
        const size_t in_digest_size,
        const UChar* in_pkcs12_buffer,
        const size_t in_pkcs12_buffer_size,
        const UString& in_keyfile_password,
        const bool in_pades_mode,
        const Crypto::DigestAlgorithm::Type in_digest_algorithm_type);
#endif

    static std::vector<UChar> GenerateESSSigningCertPAdESAttribute(
        const Crypto::X509Certificate& in_signer_cert,
        const Crypto::DigestAlgorithm::Type in_digest_algorithm_type);

    static std::vector<UChar> GenerateCMSSignedAttributes(
        const std::vector<UChar>& in_digest_buf,
        const std::vector<UChar>& in_custom_signedattributes_buf = std::vector<UChar>());
#ifndef SWIG
    static std::vector<UChar> GenerateCMSSignedAttributes(
        const UChar* in_digest_buf,
        const size_t in_digest_buf_size, 
        const UChar* in_custom_signedattributes_buf = NULL, 
        const size_t in_custom_signedattributes_buf_size = 0);
#endif

    static std::vector<UChar> GenerateCMSSignature(
        const Crypto::X509Certificate& in_signer_cert,
        const std::vector<Crypto::X509Certificate>& in_chain_certs_list,
        const Crypto::ObjectIdentifier& in_digest_algorithm_oid,
        const Crypto::ObjectIdentifier& in_signature_algorithm_oid,
        const std::vector<UChar>& in_signature_value_buf,
        const std::vector<UChar>& in_signedattributes_buf);
#ifndef SWIG
    static std::vector<UChar> GenerateCMSSignature(
        const Crypto::X509Certificate& in_signer_cert,
        const Crypto::X509Certificate* in_chain_certs_list,
        const size_t in_chain_certs_list_size,
        const Crypto::ObjectIdentifier& in_digest_algorithm_oid,
        const Crypto::ObjectIdentifier& in_signature_algorithm_oid,
        const UChar* in_signature_value_buf,
        const size_t in_signature_value_buf_size,
        const UChar* in_signedattributes_buf,
        const size_t in_signedattributes_buf_size);
#endif

    static std::vector<UChar> GenerateCMSSignature(
        const Crypto::X509Certificate& signer_cert,
        const std::vector<Crypto::X509Certificate>& chain_certs_list,
        const Crypto::AlgorithmIdentifier& digest_algorithm_id,
        const Crypto::AlgorithmIdentifier& signature_algorithm_id,
        const std::vector<UChar>& signature_value_buf,
        const std::vector<UChar>& signedattributes_buf,
        const CMSSignatureOptions& cms_options = CMSSignatureOptions());
#ifndef SWIG
    static std::vector<UChar> GenerateCMSSignature(
        const Crypto::X509Certificate& signer_cert,
        const Crypto::X509Certificate* chain_certs_list,
        const size_t chain_certs_list_size,
        const Crypto::AlgorithmIdentifier& digest_algorithm_id,
        const Crypto::AlgorithmIdentifier& signature_algorithm_id,
        const UChar* signature_value_buf,
        const size_t signature_value_buf_size,
        const UChar* signedattributes_buf,
        const size_t signedattributes_buf_size,
        const CMSSignatureOptions& cms_options = CMSSignatureOptions());
#endif

    static bool SetDigSigLogFilename(const UString& filename);
 
// @cond PRIVATE_DOC
#ifndef SWIGHIDDEN
    DigitalSignatureField(TRN_DigitalSignatureField impl);
    TRN_DigitalSignatureField m_impl;
#endif
// @endcond
};
 
#include <Impl/DigitalSignatureField.inl>
} //end pdftron
} //end PDF
 
 
#endif //PDFTRON_H_CPPPDFDigitalSignatureField