Foxit PDF SDK

Public Types | Public Member Functions | List of all members
foxit::pdf::SignatureCallback Class Referenceabstract

## Public Types
enum | CertValidity { e_CertValid = 0, e_CertExpired = 1, e_CertUnsupportType = 2, e_CertDataError = 3, e_CertInvalidPassword = 4, e_CertInvalidPath = 5, e_CertNotSet = 6, e_CertCannotGetPrivateKey = 7 }
| Enumeration for certificate validity. More...

## Public Member Functions
virtual CertValidity | CheckCertificateValidity (const wchar_t *cert_path, const WString &cert_password, void *client_data)=0
| A callback function used to check the validity of a certificate. More...
virtual common::Progressive::State | ContinueCalcDigest (const void *client_data, const common::PauseCallback *pause)=0
| A callback function used to continue the custom digest calculation process. More...
virtual String | GetDigest (const void *client_data)=0
| A callback function used to get the digest after the calculation process is finished. More...
virtual bool | IsNeedPadData ()=0
| A callback function used to check whether to return all contents with padding zero or not, when callback function SignatureCallback::VerifySigState is called. More...
virtual void | Release ()=0
| A callback function used to release current callback object itself. More...
virtual String | Sign (const void *digest, uint32 digest_length, const wchar_t *cert_path, const WString &cert_password, Signature::DigestAlgorithm digest_algorithm, void *client_data)=0
| A callback function used to do signing and return the signed data. More...
virtual String | Sign (const void *digest, uint32 digest_length, foxit::common::file::StreamCallback *cert_file_stream, const WString &cert_password, Signature::DigestAlgorithm digest_algorithm, void *client_data)=0
| A callback function used to do signing and return the signed data. More...
virtual bool | StartCalcDigest (const common::file::ReaderCallback *file, const uint32 *byte_range_array, uint32 size_of_array, const Signature &signature, const void *client_data)=0
| A callback function used to start a custom digest calculation, mainly to initialize the calculation process. More...
virtual uint32 | VerifySigState (const void *digest, uint32 digest_length, const void *signed_data, uint32 signed_data_len, void *client_data)=0
| A callback function used to verify the integrity of a signature and return the verify state. More...

## Detailed Description

This class represent a callback object to sign or verify signature. All the pure virtual functions in this class are used as callback functions and should be implemented by user, in order to sign or verify signature in a customized way.
User can set register customized signature callback object to Foxit PDF SDK by function common::Library::RegisterSignatureCallback with filter and sub filter as the callback name.

See also
  common::Library

## Member Enumeration Documentation

## ◆ CertValidity

enum foxit::pdf::SignatureCallback::CertValidity

Enumeration for certificate validity.

Values of this enumeration should be used alone.

Enumerator
e_CertValid | Certificate is valid.
e_CertExpired | Certificate is expired.
e_CertUnsupportType | Certificate is unsupport type.
e_CertDataError | Certificate's data is error.
e_CertInvalidPassword | Certificate's password is wrong.
e_CertInvalidPath | Certificate's path is wrong.
e_CertNotSet | Certificate is not set to sign a signature.
e_CertCannotGetPrivateKey | Certificate's private key cannot be gotten.

## Member Function Documentation

## ◆ CheckCertificateValidity()

virtual CertValidity foxit::pdf::SignatureCallback::CheckCertificateValidity | ( | const wchar_t * | cert_path,
|  | const WString & | cert_password,
|  | void * | client_data
| ) |  |
| pure virtual

A callback function used to check the validity of a certificate.

This callback function will be triggered when function Signature::StartSign is called. If no need to check the certificate, value SignatureCallback::e_CertValid can be returned directly.

Parameters

  [in] | cert_path | A full path of a certificate file (including file name and extension), which will be used for signing. This is passed by user from function Signature::StartSign.
  [in] | cert_password | A password string used to open the cert file. If this is an empty string, that means no password is required.This is passed by user from function Signature::StartSign.
  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign.

Returns
  Certificate validity. Please refer to values starting from SignatureCallback::e_CertValid and it should be one of these values.

## ◆ ContinueCalcDigest()

virtual common::Progressive::State foxit::pdf::SignatureCallback::ContinueCalcDigest | ( | const void * | client_data,
|  | const common::PauseCallback * | pause
| ) |  |
| pure virtual

A callback function used to continue the custom digest calculation process.

Parameters

  [in] | pause | Pause object which decides if the calculation process needs to be paused. If this is NULL, it means not to pause during the calculation process. If this is not NULL, please check the the return value of function NeedToPauseNow() of this input parameter and decide when to pause the calculation process.
  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign or Signature::StartVerify.

Returns
  common::Progressive::e_Finished means the calculation process has finished successfully.
  common::Progressive::e_ToBeContinued means the calculation process is not finished yet and callback function SignatureCallback::ContinueCalcDigest would be triggered again to continue the process.
  common::Progressive::e_Error means any error occurs.

## ◆ GetDigest()

virtual String foxit::pdf::SignatureCallback::GetDigest | ( | const void * | client_data | ) |
| pure virtual

A callback function used to get the digest after the calculation process is finished.

This callback function will be triggered when the calculation process is finished successfully.

Parameters

  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign or Signature::StartVerify.

Returns
  The digest string. If there is any error, please return an empty string.

## ◆ IsNeedPadData()

virtual bool foxit::pdf::SignatureCallback::IsNeedPadData | ( |  | ) |
| pure virtual

A callback function used to check whether to return all contents with padding zero or not, when callback function SignatureCallback::VerifySigState is called.

Returns
  true means to return all data in contents steam (including padding zero), while false means to return contents data without padding zero in stream end.

## ◆ Release()

virtual void foxit::pdf::SignatureCallback::Release | ( |  | ) |
| pure virtual

A callback function used to release current callback object itself.

Returns
  None.

## ◆ Sign() [1/2]

virtual String foxit::pdf::SignatureCallback::Sign | ( | const void * | digest,
|  | uint32 | digest_length,
|  | const wchar_t * | cert_path,
|  | const WString & | cert_password,
|  | Signature::DigestAlgorithm | digest_algorithm,
|  | void * | client_data
| ) |  |
| pure virtual

A callback function used to do signing and return the signed data.

Host application provides this callback function for custom sign mechanism. This callback function would be triggered during the signature signing process.

Parameters

  [in] | digest | The digest data buffer, for source file buffer to be signed.
  [in] | digest_length | The size of digest data buffer.
  [in] | cert_path | The certificate file path, which will be used for signing.
  [in] | cert_password | The password string, used to open the cert file. If this is an empty string, that means no password is required.
  [in] | digest_algorithm | The algorithm of message digest for signed data. Please refer to values starting from Signature::e_DigestSHA1 and this would be one of these values.
  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign or Signature::StartVerify.

Returns
  Signed data. If there is any error, please return an empty string.
  The length of returned signed data should be within the default length of signature contents which is 7942 by default or specified by fucntion Signature::SetDefaultContentsLength before signing the unsigned signature.

## ◆ Sign() [2/2]

virtual String foxit::pdf::SignatureCallback::Sign | ( | const void * | digest,
|  | uint32 | digest_length,
|  | foxit::common::file::StreamCallback * | cert_file_stream,
|  | const WString & | cert_password,
|  | Signature::DigestAlgorithm | digest_algorithm,
|  | void * | client_data
| ) |  |
| pure virtual

A callback function used to do signing and return the signed data.

Host application provides this callback function for custom sign mechanism. This callback function would be triggered during the signature signing process.

Parameters

  [in] | digest | The digest data buffer, for source file buffer to be signed.
  [in] | digest_length | The size of digest data buffer.
  [in] | cert_file_stream | A foxit::common::file::StreamCallback object which is implemented by user to access content of a certificate file which will be used for signing.
  [in] | cert_password | The password string, used to open the cert file. If this is an empty string, that means no password is required.
  [in] | digest_algorithm | The algorithm of message digest for signed data. Please refer to values starting from Signature::e_DigestSHA1 and this would be one of these values.
  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign or Signature::StartVerify.

Returns
  Signed data. If there is any error, please return an empty string.
  The length of returned signed data should be within the default length of signature contents which is 7942 by default or specified by fucntion Signature::SetDefaultContentsLength before signing the unsigned signature.

## ◆ StartCalcDigest()

virtual bool foxit::pdf::SignatureCallback::StartCalcDigest | ( | const common::file::ReaderCallback * | file,
|  | const uint32 * | byte_range_array,
|  | uint32 | size_of_array,
|  | const Signature & | signature,
|  | const void * | client_data
| ) |  |
| pure virtual

A callback function used to start a custom digest calculation, mainly to initialize the calculation process.

Parameters

  [in] | file | When signing a signature, this represents the source file object to be signed. When verifying a signature field, this represents the source file object to be verified.
  [in] | byte_range_array | A byte range array of the signed document(not the source document). Elements in this array always be in pairs of offset-size values in order of: offset,size,offset,size...
  [in] | size_of_array | Count of elements in the byte range array byte_range_array.
  [in] | signature | A signature object.
  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign, Signature::StartVerify.

Returns
  true means the calculation process is successfully started and then SignatureCallback::ContinueCalcDigest will be triggered to continue the calculation process. false means fail to start a calculation process.

## ◆ VerifySigState()

virtual uint32 foxit::pdf::SignatureCallback::VerifySigState | ( | const void * | digest,
|  | uint32 | digest_length,
|  | const void * | signed_data,
|  | uint32 | signed_data_len,
|  | void * | client_data
| ) |  |
| pure virtual

A callback function used to verify the integrity of a signature and return the verify state.

Host application provides this callback function for custom sign mechanism. This callback function would be triggered during the signature verifying process.
From 7.0, this callback function is only used to verify the intergrity of a signature. Please check the comment about return value for more details.

Parameters

  [in] | digest | The digest data buffer, for source file buffer to be verified.
  [in] | digest_length | The size of digest data buffer.
  [in] | signed_data | The signed data buffer.
  [in] | signed_data_len | The size of signed data buffer.
  [in] | client_data | A user-defined object, which is passed by user from function Signature::StartSign or Signature::StartVerify.

Returns
  Verify state:
  - Please return Signature::e_StateVerifyNoChange alone to indicate that the document has not been changed within the scope of the signature.
  - Otherwise, please return Signature::e_StateVerifyChange alone or combined with other error state value.