Foxit PDF SDK
foxit.pdf.Signature Class Reference
Inheritance diagram for foxit.pdf.Signature:
foxit.pdf.interform.Field foxit.common.Base

Public Types

enum  APFlags {
  APFlags.e_APFlagFoxitFlag = 0x0001, APFlags.e_APFlagLabel = 0x0002, APFlags.e_APFlagReason = 0x0004, APFlags.e_APFlagSigningTime = 0x0008,
  APFlags.e_APFlagDN = 0x0010, APFlags.e_APFlagLocation = 0x0020, APFlags.e_APFlagSigner = 0x0040, APFlags.e_APFlagBitmap = 0x0080,
  APFlags.e_APFlagText = 0x0100
}
 Enumeration for signature appearance flags. More...
 
enum  DigestAlgorithm { DigestAlgorithm.e_DigestSHA1 = 0, DigestAlgorithm.e_DigestSHA256 = 1, DigestAlgorithm.e_DigestSHA384 = 2, DigestAlgorithm.e_DigestSHA512 = 3 }
 Enumeration for signature digest algorithm. More...
 
enum  KeyName {
  KeyName.e_KeyNameSigner = 0, KeyName.e_KeyNameLocation = 1, KeyName.e_KeyNameReason = 2, KeyName.e_KeyNameContactInfo = 3,
  KeyName.e_KeyNameDN = 4, KeyName.e_KeyNameText = 5
}
 Enumeration for signature key name. More...
 
enum  PAdESLevel {
  PAdESLevel.e_PAdESLevelNotPAdES = 0, PAdESLevel.e_PAdESLevelNone = 1, PAdESLevel.e_PAdESLevelBB = 2, PAdESLevel.e_PAdESLevelBT = 3,
  PAdESLevel.e_PAdESLevelBLT = 4, PAdESLevel.e_PAdESLevelBLTA = 5
}
 Enumeration for PAdES level. More...
 
enum  SignatureType { SignatureType.e_SignatureTypeOrdinary = 0, SignatureType.e_SignatureTypeTimeStamp = 3 }
 Enumeration for signature type. More...
 
enum  States : uint {
  States.e_StateUnknown = 0x80000000, States.e_StateNoSignData = 0x00000200, States.e_StateUnsigned = 0x00000001, States.e_StateSigned = 0x00000002,
  States.e_StateVerifyValid = 0x00000004, States.e_StateVerifyInvalid = 0x00000008, States.e_StateVerifyErrorData = 0x00000010, States.e_StateVerifyNoSupportWay = 0x00000020,
  States.e_StateVerifyErrorByteRange = 0x00000040, States.e_StateVerifyChange = 0x00000080, States.e_StateVerifyIncredible = 0x00000100, States.e_StateVerifyNoChange = 0x00000400,
  States.e_StateVerifyIssueValid = 0x00001000, States.e_StateVerifyIssueUnknown = 0x00002000, States.e_StateVerifyIssueRevoke = 0x00004000, States.e_StateVerifyIssueExpire = 0x00008000,
  States.e_StateVerifyIssueUncheck = 0x00010000, States.e_StateVerifyIssueCurrent = 0x00020000, States.e_StateVerifyTimestampNone = 0x00040000, States.e_StateVerifyTimestampDoc = 0x00080000,
  States.e_StateVerifyTimestampValid = 0x00100000, States.e_StateVerifyTimestampInvalid = 0x00200000, States.e_StateVerifyTimestampExpire = 0x00400000, States.e_StateVerifyTimestampIssueUnknown = 0x00800000,
  States.e_StateVerifyTimestampIssueValid = 0x01000000, States.e_StateVerifyTimestampTimeBefore = 0x02000000, States.e_StateCertCannotGetVRI = 0x04000000, States.e_StateVerifyChangeLegal = 0x08000000,
  States.e_StateVerifyChangeIllegal = 0x10000000
}
 Enumeration for signature states. More...
 
- Public Types inherited from foxit.pdf.interform.Field
enum  Flags {
  Flags.e_FlagReadOnly = 0x01, Flags.e_FlagRequired = 0x02, Flags.e_FlagNoExport = 0x04, Flags.e_FlagButtonNoToggleToOff = 0x100,
  Flags.e_FlagButtonRadiosInUnison = 0x200, Flags.e_FlagTextMultiline = 0x100, Flags.e_FlagTextPassword = 0x200, Flags.e_FlagTextDoNotScroll = 0x400,
  Flags.e_FlagTextComb = 0x800, Flags.e_FlagComboEdit = 0x100, Flags.e_FlagChoiseMultiSelect = 0x100
}
 Enumeration for form field flags. More...
 
enum  Type {
  Type.e_TypeUnknown = 0, Type.e_TypePushButton = 1, Type.e_TypeCheckBox = 2, Type.e_TypeRadioButton = 3,
  Type.e_TypeComboBox = 4, Type.e_TypeListBox = 5, Type.e_TypeTextField = 6, Type.e_TypeSignature = 7
}
 Enumeration for form field type. More...
 

Public Member Functions

 Signature (Field field)
 Constructor, with parent class object. More...
 
 Signature (PDFDoc document, PDFDictionary sig_field_dict)
 Constructor, from signature field dictionary. More...
 
bool ClearSignedData ()
 Clear the data and appearance if current signature is singed and verified valid. More...
 
int GetAppearanceFlags ()
 Get signature appearance flags. More...
 
System.Drawing.Bitmap GetBitmap ()
 Get a bitmap which is used for the signature appearance. More...
 
bool GetByteRangeArray (int[] out_byte_range_array)
 Get the byte ranges data, including 4 elements. More...
 
string GetCert (int index)
 Get a certificate from current signature's certificate chain by index. More...
 
int GetCertCount ()
 Get the count of certificates in current signature's certificate chain. More...
 
string GetCertificateInfo (string key)
 Get certificate information. More...
 
PDFDoc GetDocument ()
 Get the PDF document, which current signature belongs to. More...
 
string GetFilter ()
 Get filter. More...
 
string GetKeyValue (Signature.KeyName key)
 Get the string value for specified key name. More...
 
Signature.PAdESLevel GetPAdESLevel ()
 Get PAdES level. More...
 
PDFDictionary GetSignatureDict ()
 Get signature dictionary. More...
 
Signature.SignatureType GetSignatureType ()
 Get signature type. More...
 
PDFDoc GetSignedVersionDocument (string file_path)
 Get the PDF document in the signed version in which current signature was signed. More...
 
DateTime GetSignTime ()
 Get time of signing. More...
 
uint GetState ()
 Get current state. More...
 
string GetSubFilter ()
 Get sub filter. More...
 
new bool IsEmpty ()
 Check whether current object is empty or not. More...
 
bool IsSigned ()
 Check whether current signature is signed or not. More...
 
bool IsTimeStamp ()
 Check if current signature is a time stamp signature. More...
 
void SetAppearanceContent (string appearance_content)
 Set customized appearance content (as low level drawing operation commands) for signed signature appearance. More...
 
void SetAppearanceFlags (int appearance_flags)
 Set signature appearance flags. More...
 
void SetBitmap (System.Drawing.Bitmap bitmap)
 Set a bitmap for the signature appearance. More...
 
void SetCertChain (WStringArray cert_chain)
 Set a certificate chain. More...
 
void SetDefaultContentsLength (int default_length)
 Set the default length of signature contents which represents signature value (known as signed data). More...
 
void SetFilter (string filter)
 Set filter. More...
 
void SetImage (Image image, int frame_index)
 Set an image for the signature appearance, with a specified frame index. More...
 
void SetImage (string file_path, int frame_index)
 Set an image for the signature appearance, with a specified frame index. More...
 
void SetKeyValue (Signature.KeyName key, string value)
 Set the string value for specified key name. More...
 
void SetSignTime (DateTime sign_time)
 Set time of signing. More...
 
void SetSubFilter (string sub_filter)
 Set sub filter. More...
 
Progressive StartSign (string cert_path, byte[] cert_password, Signature.DigestAlgorithm digest_algorithm, string save_path, global::System.IntPtr client_data, PauseCallback pause)
 Start signing current signature if current signature is unsigned. More...
 
Progressive StartSign (StreamCallback cert_file_stream, byte[] cert_password, Signature.DigestAlgorithm digest_algorithm, string save_path, global::System.IntPtr client_data, PauseCallback pause)
 Start signing current signature if current signature is unsigned. More...
 
Progressive StartSign (string cert_path, byte[] cert_password, Signature.DigestAlgorithm digest_algorithm, StreamCallback stream_callback, global::System.IntPtr client_data, PauseCallback pause)
 Start signing current signature if current signature is unsigned. More...
 
Progressive StartSign (StreamCallback cert_file_stream, byte[] cert_password, Signature.DigestAlgorithm digest_algorithm, StreamCallback stream_callback, global::System.IntPtr client_data, PauseCallback pause)
 Start signing current signature if current signature is unsigned. More...
 
Progressive StartVerify (global::System.IntPtr client_data, PauseCallback pause)
 Start verifying the intergrity of current signature if current signature is signed. More...
 
- Public Member Functions inherited from foxit.pdf.interform.Field
 Field (PDFDoc document, PDFDictionary field_dict)
 Constructor, from field dictionary. More...
 
 Field (Field field)
 Constructor, with another form field object. More...
 
Alignment GetAlignment ()
 Get the alignment value. More...
 
string GetAlternateName ()
 Get alternate name. More...
 
Control GetControl (int index)
 Get a form control by index. More...
 
Control GetControl (PDFPage page, int index)
 Get a form control by index, in a specified PDF page. More...
 
int GetControlCount ()
 Get count of form controls. More...
 
int GetControlCount (PDFPage page)
 Get count of form controls in a specified PDF page. More...
 
DefaultAppearance GetDefaultAppearance ()
 Get the default appearance data. More...
 
string GetDefaultValue ()
 Get default value. More...
 
PDFObject GetDefaultValueObj ()
 Get the PDF object of field's default value. More...
 
PDFDictionary GetDict ()
 Get the PDF dictionary of current object. More...
 
int GetFlags ()
 Get field flags. More...
 
PDFObject GetInheritedAttribute (string attribute_name)
 Get the PDF object for specified attribute which may be inherited from the ancestor node in the field tree. More...
 
string GetMappingName ()
 Get mapping name. More...
 
int GetMaxLength ()
 Get maximum length of the field's text, in characters. More...
 
string GetName ()
 Get field name. More...
 
ChoiceOptionArray GetOptions ()
 Get options of list box or combo box. More...
 
int GetTopVisibleIndex ()
 Get top index of option for scrollable list boxes. More...
 
Field.Type GetType ()
 Get field type. More...
 
string GetValue ()
 Get value. More...
 
PDFObject GetValueObj ()
 Get the PDF object of field's value. More...
 
bool IsEmpty ()
 Check whether current object is empty or not. More...
 
bool Reset ()
 Reset data in current field to its default value. (Not support signature field) More...
 
void SetAlignment (Alignment alignment)
 Set alignment property of a form, as a document-wide default value. (Not support signature field) More...
 
void SetAlternateName (string alternate_name)
 Set alternate name. (Not support signature field) More...
 
void SetDefaultAppearance (DefaultAppearance default_ap)
 Set default appearance data. More...
 
void SetDefaultValue (string value)
 Set default value. More...
 
void SetFlags (int flags)
 Set field flags. More...
 
void SetMappingName (string name)
 Set mapping name. (Not support signature field) More...
 
void SetMaxLength (int max_length)
 Set maximum length of the field's text, in characters. More...
 
void SetOptions (ChoiceOptionArray option_array)
 Set options of list box or combo box. More...
 
void SetTopVisibleIndex (int index)
 Set top index for scrollable list boxes. More...
 
void SetValue (string value)
 Set value. More...
 

Detailed Description

A digital signature (PDF 1.3) can be used to authenticate the identity of a user and the document's contents. It stores information about the signer and the state of the document when it was signed. The signature is contained in a signature field, as a type of form field, so class Signature is derived from class foxit.pdf.interform.Field . A signature object can be retrieved/added by following functions:

In a signature, filter and sub filter keys are used to specify the filter and sub filter of signature callback object which will be used to sign and verify the signature. Foxit PDF SDK has default signature callbacks for following filter and sub filter:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

For sub filter "ETSI.CAdES.detached" and sub filter "ETSI.RFC3161", please ensure a default time stmap server has been set to TimeStampServerMgr if default signature callbacks for them will be used to do signing. For other filter and sub filter or if user wants to use customized signature callback for above filter and sub filter, user should prepare customized signature callback and register the callback to Foxit PDF SDK by function common.Library.RegisterSignatureCallback .
This class offers functions to get/set signature information/properties, sign or verify a signature, and so on. For example:

  • To sign an unsigned signature, please use functions Signature.StartSign . When signing a signature successfully, user is strongly recommended to close current document and then open the signed PDF document and then do following operation.

  • To verify the integrity of a signed signature, please use functions Signature.StartVerify . To check if a signed signature is valid or not, please refer to class LTVVerifier .

  • To retrieve signature dictionary directly, please use function Signature.GetSignatureDict .

Before signing an unsigned signature, user can call following functions to set information for signing and signed appearance:

If an unsigned signature has been set some information for signing, but the document is saved directly or closed without signing the signature, these data (including filter and sub filter) will be lost in the saved document or in the closed document. When the document is opened again, the unsigned signature needs to be specified at least filter and sub filter for signing; otherwise, this signature cannot be signed.

See also
foxit.pdf.interform.Field
foxit.pdf.interform.Form
PDFDoc
PDFPage
TimeStampServerMgr
LTVVerifier

Member Enumeration Documentation

◆ APFlags

Enumeration for signature appearance flags.

Values of this enumeration can be used alone or in combination.

Enumerator
e_APFlagFoxitFlag 

If set, show Foxit flag on signature appearance.

e_APFlagLabel 

If set, show label on signature appearance.

e_APFlagReason 

If set, show reason on signature appearance.

e_APFlagSigningTime 

If set, show signing time on signature appearance.

e_APFlagDN 

If set, show distinguish name on signature appearance.

e_APFlagLocation 

If set, show location on signature appearance.

e_APFlagSigner 

If set, show signer on signature appearance.

e_APFlagBitmap 

If set, show bitmap on signature appearance.

e_APFlagText 

If set, show text content on signature appearance.

◆ DigestAlgorithm

Enumeration for signature digest algorithm.

Values of this enumeration should be used alone.

Enumerator
e_DigestSHA1 

Signature digest algorithm: sha1 algorithm.

e_DigestSHA256 

Signature digest algorithm: sha256 algorithm.

e_DigestSHA384 

Signature digest algorithm: sha384 algorithm.

e_DigestSHA512 

Signature digest algorithm: sha512 algorithm.

◆ KeyName

Enumeration for signature key name.

Values of this enumeration should be used alone.

Enumerator
e_KeyNameSigner 

Signature key name: signer.

e_KeyNameLocation 

Signature key name: location.

e_KeyNameReason 

Signature key name: reason.

e_KeyNameContactInfo 

Signature key name: contact information.

e_KeyNameDN 

Signature key name: distinguish name.

e_KeyNameText 

Signature key name: text content.

◆ PAdESLevel

Enumeration for PAdES level.

Values of this enumeration should be used alone.

Enumerator
e_PAdESLevelNotPAdES 

Not a PAdES signature.

e_PAdESLevelNone 

PAdES level: none.

e_PAdESLevelBB 

PAdES level: B-B.

e_PAdESLevelBT 

PAdES level: B-T.

e_PAdESLevelBLT 

PAdES level: B-LT.

e_PAdESLevelBLTA 

PAdES level: B-LTA.

◆ SignatureType

Enumeration for signature type.

Values of this enumeration should be used alone.

Enumerator
e_SignatureTypeOrdinary 

Signature type: ordinary.

e_SignatureTypeTimeStamp 

Signature type: time stamp.

◆ States

enum foxit.pdf.Signature.States : uint
strong

Enumeration for signature states.

Values of this enumeration can be used alone or in combination.
These values can be divided into four parts:

Enumerator
e_StateUnknown 

Unknown signature.

e_StateNoSignData 

Signature does not have any data for signing.

e_StateUnsigned 

Unsigned signature.

e_StateSigned 

Signed signature.

e_StateVerifyValid 

Verification state of a signature is valid.

e_StateVerifyInvalid 

Verification state of a signature is invalid.

e_StateVerifyErrorData 

Signature data is destroyed (that means the signature data cannot be parsed properly).

e_StateVerifyNoSupportWay 

Unsupported signature.

e_StateVerifyErrorByteRange 

Non expected byte range.

e_StateVerifyChange 

The document has been changed within the scope of the signature. (This indicates that signature is invalid.)

e_StateVerifyIncredible 

Signature cannot be trusted (containing aggression).

e_StateVerifyNoChange 

The document has not been changed within the scope of the signature.

e_StateVerifyIssueValid 

Verification state of the issuer is valid.

e_StateVerifyIssueUnknown 

Verification state of the issuer is unknown.

e_StateVerifyIssueRevoke 

Certificate for verifying issuer is revoked.

e_StateVerifyIssueExpire 

Certificate for verifying issuer is expired.

e_StateVerifyIssueUncheck 

Not check the issuer.

e_StateVerifyIssueCurrent 

The verified issue is current issuer.

e_StateVerifyTimestampNone 

No time stamp or not check time stamp.

e_StateVerifyTimestampDoc 

The signature is a time stamp signature.

e_StateVerifyTimestampValid 

Verification state of the time stamp is valid.

e_StateVerifyTimestampInvalid 

Verification state of the time stamp is invalid.

e_StateVerifyTimestampExpire 

Verification state of the time stamp is expired.

e_StateVerifyTimestampIssueUnknown 

Verification state of the time stamp issuer is unknown.

e_StateVerifyTimestampIssueValid 

Verification state of the time stamp issuer is valid.

e_StateVerifyTimestampTimeBefore 

Verification state of the time stamp time is valid, since the times is before the expiration date.

e_StateCertCannotGetVRI 

Cannot get verify relevant information.

e_StateVerifyChangeLegal 

The document has been changed outside of signature scope, but the changed is permitted.

e_StateVerifyChangeIllegal 

The document has been changed outside of signature scope, and the changed invalidate the signature.

Constructor & Destructor Documentation

◆ Signature() [1/2]

foxit.pdf.Signature.Signature ( Field  field)
inline

Constructor, with parent class object.

Parameters
[in]fieldParent class object.

◆ Signature() [2/2]

foxit.pdf.Signature.Signature ( PDFDoc  document,
PDFDictionary  sig_field_dict 
)
inline

Constructor, from signature field dictionary.

Parameters
[in]documentA valid PDF document.
[in]sig_field_dictA PDF dictionary which represents a signature field. It should belong to the PDF document specified by parameter document;

Member Function Documentation

◆ ClearSignedData()

bool foxit.pdf.Signature.ClearSignedData ( )
inline

Clear the data and appearance if current signature is singed and verified valid.

This function is used for a signed and valid signature.
Attention: From 7.0, this function is only used to verify the intergrity of a signature. To check if a signature is valid or not, please refer to class LTVVerifier .

Returns
true means clear the data and appearance successfully, while false means no need to clear data and appearance or any error.

◆ GetAppearanceFlags()

int foxit.pdf.Signature.GetAppearanceFlags ( )
inline

Get signature appearance flags.

Signature appearance flags indicate which information will be shown. Currently, this is only useful after Signature.SetAppearanceFlags is set successfully. For a signature gotten from PDF document, the return value of this function would be useless.

Returns
Signature appearance flags. Please refer to values starting from foxit.pdf.Signature.APFlags.e_APFlagFoxitFlag and this would be one or a combination of these values.

◆ GetBitmap()

System.Drawing.Bitmap foxit.pdf.Signature.GetBitmap ( )
inline

Get a bitmap which is used for the signature appearance.

Returns
The bitmap used in appearance. If the return value of function common.Bitmap.IsEmpty for the returned bitmap object is true, that means no bitmap is used in appearance or there is any error.

◆ GetByteRangeArray()

bool foxit.pdf.Signature.GetByteRangeArray ( int []  out_byte_range_array)
inline

Get the byte ranges data, including 4 elements.

This function is used for a signed signature to retrieve its byte range for digest calculation. The array of byte ranges contains 4 elements. These 4 elements are always in pairs of integers (starting byte offset, length in bytes), describing the exact byte range for the digest calculation.
Please refer to <PDF Reference 1.7> Section 8.7 Digital Signatures for more details.

Parameters
[out]out_byte_range_arrayOutput parameter that receives data of byte ranges. Please ensure this array can contain 4 elements.
Returns
true means success, while false means failure.

◆ GetCert()

string foxit.pdf.Signature.GetCert ( int  index)
inline

Get a certificate from current signature's certificate chain by index.

This function is recommended to be used before verifying a signature. When sub filter of current signature is "adbe.x509.rsa_sha1", application needs to call this function to get verified public certificate before verifying signature. The first certificate in certificate chain is the signing certificate, and it can be used to verify the signature.

Parameters
[in]indexThe index of certificate to be gotten. Valid range: from 0 to (count-1). count is returned by function Signature.GetCertCount .
Returns
A certificate.

◆ GetCertCount()

int foxit.pdf.Signature.GetCertCount ( )
inline

Get the count of certificates in current signature's certificate chain.

This function is recommended to be used before verifying a signature. When sub filter of current signature is "adbe.x509.rsa_sha1", application needs to call this function to get the count of certificates in certificate chain and then call function Signature.GetCert to get verified public certificate before verifying signature.

Returns
The count of certificates.

◆ GetCertificateInfo()

string foxit.pdf.Signature.GetCertificateInfo ( string  key)
inline

Get certificate information.

This function is used for a signed signature. Currently, this function only supports for iOS and android platform.

Parameters
[in]keyCertificate key string. Currently it can be one of the following keys:
  • "SerialNumber"

  • "Issuer"

  • "Subject"

  • "ValidPeriodFrom"

  • "ValidPeriodTo"

Returns
Certificate information string.
Note
For "ValidPeriodFrom" or "ValidPeriodTo" key, timezone value will not be computed in.

◆ GetDocument()

PDFDoc foxit.pdf.Signature.GetDocument ( )
inline

Get the PDF document, which current signature belongs to.

Returns
A PDF document object.

◆ GetFilter()

string foxit.pdf.Signature.GetFilter ( )
inline

Get filter.

Filter and sub filter are used to specify which registered signature callback object will be used to sign/verify current signature.

Returns
Filter string.

◆ GetKeyValue()

string foxit.pdf.Signature.GetKeyValue ( Signature.KeyName  key)
inline

Get the string value for specified key name.

This function is used to get string value of some key in signature dictionary, such as "Reason", "Location" and so on. Specially,

Parameters
[in]keyKey name. Please refer to values starting from foxit.pdf.Signature.KeyName.e_KeyNameSigner and this should be one of these values.
Returns
The string value.

◆ GetPAdESLevel()

Signature.PAdESLevel foxit.pdf.Signature.GetPAdESLevel ( )
inline

Get PAdES level.

Returns
PAdES level. Please refer to values starting from foxit.pdf.Signature.PAdESLevel.e_PAdESLevelNotPAdES and this would be one of these values.

◆ GetSignatureDict()

PDFDictionary foxit.pdf.Signature.GetSignatureDict ( )
inline

Get signature dictionary.

Signature dictionary is a part of signature field dictionary.

Returns
The signature dictionary.

◆ GetSignatureType()

Signature.SignatureType foxit.pdf.Signature.GetSignatureType ( )
inline

Get signature type.

Returns
Signature type. Please refer to values starting from foxit.pdf.Signature.SignatureType.e_SignatureTypeOrdinary and this would be one of these values.

◆ GetSignedVersionDocument()

PDFDoc foxit.pdf.Signature.GetSignedVersionDocument ( string  file_path)
inline

Get the PDF document in the signed version in which current signature was signed.

This function is useful when a PDF document has benn signed by serveral signatures and user wants to get the PDF document in which one signature is signed.

Parameters
[in]file_pathThe full path of the original opened PDF document which current signature belongs to. It should not be an empty string.
Returns
A PDF document object in singed version in which current signature was signed. The returned PDF document may represent a differenct PDF document from current PDF document where current signature is retrieved., or is just current PDF document. User should ensure to keep current PDF document object valid when reading or operating signed version document. Please ensure the returned document object has been loaded successfully, before using most functions in class PDFDoc .

◆ GetSignTime()

DateTime foxit.pdf.Signature.GetSignTime ( )
inline

Get time of signing.

Returns
A date and time object that receives the signing time. If no signing time is found, this function will return a date and time object with all values 0.

◆ GetState()

uint foxit.pdf.Signature.GetState ( )
inline

Get current state.

  • Before verifying a signature, this function is to get the state about if current signature is signed or if current signature is lack of data for signing.

  • After verifying a signature, this function is to get the verified state – which indicates that the verified signature is signed; if the verified signature is still unsigned, this function will get the unsigned state instead.

Returns
The value of signature state. Please refer to values starting from foxit.pdf.Signature.States.e_StateUnknown and this would be one or combination of them.
Specially, if the returned state is foxit.pdf.Signature.States.e_StateNoSignData , that means current signature has no data for signing, and please at least call function Signature.SetKeyValue to set necessary filter and sub filter to current signature. Use can also call following functions to set other data for signing and signed appearance before calling function Signature.StartSign :

◆ GetSubFilter()

string foxit.pdf.Signature.GetSubFilter ( )
inline

Get sub filter.

Filter and sub filter are used to specify which registered signature callback object will be used to sign/verify current signature.

Returns
Sub filter string.

◆ IsEmpty()

new bool foxit.pdf.Signature.IsEmpty ( )
inline

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
true means current object is empty, while false means not.

◆ IsSigned()

bool foxit.pdf.Signature.IsSigned ( )
inline

Check whether current signature is signed or not.

Returns
true means current signature is signed, and false means not.

◆ IsTimeStamp()

bool foxit.pdf.Signature.IsTimeStamp ( )
inline

Check if current signature is a time stamp signature.

Returns
true means current signature is a time stamp signature, while false means not.

◆ SetAppearanceContent()

void foxit.pdf.Signature.SetAppearanceContent ( string  appearance_content)
inline

Set customized appearance content (as low level drawing operation commands) for signed signature appearance.

This function can only be used for an unsigned signature before calling function Signature.StartSign for the unsigned signature.
Once customized appearance content is set, it will be used as the signed appearance. In this case, appearance flags set by Signature.SetAppearanceFlags will be ignored and related informations will not be used in appearance – these information are set by: Signature.SetSignTime , Signature.SetKeyValue (except filter and sub-filter), Signature.SetBitmap , Signature.SetImage .
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]appearance_contentCustomized appearance content. This should be sequence of drawing operation commands to be used for the appearance, for example "10 10 m 20 10 l S". Please refer to <PDF Reference 1.7> P196 for more details.
Returns
None.

◆ SetAppearanceFlags()

void foxit.pdf.Signature.SetAppearanceFlags ( int  appearance_flags)
inline

Set signature appearance flags.

This function is recommended to be used before calling function Signature.StartSign for an unsigned signature.
Signature appearance flags indicate which information will be shown in the signed appearance. If customized appearance content has been set by function Signature.SetAppearanceContent , appearance flags will be ignored.
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]appearance_flagsSignature appearance flags. Please refer to values starting from foxit.pdf.Signature.APFlags.e_APFlagFoxitFlag and this should be one or a combination of these values.
Returns
None.

◆ SetBitmap()

void foxit.pdf.Signature.SetBitmap ( System.Drawing.Bitmap  bitmap)
inline

Set a bitmap for the signature appearance.

This function is recommended to be used before calling function Signature.StartSign for an unsigned signature. If customized appearance content has been set by function Signature.SetAppearanceContent , the bitmap will not be used in signed appearance.
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]bitmapA bitmap to be set to the appearance. It should be valid.
Returns
None.

◆ SetCertChain()

void foxit.pdf.Signature.SetCertChain ( WStringArray  cert_chain)
inline

Set a certificate chain.

This function is recommended to be used before signing an unsigned signature. When the signature sub filter is "adbe.x509.rsa_sha1", users need to call this function to set the cert chain to the signature. For other sub filter, this function will return directly without doing anything.

Parameters
[in]cert_chainA string array that represents the certificate chain.
Returns
None.

◆ SetDefaultContentsLength()

void foxit.pdf.Signature.SetDefaultContentsLength ( int  default_length)
inline

Set the default length of signature contents which represents signature value (known as signed data).

This function can only be used before function Signature.StartSign for an unsigned signature.
Signature contents represent the signature value (known as signed data). When initializing the signature field, the signature contents will be initialized with the default length 7942. When using custom signature callback to sign and verify an unsigned signature, user can call this function to change the default length of signature contents. In this case, user should also ensure that the length of returned signed data in callback function SignatureCallback.Sign should not be larger than the default length set by this function.

Parameters
[in]default_lengthThe default length of the signature value (known as signed data), in bytes. It should not be less than 4098.
Returns
None.

◆ SetFilter()

void foxit.pdf.Signature.SetFilter ( string  filter)
inline

Set filter.

Filter and sub filter are used to specify which registered signature callback object will be used to sign/verify current signature. User could should set filter and sub filter to use default signature callback in Foxit PDF SDK, or use other filter and sub fitler but please ensure that a signature callback object with non-default filter and sub filter should has been registered in Foxit PDF SDK before signing or verifying current signature. Filter and sub filter for default signature callback are:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

Parameters
[in]filterString for filter. It cannot be an empty string.
Returns
None.

◆ SetImage() [1/2]

void foxit.pdf.Signature.SetImage ( Image  image,
int  frame_index 
)
inline

Set an image for the signature appearance, with a specified frame index.

This function is recommended to be used before calling function Signature.StartSign for an unsigned signature. If customized appearance content has been set by function Signature.SetAppearanceContent , the image will not be used in signed appearance.
Input image may contain multiple frames, and only one frame of the image can be set to current signature.
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]imageAn image. One of its frames will be set to current signature. This image contains at least one frame and the image type should not be foxit.common.Image.Type.e_Unknown .
[in]frame_indexFrame index. Valid range: from 0 to (count-1). count is returned by function common.Image.GetFrameCount .
Returns
None.

◆ SetImage() [2/2]

void foxit.pdf.Signature.SetImage ( string  file_path,
int  frame_index 
)
inline

Set an image for the signature appearance, with a specified frame index.

This function is recommended to be used before calling function Signature.StartSign for an unsigned signature. If customized appearance content has been set by function Signature.SetAppearanceContent , the image will not be used in signed appearance.
Input image may contain multiple frames, and only one frame of the image can be set to current signature.
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]file_pathA full path of an existing image file. It should not be an empty string.
[in]frame_indexFrame index. Valid range: from 0 to (count-1). count is returned by function common.Image.GetFrameCount of input image file.
Returns
None.

◆ SetKeyValue()

void foxit.pdf.Signature.SetKeyValue ( Signature.KeyName  key,
string  value 
)
inline

Set the string value for specified key name.

This function is recommended to be used before calling function Signature.StartSign for an unsigned signature.
This function is used to set string value of some key in signature dictionary, such as signer, reason, location and so on.
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]keyKey name. Please refer to values starting from foxit.pdf.Signature.KeyName.e_KeyNameSigner and this should be one of these values.
[in]valueNew string value.
Returns
None.

◆ SetSignTime()

void foxit.pdf.Signature.SetSignTime ( DateTime  sign_time)
inline

Set time of signing.

This function is recommended to be used before calling function Signature.StartSign for an unsigned signature.

Parameters
[in]sign_timeThe signing time.
Returns
None.

◆ SetSubFilter()

void foxit.pdf.Signature.SetSubFilter ( string  sub_filter)
inline

Set sub filter.

Filter and sub filter are used to specify which registered signature callback object will be used to sign/verify current signature. User could should set filter and sub filter to use default signature callback in Foxit PDF SDK, or use other filter and sub fitler but please ensure that a signature callback object with non-default filter and sub filter should has been registered in Foxit PDF SDK before signing or verifying current signature. Filter and sub filter for default signature callback are:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

Parameters
[in]sub_filterString for sub filter.
Returns
None.

◆ StartSign() [1/4]

Progressive foxit.pdf.Signature.StartSign ( string  cert_path,
byte []  cert_password,
Signature.DigestAlgorithm  digest_algorithm,
string  save_path,
global::System.IntPtr  client_data,
PauseCallback  pause 
)
inline

Start signing current signature if current signature is unsigned.

This function is used for an unsigned signature. Filter and sub filter keys of current signature specify the name of signature callback object which will be used to sign current signature. So before signing, please ensure current signature has valid filter and sub filter string values. If the filter and sub filter are one of following strings that means to use the default signature callback in Foxit PDF SDK:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

For other filter and sub filter or if user wants to use customized signature callback for above filter and sub filter, please ensure a customized signature callback has been registered to Foxit PDF SDK by function common.Library.RegisterSignatureCallback .
It may take a long time to sign a signature, so Foxit PDF SDK uses a progressive process to do this.

Parameters
[in]cert_pathA full path of a certificate file (including file name and extension), which will be used for signing. This can be an empty string if not necessary in custom signature callback. When this file path is not empty, it should be a valid path.
If default signature callback is to be used for signing current signature, this can be a PFX certificate file.
[in]cert_passwordA password string used to open the cert file. If this is an empty string, that means no password is required.
[in]digest_algorithmThe algorithm of message digest for signed data. Please refer to values starting from foxit.pdf.Signature.DigestAlgorithm.e_DigestSHA1 and this should be one of these values.
[in]save_pathA full PDF file path for saving the signing result. The signed document would be saved to another PDF file.
[in]client_dataA user-defined object, which will be passed to call back functions in SignatureCallback . This is useless if the default callback object will be used to sign current signature.
[in]pausePause object which decides if the signing process needs to be paused. This can be null which means not to pause during the signing process. If this is not null, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function common.Progressive.GetRateOfProgress . If the rate is not 100 yet, call function common.Progressive.Continue to coninue the progress until the progress is finished.
Note
This function does not support to save signed PDF document directly to the PDF file which is used to construct the related PDF document of current signature. In order to do so, user is recommended to do as following steps:
Assume that the related PDF document object is constructed from a PDF file named "org.pdf".
  1. Use current function to save the signed result to an temporary file. Here, this temporary file is named as "temp.tmp".

  2. Ensure that the related PDF document object has destructed – which is equal to "close document".

  3. Remove "org.pdf" and rename "temp.tmp" to "org.pdf".

Then user can open the signed PDF document to do other operation.

◆ StartSign() [2/4]

Progressive foxit.pdf.Signature.StartSign ( StreamCallback  cert_file_stream,
byte []  cert_password,
Signature.DigestAlgorithm  digest_algorithm,
string  save_path,
global::System.IntPtr  client_data,
PauseCallback  pause 
)
inline

Start signing current signature if current signature is unsigned.

This function is used for an unsigned signature. Filter and sub filter keys of current signature specify the name of signature callback object which will be used to sign current signature. So before signing, please ensure current signature has valid filter and sub filter string values. If the filter and sub filter are one of following strings that means to use the default signature callback in Foxit PDF SDK:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

For other filter and sub filter or if user wants to use customized signature callback for above filter and sub filter, please ensure a customized signature callback has been registered to Foxit PDF SDK by function common.Library.RegisterSignatureCallback .
It may take a long time to sign a signature, so Foxit PDF SDK uses a progressive process to do this.

Parameters
[in]cert_file_streamA foxit.common.fxcrt.StreamCallback object which is implemented by user to access content of a certificate file which will be used for signing. This can be null if not necessary in custom signature callback.
If default signature callback is to be used for signing current signature, a PFX certificate file can be used.
[in]cert_passwordA password string used to open the cert file. If this is an empty string, that means no password is required.
[in]digest_algorithmThe algorithm of message digest for signed data. Please refer to values starting from foxit.pdf.Signature.DigestAlgorithm.e_DigestSHA1 and this should be one of these values.
[in]save_pathA full PDF file path for saving the signing result. The signed document would be saved to another PDF file.
[in]client_dataA user-defined object, which will be passed to call back functions in SignatureCallback . This is useless if the default callback object will be used to sign current signature.
[in]pausePause object which decides if the signing process needs to be paused. This can be null which means not to pause during the signing process. If this is not null, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function common.Progressive.GetRateOfProgress . If the rate is not 100 yet, call function common.Progressive.Continue to coninue the progress until the progress is finished.
Note
This function does not support to save signed PDF document directly to the PDF file which is used to construct the related PDF document of current signature. In order to do so, user is recommended to do as following steps:
Assume that the related PDF document object is constructed from a PDF file named "org.pdf".
  1. Use current function to save the signed result to an temporary file. Here, this temporary file is named as "temp.tmp".

  2. Ensure that the related PDF document object has destructed – which is equal to "close document".

  3. Remove "org.pdf" and rename "temp.tmp" to "org.pdf".

Then user can open the signed PDF document to do other operation.

◆ StartSign() [3/4]

Progressive foxit.pdf.Signature.StartSign ( string  cert_path,
byte []  cert_password,
Signature.DigestAlgorithm  digest_algorithm,
StreamCallback  stream_callback,
global::System.IntPtr  client_data,
PauseCallback  pause 
)
inline

Start signing current signature if current signature is unsigned.

This function is used for an unsigned signature. Filter and sub filter keys of current signature specify the name of signature callback object which will be used to sign current signature. So before signing, please ensure current signature has valid filter and sub filter string values. If the filter and sub filter are one of following strings that means to use the default signature callback in Foxit PDF SDK:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

For sub filter "ETSI.CAdES.detached" and sub filter "ETSI.RFC3161", please ensure a default time stmap server has been set to TimeStampServerMgr if default signature callbacks for them will be used to do signing. For other filter and sub filter or if user wants to use customized signature callback for above filter and sub filter, please ensure a customized signature callback has been registered to Foxit PDF SDK by function common.Library.RegisterSignatureCallback .
It may take a long time to sign a signature, so Foxit PDF SDK uses a progressive process to do this.

Parameters
[in]cert_pathA full path of a certificate file (including file name and extension), which will be used for signing. This can be an empty string if not necessary in custom signature callback. When this file path is not empty, it should be a valid path.
If default signature callback is to be used for signing current signature, this can be a PFX certificate file.
[in]cert_passwordA password string used to open the cert file. If this is an empty string, that means no password is required.
[in]digest_algorithmThe algorithm of message digest for signed data. Please refer to values starting from foxit.pdf.Signature.DigestAlgorithm.e_DigestSHA1 and this should be one of these values.
[in]stream_callbackA foxit.common.fxcrt.StreamCallback object which is implemented by user to save the signing result. The signed document would be saved to another PDF file.
[in]client_dataA user-defined object, which will be passed to call back functions in SignatureCallback . This is useless if the default callback object will be used to sign current signature.
[in]pausePause object which decides if the signing process needs to be paused. This can be null which means not to pause during the signing process. If this is not null, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function common.Progressive.GetRateOfProgress . If the rate is not 100 yet, call function common.Progressive.Continue to coninue the progress until the progress is finished.
Note
This function does not support to save signed PDF document directly to the PDF file which is used to construct the related PDF document of current signature. In order to do so, user is recommended to do as following steps:
Assume that the related PDF document object is constructed from a PDF file named "org.pdf".
  1. Use current function to save the signed result to an temporary file. Here, this temporary file is named as "temp.tmp".

  2. Ensure that the related PDF document object has destructed – which is equal to "close document".

  3. Remove "org.pdf" and rename "temp.tmp" to "org.pdf".

Then user can open the signed PDF document to do other operation.

◆ StartSign() [4/4]

Progressive foxit.pdf.Signature.StartSign ( StreamCallback  cert_file_stream,
byte []  cert_password,
Signature.DigestAlgorithm  digest_algorithm,
StreamCallback  stream_callback,
global::System.IntPtr  client_data,
PauseCallback  pause 
)
inline

Start signing current signature if current signature is unsigned.

This function is used for an unsigned signature. Filter and sub filter keys of current signature specify the name of signature callback object which will be used to sign current signature. So before signing, please ensure current signature has valid filter and sub filter string values. If the filter and sub filter are one of following strings that means to use the default signature callback in Foxit PDF SDK:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

For sub filter "ETSI.CAdES.detached" and sub filter "ETSI.RFC3161", please ensure a default time stmap server has been set to TimeStampServerMgr if default signature callbacks for them will be used to do signing. For other filter and sub filter or if user wants to use customized signature callback for above filter and sub filter, please ensure a customized signature callback has been registered to Foxit PDF SDK by function common.Library.RegisterSignatureCallback .
It may take a long time to sign a signature, so Foxit PDF SDK uses a progressive process to do this.

Parameters
[in]cert_file_streamA foxit.common.fxcrt.StreamCallback object which is implemented by user to access content of a certificate file which will be used for signing. This can be null if not necessary in custom signature callback.
If default signature callback is to be used for signing current signature, a PFX certificate file can be used.
[in]cert_passwordA password string used to open the cert file. If this is an empty string, that means no password is required.
[in]digest_algorithmThe algorithm of message digest for signed data. Please refer to values starting from foxit.pdf.Signature.DigestAlgorithm.e_DigestSHA1 and this should be one of these values.
[in]stream_callbackA foxit.common.fxcrt.StreamCallback object which is implemented by user to save the signing result. The signed document would be saved to another PDF file.
[in]client_dataA user-defined object, which will be passed to call back functions in SignatureCallback . This is useless if the default callback object will be used to sign current signature.
[in]pausePause object which decides if the signing process needs to be paused. This can be null which means not to pause during the signing process. If this is not null, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function common.Progressive.GetRateOfProgress . If the rate is not 100 yet, call function common.Progressive.Continue to coninue the progress until the progress is finished.
Note
This function does not support to save signed PDF document directly to the PDF file which is used to construct the related PDF document of current signature. In order to do so, user is recommended to do as following steps:
Assume that the related PDF document object is constructed from a PDF file named "org.pdf".
  1. Use current function to save the signed result to an temporary file. Here, this temporary file is named as "temp.tmp".

  2. Ensure that the related PDF document object has destructed – which is equal to "close document".

  3. Remove "org.pdf" and rename "temp.tmp" to "org.pdf".

Then user can open the signed PDF document to do other operation.

◆ StartVerify()

Progressive foxit.pdf.Signature.StartVerify ( global::System.IntPtr  client_data,
PauseCallback  pause 
)
inline

Start verifying the intergrity of current signature if current signature is signed.

This function is used for a signed signature. Filter and sub filter keys of current signature specify the name of signature callback object which will be used to verify current signature. So before verifying, please ensure: the necessary signature callback object has been registered by function common.Library.RegisterSignatureCallback . If the filter and sub filter of current signed signature are one of following strings that means to use the default signature callback in Foxit PDF SDK and user does not need to register one for them:

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.detached"

  • filter: "Adobe.PPKLite" and sub filter: "adbe.pkcs7.sha1"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.CAdES.detached"

  • filter: "Adobe.PPKLite" and sub filter: "ETSI.RFC3161"

It may take a long time to verify a signature, so Foxit PDF SDK uses a progressive process to do this.
From 7.0, this function is only used to verify the intergrity of a signature. To check if a signature is valid or not, please refer to class LTVVerifier .

Parameters
[in]client_dataA user-defined object, which will be passed to call back functions in SignatureCallback . This is useless if the default callback object will be used to verify current signature.
[in]pausePause object which decides if the verifying process needs to be paused. This can be null which means not to pause during the verifying process. If this is not null, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function common.Progressive.GetRateOfProgress . If the rate is not 100 yet, call function common.Progressive.Continue to coninue the progress until the progress is finished.