Foxit PDF SDK
FSSignature Class Reference
Inheritance diagram for FSSignature:
FSField FSBase

Instance Methods

(BOOL) - clearSignedData
 Clear the data and appearance if current signature is singed and verified valid.
More...
 
(FSInt32Array *) - getByteRangeArray
 Get the byte ranges data, including 4 elements.
More...
 
(NSString *) - getCert:
 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...
 
(NSString *) - getCertificateInfo:
 Get certificate information.
More...
 
(FSPDFDoc *) - getDocument
 Get the PDF document, which current signature belongs to.
More...
 
(FSSignatureFieldMDPAction- getFieldMDPAction
 Get FieldMDP("MDP" means modification detection and prevention) action type.
More...
 
(NSArray< NSString * > *) - getFieldMDPActionFields
 Get the field name array which is used for FieldMDP action.
More...
 
(NSString *) - getKeyLabel:
 Get the string for specified key label.
More...
 
(NSString *) - getKeyValue:
 Get the string value for specified key name.
More...
 
(FSSignaturePAdESLevel- getPAdESLevel
 Get PAdES level.
More...
 
(FSPDFDictionary *) - getSignatureDict
 Get signature dictionary.
More...
 
(FSSignatureSignatureType- getSignatureType
 Get signature type.
More...
 
(FSPDFDoc *) - getSignedVersionDocument:
 Get the PDF document in the signed version in which current signature was signed.
More...
 
(unsigned int) - getState
 Get current state.
More...
 
(id) - initWithDocument:sig_field_dict:
 Constructor, from signature field dictionary.
More...
 
(id) - initWithField:
 Constructor, with parent class object.
More...
 
(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:
 Set customized appearance content (as low level drawing operation commands) for signed signature appearance.
More...
 
(void) - setCertChain:
 Set a certificate chain.
More...
 
(void) - setDefaultContentsLength:
 Set the default length of signature contents which represents signature value (known as signed data).
More...
 
(void) - setFieldMDPActionFields:field_array:
 Set FieldMDP("MDP" means modification detection and prevention) action names array.
More...
 
(void) - setImage:frame_index:
 Set an image for the signature appearance, with a specified frame index.
More...
 
(void) - setImageWithFilePath:frame_index:
 Set an image for the signature appearance, with a specified frame index.
More...
 
(void) - setKeyLabel:label_value:
 Set the string for specified key label.
More...
 
(void) - setKeyValue:value:
 Set the string value for specified key name.
More...
 
(FSProgressive *) - startSign:cert_password:digest_algorithm:save_path:client_data:pause:
 Start signing current signature if current signature is unsigned.
More...
 
(FSProgressive *) - startSignWithCertFileStreamCallback:cert_password:digest_algorithm:stream_callback:client_data:pause:
 Start signing current signature if current signature is unsigned.
More...
 
(FSProgressive *) - startSignWithStreamCallback:cert_password:digest_algorithm:stream_callback:client_data:pause:
 Start signing current signature if current signature is unsigned.
More...
 
(FSProgressive *) - startVerify:pause:
 Start verifying the intergrity of current signature if current signature is signed.
More...
 
- Instance Methods inherited from FSField
(FSControl *) - getControl:
 Get a form control by index.
More...
 
(int) - getControlCount
 Get count of form controls.
More...
 
(int) - getControlCountWithPDFPage:
 Get count of form controls in a specified PDF page.
More...
 
(FSControl *) - getControlWithPDFPage:index:
 Get a form control by index, in a specified PDF page.
More...
 
(FSPDFObject *) - getDefaultValueObj
 Get the PDF object of field's default value.
More...
 
(FSPDFDictionary *) - getDict
 Get the PDF dictionary of current object.
More...
 
(FSPDFObject *) - getInheritedAttribute:
 Get the PDF object for specified attribute which may be inherited from the ancestor node in the field tree.
More...
 
(NSString *) - getName
 Get field name.
More...
 
(FSFieldType- getType
 Get field type.
More...
 
(FSPDFObject *) - getValueObj
 Get the PDF object of field's value.
More...
 
(id) - initWithDocument:field_dict:
 Constructor, from field dictionary.
More...
 
(BOOL) - reset
 Reset data in current field to its default value. (Not support signature field)
More...
 

Properties

unsigned int appearanceFlags
 Get or Set signature appearance flags.
More...
 
FSBitmapbitmap
 Get or Set a bitmap which is used for the signature appearance.

 
FSSignatureDocPermission docPermission
 Get or Set document permission for current signature.
More...
 
NSString * filter
 Get or Set filter.
More...
 
FSDateTimesignTime
 Get or Set time of signing.

 
NSString * subFilter
 Get or Set sub filter.
More...
 
- Properties inherited from FSField
FSAlignment alignment
 Get or Set the alignment value.
More...
 
NSString * alternateName
 Get or Set alternate name.
More...
 
FSDefaultAppearancedefaultAppearance
 Get or Set the default appearance data.

 
NSString * defaultValue
 Get or Set default value.
More...
 
unsigned int flags
 Get or Set field flags.
More...
 
NSString * mappingName
 Get or Set mapping name.
More...
 
int maxLength
 Get or Set maximum length of the field's text, in characters.
More...
 
FSChoiceOptionArrayoptions
 Get or Set options of list box or combo box.
More...
 
int topVisibleIndex
 Get or Set top index of option for scrollable list boxes.
More...
 
NSString * value
 Get or 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 FSSignature is derived from class FSField. 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 FSTimeStampServerMgr 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 FSLibrary::registerSignatureCallback:sub_filter:signature_callback:.
This class offers functions to get/set signature information/properties, sign or verify a signature, and so on. For example:

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
FSField
FSForm
FSPDFDoc
FSPDFPage
FSTimeStampServerMgr
FSLTVVerifier

Method Documentation

◆ clearSignedData()

- (BOOL) clearSignedData

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

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

◆ getByteRangeArray()

- (FSInt32Array *) getByteRangeArray

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.

Returns
YES means success, while NO means failure.

◆ getCert:()

- (NSString *) getCert: (int)  index

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 FSSignature::getCertCount.
Returns
A certificate.

◆ getCertCount()

- (int) getCertCount

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 FSSignature::getCert: to get verified public certificate before verifying signature.

Returns
The count of certificates.

◆ getCertificateInfo:()

- (NSString *) getCertificateInfo: (NSString *)  key

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()

- (FSPDFDoc *) getDocument

Get the PDF document, which current signature belongs to.

Returns
A PDF document object.

◆ getFieldMDPAction()

- (FSSignatureFieldMDPAction) getFieldMDPAction

Get FieldMDP("MDP" means modification detection and prevention) action type.

Returns
FieldMDP action type. Please refer to values starting from FSSignatureFieldMDPActionNone and this should be one of these values.

◆ getFieldMDPActionFields()

- (NSArray< NSString * > *) getFieldMDPActionFields

Get the field name array which is used for FieldMDP action.

Returned field name array is associated to the FieldMDP action (which can be checked by function FSSignature::getFieldMDPAction):

  • If FieldMDP action type is FSSignatureFieldMDPActionNone, returned field name array is uselss.
  • If FieldMDP action type is FSSignatureFieldMDPActionAll, returned field name array will contain name of all form fields.
  • If FieldMDP action type is FSSignatureFieldMDPActionInclude, returned field name array specifies form fields whose flags are read-only when current signature is signed.
  • If FieldMDP action type is FSSignatureFieldMDPActionExclude, returned field name array specifies form fields whose flags are not read-only (but rest fields' flags are read-only) when current signature is a signed signature.


Returns
FieldMDP action field name array.

◆ getKeyLabel:()

- (NSString *) getKeyLabel: (FSSignatureLabelName label_name

Get the string for specified key label.

If current signature is a time stamp signature, this function will always return an empty string.

Parameters
[in]label_nameKey label. Please refer to values starting from FSSignatureLabelNameSigner and this should be one of these values.
Returns
String for specified key label.

◆ getKeyValue:()

- (NSString *) getKeyValue: (FSSignatureKeyName key

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 FSSignatureKeyNameSigner and this should be one of these values.
Returns
The string value.

◆ getPAdESLevel()

- (FSSignaturePAdESLevel) getPAdESLevel

Get PAdES level.

Returns
PAdES level. Please refer to values starting from FSSignaturePAdESLevelNotPAdES and this would be one of these values.

◆ getSignatureDict()

- (FSPDFDictionary *) getSignatureDict

Get signature dictionary.

Signature dictionary is a part of signature field dictionary.

Returns
The signature dictionary.

◆ getSignatureType()

- (FSSignatureSignatureType) getSignatureType

Get signature type.

Returns
Signature type. Please refer to values starting from FSSignatureSignatureTypeOrdinary and this would be one of these values.

◆ getSignedVersionDocument:()

- (FSPDFDoc *) getSignedVersionDocument: (NSString *)  file_path

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

◆ getState()

- (unsigned int) getState

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 FSSignatureStateUnknown and this would be one or combination of them.
Specially, if the returned state is FSSignatureStateNoSignData, that means current signature has no data for signing, and please at least call function FSSignature::setKeyValue:value: 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 FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause::

◆ initWithDocument:sig_field_dict:()

- (id) initWithDocument: (FSPDFDoc*)  document
sig_field_dict: (FSPDFDictionary*)  sig_field_dict 

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;

◆ initWithField:()

- (id) initWithField: (FSField*)  field

Constructor, with parent class object.

Parameters
[in]fieldParent class object.

Reimplemented from FSField.

◆ isEmpty()

- (BOOL) isEmpty

Check whether current object is empty or not.

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

Returns
YES means current object is empty, while NO means not.

Reimplemented from FSField.

◆ isSigned()

- (BOOL) isSigned

Check whether current signature is signed or not.

Returns
YES means current signature is signed, and NO means not.

◆ isTimeStamp()

- (BOOL) isTimeStamp

Check if current signature is a time stamp signature.

Returns
YES means current signature is a time stamp signature, while NO means not.

◆ setAppearanceContent:()

- (void) setAppearanceContent: (NSString *)  appearance_content

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 FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: 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 FSSignature::appearanceFlags will be ignored and related informations will not be used in appearance – these information are set by: FSSignature::signTime, FSSignature::setKeyValue:value: (except filter and sub-filter), FSSignatureFillSignObject::setBitmap:, FSSignature::setImage:frame_index:.
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.

◆ setCertChain:()

- (void) setCertChain: (NSArray<NSString *> *)  cert_chain

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) setDefaultContentsLength: (unsigned int)  default_length

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

This function can only be used before function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: 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 FSSignatureCallback::sign:cert_path:cert_password:digest_algorithm:client_data: 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.

◆ setFieldMDPActionFields:field_array:()

- (void) setFieldMDPActionFields: (FSSignatureFieldMDPAction action
field_array: (NSArray<NSString *> *)  field_array 

Set FieldMDP("MDP" means modification detection and prevention) action names array.

This function is only useful for an unsigned signature. If this function is used for a signed signature, nothing will be done.
If current signature is signed, this function is invalidate.

Parameters
[in]actionFieldMDP action type.Please refer to values starting from FSSignatureFieldMDPActionNone and this should be one of these values.
  • If this value is FSSignatureFieldMDPActionNone, that means no FieldMDP action will be used.
  • If this value is FSSignatureFieldMDPActionAll, parameter field_array will be ignored and all fields will be included in the object digest (and hence do not permit changes after current signature is signed).
  • If this value is FSSignatureFieldMDPActionInclude, that means only flags of form fields specified by parameter field_array will be set read-only and these fields will be included in the object digest (and hence do not permit changes after current signature is signed).
  • If this value is FSSignatureFieldMDPActionExclude, that means flags of form fields (except those specified by parameter field_array) will be set read-only and these fields are included in the object digest (and hence do not permit changes after current signature is signed).

[in]field_arrayA field name array used for FieldMDP action.
Returns
None.

◆ setImage:frame_index:()

- (void) setImage: (FSImage*)  image
frame_index: (int)  frame_index 

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

This function is recommended to be used before calling function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: for an unsigned signature. If customized appearance content has been set by function FSSignature::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 FSImageUnknown.
[in]frame_indexFrame index. Valid range: from 0 to (count-1). count is returned by function FSImage::getFrameCount.
Returns
None.

◆ setImageWithFilePath:frame_index:()

- (void) setImageWithFilePath: (NSString *)  file_path
frame_index: (int)  frame_index 

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

This function is recommended to be used before calling function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: for an unsigned signature. If customized appearance content has been set by function FSSignature::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 FSImage::getFrameCount of input image file.
Returns
None.

◆ setKeyLabel:label_value:()

- (void) setKeyLabel: (FSSignatureLabelName label_name
label_value: (NSString *)  label_value 

Set the string for specified key label.

This function is recommended to be used before calling function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: for an unsigned signature.
This function is used to set string value for custom label of some key in signature dictionary. If no custom label is set, default labels will be used by Foxit PDF SDK. Please refer to comment of values starting from FSSignatureLabelNameSigner for more details.
If current signature is a time stamp signature, this function will do nothing.

Parameters
[in]label_nameKey label. Please refer to values starting from FSSignatureLabelNameSigner and this should be one of these values.
[in]label_valueNew string value for key label. If this is an empty string, Foxit PDF SDK will use default label. Please refer to comment of values starting from FSSignatureLabelNameSigner for more details.
Returns
None.

◆ setKeyValue:value:()

- (void) setKeyValue: (FSSignatureKeyName key
value: (NSString *)  value 

Set the string value for specified key name.

This function is recommended to be used before calling function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: 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 FSSignatureKeyNameSigner and this should be one of these values.
[in]valueNew string value.
Returns
None.

◆ startSign:cert_password:digest_algorithm:save_path:client_data:pause:()

- (FSProgressive *) startSign: (NSString *)  cert_path
cert_password: (NSString *)  cert_password
digest_algorithm: (FSSignatureDigestAlgorithm digest_algorithm
save_path: (NSString *)  save_path
client_data: (NSData *)  client_data
pause: (id<FSPauseCallback>)  pause 

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 FSLibrary::registerSignatureCallback:sub_filter:signature_callback:.
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 FSSignatureDigestSHA1 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 FSSignatureCallback . 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 nil which means not to pause during the signing process. If this is not nil, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function FSProgressive::getRateOfProgress. If the rate is not 100 yet, call function FSProgressive::resume 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.

◆ startSignWithCertFileStreamCallback:cert_password:digest_algorithm:stream_callback:client_data:pause:()

- (FSProgressive *) startSignWithCertFileStreamCallback: (id<FSFileStreamCallback>)  cert_file_stream
cert_password: (NSString *)  cert_password
digest_algorithm: (FSSignatureDigestAlgorithm digest_algorithm
stream_callback: (id<FSFileStreamCallback>)  stream_callback
client_data: (NSData *)  client_data
pause: (id<FSPauseCallback>)  pause 

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 FSTimeStampServerMgr 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 FSLibrary::registerSignatureCallback:sub_filter:signature_callback:.
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 FSFileStreamCallback object which is implemented by user to access content of a certificate file which will be used for signing. This can be nil 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 FSSignatureDigestSHA1 and this should be one of these values.
[in]stream_callbackA FSFileStreamCallback 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 FSSignatureCallback . 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 nil which means not to pause during the signing process. If this is not nil, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function FSProgressive::getRateOfProgress. If the rate is not 100 yet, call function FSProgressive::resume 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.

◆ startSignWithStreamCallback:cert_password:digest_algorithm:stream_callback:client_data:pause:()

- (FSProgressive *) startSignWithStreamCallback: (NSString *)  cert_path
cert_password: (NSString *)  cert_password
digest_algorithm: (FSSignatureDigestAlgorithm digest_algorithm
stream_callback: (id<FSFileStreamCallback>)  stream_callback
client_data: (NSData *)  client_data
pause: (id<FSPauseCallback>)  pause 

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 FSTimeStampServerMgr 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 FSLibrary::registerSignatureCallback:sub_filter:signature_callback:.
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 FSSignatureDigestSHA1 and this should be one of these values.
[in]stream_callbackA FSFileStreamCallback 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 FSSignatureCallback . 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 nil which means not to pause during the signing process. If this is not nil, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function FSProgressive::getRateOfProgress. If the rate is not 100 yet, call function FSProgressive::resume 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:pause:()

- (FSProgressive *) startVerify: (NSData *)  client_data
pause: (id<FSPauseCallback>)  pause 

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 FSLibrary::registerSignatureCallback:sub_filter:signature_callback:. 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 FSLTVVerifier .

Parameters
[in]client_dataA user-defined object, which will be passed to call back functions in FSSignatureCallback . 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 nil which means not to pause during the verifying process. If this is not nil, it should be a valid pause object implemented by user.
Returns
A progressive object. Please check the rate of current progress by function FSProgressive::getRateOfProgress. If the rate is not 100 yet, call function FSProgressive::resume to coninue the progress until the progress is finished.

Property Documentation

◆ appearanceFlags

- (unsigned int) appearanceFlags
readwritenonatomicassign

Get or Set signature appearance flags.

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

◆ docPermission

- (FSSignatureDocPermission) docPermission
readwritenonatomicassign

Get or Set document permission for current signature.


◆ filter

- (NSString *) filter
readwritenonatomicweak

Get or Set filter.

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

◆ subFilter

- (NSString *) subFilter
readwritenonatomicweak

Get or Set sub filter.

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