SignDoc SDK (.NET with exceptions)  5.0.3.5
Public Member Functions | Static Public Member Functions | List of all members
SignDocSignatureParameters Class Reference

Parameters for signing a document. More...

Public Member Functions

 ~SignDocSignatureParameters ()
 Destructor. More...
 
 SignDocSignatureParameters ()
 Constructor. More...
 
SignDocSignatureParameters clone (bool aStartKeyGenerator)
 Clone this object. More...
 
void loadFromMemory (byte[] aBlob, ParametersLoadFlags aFlags)
 Load a SignDocSignatureParameters object from a blob (deserialize). More...
 
byte[] saveToMemory (ParametersSaveFlags aFlags)
 Serialize this object to a blob. More...
 
void setBoolean (string aName, bool aValue)
 Set a boolean parameter. More...
 
void setString (string aName, string aValue)
 Set a string parameter. More...
 
void setInteger (string aName, int aValue)
 Set an integer parameter. More...
 
void setBlob (string aName, byte[] aValue)
 Set a blob parameter. More...
 
void setLength (string aName, LengthType aType, double aValue)
 Set a length parameter. More...
 
void setColor (string aName, SignDocColor aValue)
 Set a color parameter. More...
 
void addTextItem (string aItem, TextGroup aGroup)
 Add another string to be displayed, top down. More...
 
void addTextItem2 (string aItem, TextGroup aGroup, SignatureParametersHAlignment aHAlignment, TextItemDirection aDirection)
 Add another string to be displayed, top down, with paragraph direction. More...
 
void clearTextItems ()
 Remove all strings that were to be displayed. More...
 
void setTextItemDirection (string aItem, SignatureParametersHAlignment aHAlignment, TextItemDirection aDirection)
 Set the paragraph direction of text items. More...
 
void setPKCS7 (SignPKCS7 aPKCS7)
 Set an object which will create a PKCS #7 or CAdES signature. More...
 
void setRSA (SignRSA aRSA)
 Set an object which will compute an RSA signature. More...
 
void setECDSA (SignECDSA aECDSA)
 Set an object which will compute an ECDSA signature. More...
 
void setDSA (SignDSA aDSA)
 Set an object which will compute a DSA signature. More...
 
void setTimeStamper (UserTimeStamper aTimeStamper)
 Set an object which will create an RFC 3161 time stamp. More...
 
void setCertificatePicker (CertificatePicker aCertificatePicker)
 Set an object which will let the user select a certificate. More...
 
void setPasswordProvider (PasswordProvider aPasswordProvider)
 Set an object which asks the user for a password. More...
 
SigningMethodFlags getAvailableMethods ()
 Get a bitset indicating which signing methods are available for this signature field. More...
 
byte[] getTemplate ()
 Get an XML document specifying the current layout. More...
 
bool? getBoolean (string aName)
 Get the value of a boolean parameter. More...
 
int? getInteger (string aName)
 Get the value of an integer parameter. More...
 
string getString (string aName)
 Get the value of a string parameter. More...
 
string getString (string aName, int aIndex)
 Get the value of a string parameter with index. More...
 
double? getLength (string aName)
 Get the value of a length parameter. More...
 
LengthType getLengthType (string aName)
 Get the length type of a length parameter. More...
 
SignDocColor getColor (string aName)
 Get the value of a color parameter. More...
 
byte[] getBlob (string aName)
 Get the value of a blob parameter. More...
 
byte[] getBlob (string aName, int aIndex)
 Get the value of a blob parameter with index. More...
 
SignDocTextItem getTextItem (int aIndex)
 Get a text item. More...
 
bool hasCallback (string aName)
 Check if setDSA(), setECDSA(), setPKCS7(), setRSA(), or setTimeStamper() has been called with a non-null parameter. More...
 
string getErrorMessage ()
 Get an error message for the last function call. More...
 
void destroy ()
 Destroy this object, overwriting sensitive data. More...
 

Static Public Member Functions

static SignatureParameterType getType (string aName)
 Get the type of a parameter. More...
 

Detailed Description

Parameters for signing a document.

Use SignDocDocument.createSignatureParameters() or SignDocDocument.createSignatureParametersForTimeStamp() to create objects of this type. Alternatively, use the default constructor and loadFromMemory().

Use getErrorMessage() to get more information after a function call failed.

The available parameters depend both on the document type and on the signature field for which the SignDocSignatureParameters object has been created.

SignDocDocument.addSignature() may fail due to invalid parameters even if all setters reported success as the setters do not check if there are conflicts between parameters.

Which certificates are acceptable may be restricted by the application (by using CertificateSelectionFlags.Software and CertificateSelectionFlags.Hardware of integer parameter "SelectCertificate", blob parameters "FilterCertificatesByIssuerCertificate" and "FilterCertificatesBySubjectCertificate", and string parameters "FilterCertificatesByPolicy" and "FilterCertificatesBySubjectDN") and by the PDF document (certificate seed value dictionary). If no matching certificate is available (for instance, because integer parameter "SelectCertificate" is zero), SignDocDocument.addSignature() will fail with exception SignDocNoCertificateException. If more than one matching certificate is available but CertificateSelectionFlags.NeverAsk is specified in integer parameter "SelectCertificate"), SignDocDocument.addSignature() will fail with exception SignDocAmbiguousCertificateException.

To make the signature maximally meaningful, integer parameter "AddCertificates" should be AddCertificates.All (which is the default value) and integer parameter "AddRevocationInfo" should include AddRevocationInfo.Add.

Unless you need a specific signing method, you should leave integer parameter "Method" at its default value SigningMethod.Default. Use SigningMethod.DigSigCadesDetached for LTV. If you select a specific signing method and that method is not allowed by the signature field's seed values, signing will fail.

Unless you need a specific digest algorithm, you should leave string parameter "DetachedHashAlgorithm" at its default value "default". If you select a specific digest algorithm and that algorithm is not allowed by the signature field's seed values, signing will fail.

The interaction between some parameters is quite complex; the following section tries to summarize the signing methods for PDF documents.

(1a)
Default method, private key and self-signed certificate created on the fly:
  • Method: SigningMethod.Default
  • CommonName: signer's name
  • GenerateKeyPair: 1024-4096 (or GenerateECCKeyPair)
(1b)
Default method, the certificate and its key are provided as PKCS #12 blob:
  • Method: SigningMethod.Default
  • Certificate: PKCS #12 blob containing certificate (need not be self-signed) and its private key
  • PKCS#12Password: password for private key in the PKCS #12 blob
(1c)
Default method, private key provided, certificate provided:
  • Method: SigningMethod.Default
  • Certificate: certificate
  • CertificatePrivateKey: private key for the certificate
(1d)
Default method, user must select certificate:
(1e)
Default method, user may select certificate or choose to create a self-signed certificate, the private key of which will be generated:
(1f)
Default method, the certificate is selected programmatically or by the PDF document without user interaction:
(1g)
Default method via SignRSA, SignECDSA, or SignDSA interface: See setRSA(), setECDSA(), and setDSA() for details.
(1h)
Default method, private key provided, self-signed certificate created on the fly:
  • Method: SigningMethod.Default
  • CommonName: signer's name
  • CertificatePrivateKey: private key for the self-signed certificate
(1i)
Default method, user may select certificate or choose to create a self-signed certificate, the private key of which is provided:
(1j)
Default method, user may select certificate or choose to "create" a self-signed certificate, the certificate to be used in that case and its key are provided separately:
(1k)
Default method, user may select certificate or choose to "create" a self-signed certificate, the certificate to be used in that case and its key are provided as PKCS #12 blob:
(2a)
PKCS #7 or CAdES, private key and self-signed certificate created on the fly:
(2b)
PKCS #7 or CAdES, the certificate and its key are provided as PKCS #12 blob:
(2c)
PKCS #7 or CAdES, private key provided, certificate provided:
(2d)
PKCS #7 or CAdES, user must select certificate:
(2e)
PKCS #7 or CAdES, user may select certificate or choose to create a self-signed certificate, the private key of which will be generated:
(2f)
PKCS #7 or CAdES, the certificate is selected programmatically or by the PDF document without user interaction:
(2g)
PKCS #7 or CAdES via SignRSA interface: See setRSA(), setECDSA(), and setDSA() for details.
(2h)
PKCS #7 or CAdES, private key provided, self-signed certificate created on the fly:
(2i)
PKCS #7 or CAdES, user may select certificate or choose to create a self-signed certificate, the private key of which is provided:
(2j)
PKCS #7 or CAdES, user may select certificate or choose to "create" a self-signed certificate, the certificate to be used in that case and its key are provided separately:
(2k)
PKCS #7 or CAdES, user may select certificate or choose to "create" a self-signed certificate, the certificate to be used in that case and its key are provided as PKCS #12 blob:
(2l)
PKCS #7 or CAdES via SignPKCS7 interface: See setPKCS7() for details.
(3a)
PKCS #1, private key and self-signed certificate created on the fly:
(3b)
PKCS #1 via SignRSA interface: See setRSA(), setECDSA(), and setDSA() for details.
(3c)
PKCS #1, private key provided, self-signed certificate created on the fly:
  • Method: SigningMethod.DigSigPKCS1
  • CommonName: signer's name
  • CertificatePrivateKey: private key for the self-signed certificate
(3d)
PKCS #1, private key provided, self-signed certificate provided:
  • Method: SigningMethod.DigSigPKCS1
  • Certificate: self-signed certificate
  • CertificatePrivateKey: private key for self-signed certificate
(4a)
document time stamp using a SignDocSignatureParameters object created by SignDocDocument.createSignatureParametersForTimeStamp():
  • TimeStampServerURL: URL of time stamp server

Additionally:

  • You may want to set string parameter "Filter" to "Adobe.PPKLite".
  • You may want to set integer parameter "IgnoreSeedValues" if you set integer parameter "Method" and/or string parameter "DetachedHashAlgorithm".

For TIFF documents, an additional, simplified signing method is available:

(4)
just a hash:

If the signing certificate has a key usage extension, at least one of the following key purposes must be present in the key usage extension:

  • digitalSignature (bit 0)
  • nonRepudiation (bit 1)

If the signing certificate has an extended key usage extension, at least one of the following extended key purposes must be present in the extended key usage extension:

  • 1.2.840.113583.1.1.5 (authenticDocumentsTrust, Adobe)
  • 1.3.6.1.4.1.311.10.3.12 (documentSigning, Microsoft)
  • 1.3.6.1.5.5.7.3.3 (codeSigning)
  • 1.3.6.1.5.5.7.3.4 (emailProtection)
  • 2.5.29.37.0 (anyExtendedKeyUsage)

The following parameters control the signing method and related aspects of the signature:

  • DetachedHashAlgorithm (string)
  • IgnoreSeedValues (integer)
  • Method (integer)
  • RSASignatureScheme (string)

The following parameters control the certificate and the private key used for signing:

  • Certificate (blob)
  • CertificatePrivateKey (blob)
  • GenerateECCKeyPair (string)
  • GenerateKeyPair (integer)
  • PasswordProvider (string)
  • PKCS#12Password (string)

The following parameters control rendering of the signature image from biometric data:

  • BiometricData (blob)
  • PenWidth (integer)
  • RenderSignature (integer)
  • RenderWidth (integer)
  • SignatureColor (color)

The following parameters put additional data into the signature:

  • ContactInfo (string)
  • Filter (string)
  • Location (string)
  • Reason (string)
  • Signer (string)
  • Timestamp (string)
  • TimestampOffset (integer)

The following parameters provide texts for the appearance of a signature in PDF documents:

  • Adviser (string)
  • Comment (string)
  • ContactInfo (string)
  • Location (string)
  • Reason (string)
  • Signer (string)
  • SignTime (string)
  • Template (blob)
  • Text1 through Text9 (string)

The following parameters control how a signed signature field in a PDF document will look like (parameters marked with * can be overridden with blob parameter "Template"):

  • FontName (string) *
  • FontSize (length) *
  • Image (blob)
  • ImageDPI (integer)
  • ImageHAlignment (integer) *
  • ImageMargin (length) *
  • ImageTransparency (integer) *
  • ImageVAlignment (integer) *
  • SignatureColor (color)
  • Template (blob)
  • TextColor (color) *
  • TextHAlignment (integer) *
  • TextHMargin (length) *
  • TextPosition (integer) *
  • TextVAlignment (integer) *

The following parameters are used with PKCS #11 tokens:

The following parameters are used for generating a self-signed certificate on the fly (you also need to set at least one parameter for the private key):

  • CertificateSigningAlgorithm (string)
  • CommonName (string)
  • Country (string)
  • Locality (string)
  • Organization (string)
  • OrganizationUnit (string)
  • SelfSignedOffset (integer)

The following parameters are used for putting biometric data (handwritten signature) into the signature:

  • BiometricData (blob)
  • BiometricEncryption (integer)
  • BiometricHashLocation (integer)
  • BiometricKey (blob)
  • BiometricKeyPath (string)
  • BiometricPassphrase (string)

The following parameters control the certificate selection dialog:

  • CertificatePicker (string)
  • FilterCertificatesByIssuerCertificate (blob)
  • FilterCertificatesByPolicy (string)
  • FilterCertificatesBySubjectCertificate (blob)
  • FilterCertificatesBySubjectDN (string)
  • SelectCertificate (integer)
  • SelectCertificateMessage (string)
  • SelectCertificateTitle (string)

The following parameters control RFC 3161 timestamps:

  • TimeStampClientCertificatePath (string)
  • TimeStampClientKeyPath (string)
  • TimeStampHashAlgorithm (string)
  • TimeStampRetries (integer)
  • TimeStampServerPassword (string)
  • TimeStampServerTimeout (integer)
  • TimeStampServerURL (string)
  • TimeStampServerUser (string)
  • TimeStampSize (integer)
  • TimeStampUserAgent (string)

The following parameters control certification signatures:

  • DocMDP (integer)
  • LegalAttestation (string)

The following parameters put additional certificates and revocation information into the signature:

  • AddCertificates (integer)
  • AddRevocationInfo (integer)
  • IntermediateCertificate (blob)

The following parameters are used for multi-phase signing:

  • LastPhase (boolean, output)
  • MultiPhase (boolean)
  • MultiPhaseData (blob)
  • Next (string, output)

The following parameters do not fall into the above categories:

  • OutputPath (string)
  • Optimize (integer)
  • PDFAButtons (integer)
  • RemoveXFA (integer)

The following parameters can be set by SignDocDocument.addSignature():

  • LastPhase (boolean)
  • Next (string)

Constructor & Destructor Documentation

~SignDocSignatureParameters ( )

Destructor.

SignDocSignatureParameters ( )

Constructor.

Use SignDocDocument.createSignatureParameters() or SignDocDocument.createSignatureParametersForTimeStamp() to create objects of this type. Alternatively, use this constructor and loadFromMemory().

Member Function Documentation

void addTextItem ( string  aItem,
TextGroup  aGroup 
)

Add another string to be displayed, top down.

For DigSig signature fields, this function adds another string to the appearance stream of PDF documents. The first call clears any default strings. The default values depend on the profile passed to SignDocDocument.createSignatureParameters():

ProfileValue
"" "Signer"/TextGroup.Primary, "SignTime"/TextGroup.Primary
"image"(empty)

The paragraph direction is 0 which is treated like TextItemDirection.LTR.

See also blob parameter "Template".

Parameters
[in]aItemSelect the string to be added:
  • Signer String parameter "Signer".
  • SignTime String parameter "SignTime".
  • Comment String parameter "Comment".
  • Adviser String parameter "Adviser".
  • ContactInfo String parameter "ContactInfo".
  • Location String parameter "Location".
  • Reason String parameter "Reason".
  • Text1 String parameter "Text1".
  • Text2 String parameter "Text2".
  • Text3 String parameter "Text3".
  • Text4 String parameter "Text4".
  • Text5 String parameter "Text5".
  • Text6 String parameter "Text6".
  • Text7 String parameter "Text7".
  • Text8 String parameter "Text8".
  • Text9 String parameter "Text9".
[in]aGroupThe string's group for font size computation.
See also
addTextItem2(), clearTextItems(), getTextItem(), setTextItemDirection(), TextGroup.Primary
void addTextItem2 ( string  aItem,
TextGroup  aGroup,
SignatureParametersHAlignment  aHAlignment,
TextItemDirection  aDirection 
)

Add another string to be displayed, top down, with paragraph direction.

For DigSig signature fields, this function adds another string to the appearance stream of PDF documents. The first call clears any default strings. The default values depend on the profile passed to SignDocDocument.createSignatureParameters():

ProfileValue
"" #"Signer"/TextGroup.Primary, "SignTime"/TextGroup.Primary
"image"(empty)

See also blob parameter "Template".

Parameters
[in]aItemSelect the string to be added:
  • Signer String parameter "Signer".
  • SignTime String parameter "SignTime".
  • Comment String parameter "Comment".
  • Adviser String parameter "Adviser".
  • ContactInfo String parameter "ContactInfo".
  • Location String parameter "Location".
  • Reason String parameter "Reason".
  • Text1 String parameter "Text1".
  • Text2 String parameter "Text2".
  • Text3 String parameter "Text3".
  • Text4 String parameter "Text4".
  • Text5 String parameter "Text5".
  • Text6 String parameter "Text6".
  • Text7 String parameter "Text7".
  • Text8 String parameter "Text8".
  • Text9 String parameter "Text9".
[in]aGroupThe string's group for font size computation.
[in]aHAlignmentHorizontal alignment. This value overrides integer parameter "TextHAlignment" unless it is SignatureParametersHAlignment.Default.
[in]aDirectionThe paragraph direction, see enum TextItemDirection. 0 is treated like TextItemDirection.LTR.
See also
addTextItem(), clearTextItems(), getTextItem(), setTextItemDirection(), TextGroup.Primary
void clearTextItems ( )

Remove all strings that were to be displayed.

addTextItem() cannot remove the default strings without adding a new string. This function does.

See also blob parameter "Template".

See also
addTextItem()
SignDocSignatureParameters clone ( bool  aStartKeyGenerator)

Clone this object.

Parameters
[in]aStartKeyGeneratortrue to start the key generator in the copied object. This is needed if integer parameter "GenerateKeyPair" or string parameter "GenerateECCKeyPair" is set and you want to pass the copy to SignDocDocument.addSignature(). false to not start the key generator. If integer parameter "GenerateKeyPair" or string parameter "GenerateECCKeyPair" is set, SignDocDocument.addSignature() will fail.
Returns
A clone of this object.
void destroy ( )

Destroy this object, overwriting sensitive data.

After calling this method, all methods of this object will fail.

SigningMethodFlags getAvailableMethods ( )

Get a bitset indicating which signing methods are available for this signature field.

Returns
1<<SigningMethod.DigSigPKCS1 etc.
See also
SignDocDocument.getAvailableMethods()
byte [] getBlob ( string  aName)

Get the value of a blob parameter.

getBlob(name) is equivalent to getBlob(name,0).

This function does not support blob parameters "FilterCertificatesByIssuerCertificate", "FilterCertificatesBySubjectCertificate", and "IntermediateCertificate".

Certificates passed to setBlob() in PEM format may be returned by this function as individual DER-encoded certificates.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The value of the specified parameter or null if the parameter is not set or is not a blob parameter.
See also
setBlob()
byte [] getBlob ( string  aName,
int  aIndex 
)

Get the value of a blob parameter with index.

getBlob(name,0) is equivalent to getBlob(name).

This function supports blob parameters "FilterCertificatesByIssuerCertificate", "FilterCertificatesBySubjectCertificate", and "IntermediateCertificate".

Certificates passed to setBlob() in PEM format may be returned by this function as individual DER-encoded certificates.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aIndexThe zero-based index of the blob to get.
Returns
The value of the specified parameter or null if the parameter is not set or is not a blob parameter or if aIndex is out of range.
See also
setBlob()
bool? getBoolean ( string  aName)

Get the value of a boolean parameter.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The value of the parameter or null if the parameter is not set or is not a boolean parameter.
See also
setBoolean()
SignDocColor getColor ( string  aName)

Get the value of a color parameter.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The value of the specified parameter or null if the parameter is not set or is not a color parameter.
See also
setColor()
string getErrorMessage ( )

Get an error message for the last function call.

Returns
A string describing the reason for the failure of the last function call. The string is empty if the last call succeeded.
int? getInteger ( string  aName)

Get the value of an integer parameter.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The value of the parameter or null if the parameter is not set or is not an integer parameter.
See also
setInteger()
double? getLength ( string  aName)

Get the value of a length parameter.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The value of the parameter or null if the parameter is not set or is not a length parameter.
See also
getLengthType(), setLength()
LengthType getLengthType ( string  aName)

Get the length type of a length parameter.

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The length type or -1 if the parameter is not set or is not a length parameter.
See also
getLength(), setLength()
string getString ( string  aName)

Get the value of a string parameter.

getString(name) is equivalent to getString(name,0).

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The value of the parameter or null if the parameter is not set or is not a string parameter.
See also
setString()
string getString ( string  aName,
int  aIndex 
)

Get the value of a string parameter with index.

getString(name,0) is equivalent to getString(name).

This function does not set an error message.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aIndexThe zero-based index of the string to get.
Returns
The value of the parameter or null if the parameter is not set or is not a string parameter or if aIndex is out of range.
See also
setString()
byte [] getTemplate ( )

Get an XML document specifying the current layout.

This function can be used for debugging and for reporting bugs. This function will fail if the "Template" blob parameter is invalid.

Returns
The XML document.
See also
setBlob()
SignDocTextItem getTextItem ( int  aIndex)

Get a text item.

Parameters
[in]aIndexZero based index of the text item.
Returns
The text item or null if aIndex is out of range.
See also
addTextItem(), addTextItem2(), setTextItemDirection()
static SignatureParameterType getType ( string  aName)
static

Get the type of a parameter.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
Returns
The type of the parameter.
bool hasCallback ( string  aName)

Check if setDSA(), setECDSA(), setPKCS7(), setRSA(), or setTimeStamper() has been called with a non-null parameter.

This function does not set an error message.

Parameters
[in]aName"CertificatePicker" for setCertificatePicker(), "DSA" for setDSA(), "ECDSA" for setECDSA(), "PasswordProvider" for setPasswordProvider(), "PKCS7" for setPKCS7(), "RSA" for setRSA(), or "TimeStamper" for setTimeStamper().
Returns
true iff the method specified by aName has been called with a non-null parameter.
See also
setCertificatePicker(), setDSA(), setECDSA(), setPasswordProvider(), setPKCS7(), setRSA(), setTimeStamper()
void loadFromMemory ( byte[]  aBlob,
ParametersLoadFlags  aFlags 
)

Load a SignDocSignatureParameters object from a blob (deserialize).

Parameters set in this object but not set in the blob won't be overwritten.

Parameters
[in]aBlobA blob containing a serialized SignDocSignatureParameters object, see saveToMemory(). If the blob contains an XML document, it must conform to SignDocParameters.dtd, which see for details.
[in]aFlagsMust be ParametersLoadFlags.Zero.
See also
clear(), saveToMemory()
byte [] saveToMemory ( ParametersSaveFlags  aFlags)

Serialize this object to a blob.

Secret values won't be saved unless ParametersSaveFlags.Secret or ParametersSaveFlags.Debug is set in aFlags.

SignDocDocument.addSignature() may change the SignDocSignatureParameters object passed to it. If you want to serialize the SignDocSignatureParameters object, please do so before calling SignDocDocument.addSignature().

Parameters
[in]aFlagsSet of flags. Pass ParametersSaveFlags.Zero for no flags (binary format).
Returns
A blob containing a serialized version of this object. If the output is an XML document, it will conform SignDocParameters.dtd, which see for details.
void setBlob ( string  aName,
byte[]  aValue 
)

Set a blob parameter.

Available blob parameters are:

  • BiometricData The biometric data is stored in the document (see integer parameter "BiometricEncryption") and will be used for rendering the signature image if integer parameter "RenderSignature" is non-zero (unless a signature image is specified by blob parameter "Image"). If used for rendering, the data must be in a format supported by SignWare (e.g., created by SPFlatFileCreateFromSignature()).
  • BiometricKey The public key (BiometricEncryption.RSA) or the AES key (BiometricEncryption.Binary) for encrypting the biometric data. See also string parameter "BiometricKeyPath" and Encryption of biometric data.
  • Certificate The signing certificate for the signature. The blob must contain a serialized X.509 certificate (DER or PEM) and blob parameter "CertificatePrivateKey" must contain the private key for that certificate. Alternatively, for PKCS #7 and CAdES detached signatures, the blob may contain the certificate and its private key in PKCS #12 format; string parameter "PKCS#12Password" contains the password for extracting the private key.
  • CertificatePrivateKey The private key for the (self-signed) certificate in PKCS #1 format (DER or PEM) for RSA or in SEC 1 format, traditional format, or PKCS #8 format (DER or PEM) for ECDSA. If a certificate is passed in blob parameter "Certificate", this parameter must contain the private key for that certificate. If a self-signed certificate is to be generated, the private key can be either set with this parameter or generated with integer parameter "GenerateKeyPair" or with string parameter "GenerateECCKeyPair". Alternatively, string parameter "PasswordProvider" can be set or setPasswordProvider() be called.
  • FilterCertificatesByIssuerCertificate Acceptable issuer certificates. Setting this parameter adds the specified DER-encoded certificate to a list of acceptable issuer certificates. Pass 0 for aSize to clear the list. A PDF document may contain (in its certificate seed value dictionaries) additional restrictions for acceptable issuer certificates. A signer certificate is acceptable for the rule defined by this parameter if it chains up to any of the certificates in the list of acceptable issuer certificates. SignDocDocument.addSignature() will fail if no matching certificate is available for signing. Note that CertificateSelectionFlags.Software and/or CertificateSelectionFlags.Hardware must be included in integer parameter "SelectCertificate" to make certificates available at all.
  • FilterCertificatesBySubjectCertificate Acceptable certificates. Setting this parameter adds the specified DER-encoded certificate to a list of acceptable certificates. Pass 0 for aSize to clear the list. A PDF document may contain (in its certificate seed value dictionaries) additional restrictions for acceptable certificates. SignDocDocument.addSignature() will fail if no matching certificate is available for signing. Note that CertificateSelectionFlags.Software and/or CertificateSelectionFlags.Hardware must be included in integer parameter "SelectCertificate" to make certificates available at all.
  • Image The signature image. The image can be in BMP, JPEG, PNG, TIFF, or WebP format. If no image is set (or rendered, see integer parameter "RenderSignature"), the signature field may or may not show an image computed from the biometric data, depending on the document type and signature field type. This parameter overrides integer parameter "RenderSignature". See also integer parameters "ImageDPI" and "ImageTransparency" and blob parameter "Template".
  • IntermediateCertificate An intermediate certificate for the signature. The blob must contain a DER-encoded X.509 certificate or one or more PEM-encoded X.509 certificates. setBlob() calls with name "IntermediateCertificate" are cumulative. Intermediate certificates can also be provided in the PKCS #12 blob passed to blob parameter "Certificate". See also integer parameter "AddCertificates".
  • MultiPhaseData Computed data for multi-phase signing. This is the value that would be returned by SignRSA.sign(), SignECDSA.sign(), SignDSA.sign(), SignPKCS7.sign(), or UserTimeStamper.stamp() if multi-phase signing were not active.
  • Template An XML document specifying the layout of the appearance of a signature in PDF documents. The XML document must conform to SignatureTemplate.dtd, which see for details. You can control the layout of the appearance of the signature by
    • using the default values provided by SignDocDocument.createSignatureParameters(), or
    • using only string parameters (such as "FontName"), integer parameters (such as "TextPosition"), and length parameters (such as "ImageMargin"), color parameters (such as "TextColor"), or
    • using only blob parameter "Template", or
    • a mixture of the above.
    Initial values for the parameters are provided by SignDocDocument.createSignatureParameters(). If blob parameter "Template" is set, text items added by addTextItem() and friends are ignored, but other parameters provide default values for attributes not used in the XML document.

Additionally, you can store your own blobs in the signature by using a name starting with "Prop_", except for "Prop_AuthTime", "Prop_AuthType", "Prop_Build", and any name starting with "Prop_BiometricData", see SignDocVerificationResult.getSignatureBlob(). The name shall contain the following characters only: 0-9, a-z, A-Z, '-', and '_'.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value.
See also
getBlob(), getTemplate()
void setBoolean ( string  aName,
bool  aValue 
)

Set a boolean parameter.

The following boolean parameters are available:

  • ChildGUI true to run a process to display the signature selection dialog (see string parameter "CertificatePicker") and the password dialog (see string parameter "PasswordProvider"). The default value is "false". However, the value is assumed to be "true" when using SignDoc SDK from Java on macOS.
  • LastPhase true if the next phase is the last phase of multi-phase signing. This parameter is set by SignDocDocument.addSignature(), any value set with setBoolean() is ignored. See also string parameter "Next".
  • MultiPhase Enable multi-phase signing if true. If this value is false, signing is performed by a single call to addSignature(). The default value is false (single-phase signing). This parameter modifies the interpretation of string parameter "OutputPath". See SignDocDocument.addSignature() for details.

This function throws SignDocUnkownParameterException if aName is not the name of a boolean parameter.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter.
See also
getBoolean()
void setCertificatePicker ( CertificatePicker  aCertificatePicker)

Set an object which will let the user select a certificate.

By default, SignDoc SDK uses a wxWidgets-based dialog for letting the user select a certificate for CertificateSelectionFlags.Software and CertificateSelectionFlags.Hardware (without CertificateSelectionFlags.NeverAsk). You can use your own dialog by calling this method.

See de.softpro.doc.CertificatePicker for details. See also string parameter "CertificatePicker".

Parameters
[in]aCertificatePickerThe object that will let the user select a certificate.
See also
hasCallback()
void setColor ( string  aName,
SignDocColor  aValue 
)

Set a color parameter.

Available color parameters are:

  • SignatureColor The foreground color for the rendered signature (see integer parameter "RenderSignature"). The default color is black.
  • TextColor The color to be used for text in the appearance of a DigSig signature field in a PDF document. If this parameter is not set, the color will be taken from the field's text field attributes. If the field doesn't have text field attributes, the document's text field attributes will be used. If this also fails, the text will be black. Once set, this parameter cannot be unset. See also string parameter "FontName", length parameter "FontSize", and blob parameter "Template".
Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter.
void setDSA ( SignDSA  aDSA)

Set an object which will compute a DSA signature.

By default, DSA signatures are computed internally which means that the private key must be available on this machine.

Requirements for string parameters:

  • GenerateECCKeyPair must not be set

Requirements for integer parameters:

  • GenerateKeyPair must not be set
  • SelectCertificate must be zero (which is the default value)

Requirements for blob parameters:

  • Certificate must not be set
  • CertificatePrivateKey must not be set

setRSA() and setPKCS7() must not have been called

Parameters
[in]aDSAThe object that will compute the DSA signature.
See also
hasCallback(), setECDSA(), setPKCS7(), setRSA()
void setECDSA ( SignECDSA  aECDSA)

Set an object which will compute an ECDSA signature.

By default, ECDSA signatures are computed internally which means that the private key must be available on this machine.

Requirements for string parameters:

  • GenerateECCKeyPair must not be set

Requirements for integer parameters:

  • GenerateKeyPair must not be set
  • SelectCertificate must be zero (which is the default value)

Requirements for blob parameters:

  • Certificate must not be set
  • CertificatePrivateKey must not be set

setRSA() and setPKCS7() must not have been called

Parameters
[in]aECDSAThe object that will compute the ECDSA signature.
See also
hasCallback(), setDSA(), setPKCS7(), setRSA()
void setInteger ( string  aName,
int  aValue 
)

Set an integer parameter.

Available integer parameters are:

  • AddCertificates This parameter controls inclusion of intermediate and root certificates. See enum AddCertificates. The default value is AddCertificates.All. If you are using setPKCS7(), you'll have to include the certificates yourself. See also integer parameter "AddRevocationInfo" and blob parameter "IntermediateCertificate".
  • AddRevocationInfo This parameter controls inclusion of revocation data (CRL and OCSP) for the signing certificate (unless it is self-signed) and the intermediate certificates. See enum AddRevocationInfo. If the parameter is zero (which is the default value), revocation data won't be included. If the signature field has a mandatory AddRevInfo seed value, with value true, AddRevocationInfo is assumed to have AddRevocationInfo.Add set. If revocation data is to be added, integer parameter "Method" must be set to SigningMethod.DigSigPKCS7Detached, SigningMethod.DigSigPKCS7SHA1, or SigningMethod.DigSigCadesDetached, otherwise signing will fail. Integer parameter "AddCertificates" must be AddCertificates.All or AddCertificates.Trusted, otherwise signing will fail. If revocation data is to be included, VerificationFlags.CheckRevocation is assumed to be set in the value of integer parameter "VerificationFlags" of the verification parameters. Integer parameter "VerificationModel" of addSignature()'s aVerificationParameters is assumed to be VerificationModel.Chain if it is VerificationModel.Minimal (to enable inclusion of all certificates but the root certificate). If revocation data cannot be retrieved or if any of the certificates for which revocation information is retrieved is revoked or has unknown revocation status, signing will fail. If you are using setPKCS7(), you'll have to include revocation information yourself.
  • BiometricEncryption Specifies how biometric data is to be encrypted (enum BiometricEncryption). The default value is BiometricEncryption.DontStore.
  • BiometricHashLocation Specifies where to store the message digest computed over the document hash and the unencrypted biometric data (enum BiometricHashLocation). This parameter is used for PDF documents only. The default value is BiometricHashLocation.Attr.
  • DocMDP To create a certification signature rather than an approval signature, set this parameter to a positive value (PDF only):
    • 1 no changes to the document shall be permitted
    • 2 only filling in forms, instantiating page templates, and signing shall be permitted
    • 3 only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations shall be permitted.
    To create an approval signature, set this parameter to 0 or -1. The default value is -1. A positive MDP value from the signature seed value dictionary overrides this parameter, see SignDocField.getSeedValueMDP(). A PDF document can have at most one certification signature. The certification signature must be added before any approval signature (currently not enforced by SignDoc SDK). If you want the certification signature to be invisible, create the signature field with zero for the left, bottom, right, and top coordinates. String parameter LegalAttestation should be set for a certification signature.
  • GenerateKeyPair Start generation of an RSA key pair for the self-signed certificate if non-zero. The value is the number of bits (1024 through 4096, multiple of 8). If a self-signed certificate is to be generated, the private key can either be generated by setting this parameter or set as blob parameter "CertificatePrivateKey". The default value is zero. See also string parameter "GenerateECCKeyPair". "GenerateECCKeyPair" and "GenerateKeyPair" are mutually exclusive.
  • IgnoreSeedValues Specifies what entries in the signature field seed value dictionary shall be ignored. This parameter contains a set of flags taken from enum IgnoreSeedValues. The default value is 0 which means that signing might fail due to a conflict between integer parameters "Method" and string parameter "DetachedHashAlgorithm" on one hand and the SubFilter and DigestMethod entries of the signature field seed value dictionary on the other hand. The Cert entry of the signature field seed value dictionary is currently ignored by default, see CertificateSelectionFlags.UseCertificateSeedValues of integer parameter "SelectCertificate". This parameter is ignored for TIFF documents.
  • ImageDPI Resolution in DPI of the image passed in blob parameter "Image" for PDF signature fields. The width and height of the image computed by multiplying the resolution with the number of horizontal pixels and vertical pixels, respectively, limits the size of the image in the signature field: The image will never be wider or higher than that width and height, respectively. (You can cheat by specifying a smaller resolution.) Positive values of this parameter specify the horizontal resolution in DPI, zero means that the resolution is taken from the image (the behavior is undefined if the image does not specify a resolution), -1 means that the size of the image in the signature field won't be limited by values computed from its size (apart from the aspect ratio). The default value is -1. This parameter is ignored for TIFF documents.
  • ImageHAlignment The horizontal alignment of the image (enum SignatureParametersHAlignment, SignatureParametersHAlignment.Left, SignatureParametersHAlignment.Center, or SignatureParametersHAlignment.Right). For DigSig signature fields, this parameter defines the horizontal alignment of the image in the appearance stream of PDF documents. The default value depends on the profile passed to SignDocDocument.createSignatureParameters():
    ProfileValue
    "" SignatureParametersHAlignment.Center
    "image"SignatureParametersHAlignment.Center
    See also blob parameter "Template".
  • ImageVAlignment The vertical alignment of the image (enum SignatureParametersVAlignment). For DigSig signature fields, this parameter defines the vertical alignment of the image in the appearance stream of PDF documents. The default value depends on the profile passed to SignDocDocument.createSignatureParameters():
    ProfileValue
    "" SignatureParametersVAlignment.Top
    "image"SignatureParametersHAlignment.Center
    See also blob parameter "Template".
  • ImageTransparency Image transparency (enum ImageTransparency). For DigSig signature fields, this parameter defines how to handle transparency for signature image (either the image passed in the "Image" blob parameter or the image computed according to the "RenderSignature" integer parameter). The default value is ImageTransparency.Brightest. See also blob parameter "Template".
  • Method The signing method (enum SigningMethod). The default value is SigningMethod.Default. Use SigningMethod.DigSigCadesDetached for LTV. See also string parameter "DetachedHashAlgorithm" and integer parameter"IgnoreSeedValues".
  • Optimize Specifies whether the document shall be optimized if the signature to be added is the first signature. Use one of the values of enum Optimize. The default value is Optimize.IfPossible. If the return value of getRequiredSaveToFileFlags() includes SaveFlags.Incremental, signing with this parameter set to Optimize.Yes will fail.
  • PDFAButtons Set whether appearance streams of check boxes and radio buttons shall be frozen (fixed) for conformance with PDF/A-1 without TC2 before signing. Use one of the values of enum PDFAButtons. The default value is PDFAButtons.DontFreeze.
  • PenWidth Pen width for rendering the signature (see blob parameter "BiometricData") for the signature image. Ignored unless integer parameter "RenderSignature" is non-zero. The pen width is specified in micrometers, the default value is 500 (0.5mm).
  • RemoveXFA This parameter controls whether the XFA entry of the interactive form dictionary of the PDF document shall be removed. SignDoc SDK does not support XFA (XML Forms Architecture) and therefore addSignature(), addField(), applyFdf(), and setField() remove XFA from the document to avoid descrepancies between "classic" form fields and XFA. Use one of the values of enum RemoveXFA. The default value is RemoveXFA.IfAllowed. This parameter is ignored for TIFF documents.
  • RenderSignature Specifies whether and how the signature (see blob parameter "BiometricData") is to be rendered for the signature image. This parameter contains a set of flags taken from enum RenderSignatureFlags. If this value is 0, the signature won't be rendered. If no image is rendered (or set, see blob parameter "Image"), the signature field may or may not show an image computed from the biometric data, depending on the document type and signature field type. This parameter is ignored if blob parameter "Image" is set. The default value is 0. See also integer parameters "ImageTransparency", "PenWidth", and "RenderWidth" and color parameter "SignatureColor".
  • RenderWidth Specifies the width (in pixels) for the signature image rendered from biometric data for PDF documents. This parameter is ignored for TIFF documents. The default value is 600. If the signature is higher than wide, this value specified the height of the signature image.
  • SelectCertificate Let the user and/or the application select the certificate for the signature. The parameter contains a set of flags taken from enum CertificateSelectionFlags. If this parameter is zero (which is the default value), the user won't be asked and the certificate will either be generated on the fly or be supplied by the "Certificate" blob parameter and SignDocDocument.addSignature() will fail if the PDF document restricts acceptable certificates by means of a certificate seed value dictionary. This parameter is not yet implemented for iOS and Windows Store apps. See also string parameters "SelectCertificateMessage" and "SelectCertificateTitle".
  • SelfSignedOffset Add this value as seconds to the current time for the notBefore value (start of validity) of the generated self-signed certificate. Use a negative value to extend the validity period into the past. Ignored if not generating a self-signed certificate. The default value is zero.
  • TextHAlignment The horizontal alignment of text lines (enum SignatureParametersHAlignment). For DigSig signature fields, this parameter defines the horizontal alignment of text lines in the appearance stream of PDF documents. The default value depends on the profile passed to SignDocDocument.createSignatureParameters():
    ProfileValue
    "" SignatureParametersHAlignment.Center
    "image"SignatureParametersHAlignment.Center
    See also blob parameter "Template".
  • TextPosition The position of the text block w.r.t. the image (enum TextPosition). For DigSig signature fields, this parameter defines the position of the text block in the appearance stream of PDF documents. The default value depends on the profile passed to SignDocDocument.createSignatureParameters().
    ProfileValue
    "" TextPosition.Below
    "image"TextPosition.Overlay
    See also blob parameter "Template".
  • TextVAlignment The vertical alignment of text lines (enum SignatureParametersVAlignment). For DigSig signature fields, this parameter defines the vertical alignment of text lines in the appearance stream of PDF documents. The default value depends on the profile passed to SignDocDocument.createSignatureParameters():
    ProfileValue
    "" SignatureParametersVAlignment.Bottom
    "image"SignatureParametersHAlignment.Center
    See also blob parameter "Template".
  • TimestampOffset Add this value as seconds to the timestamp controlled by string parameter "Timestamp", no matter whether the value of "Timestamp" is empty (current time) or non-empty (specified time). This parameter is used for moving the timestamp (which is used as signing time by signature verification) slightly into the future to cope with certificates generated on the fly on other systems with the validity period beginning at the current time: if the clock of the system that generates the certificate is ahead of the clock of the system that signs the document, the certificate will be used outside its validity period unless this parameter is set to a sufficiently positive value. The value must be small enough to keep the signing time before the end of validity period of the certificate. This value is ignored if the value of string parameter "Timestamp" is "-" (PDF only). The default value is zero.
  • TimeStampRetries The maximum number of retries for obtaining an RFC 3161 timestamp after a timeout. The default value is 0. See also string parameter "TimeStampServerURL".
  • TimeStampServerTimeout Timeout in milliseconds for retrieving a time stamp from an RFC 3161 time-stamp server. The value must be positive. The default value is 10000. See also string parameter "TimeStampServerURL".
  • TimeStampSize If the value of this parameter is positive, add this many octets for the RFC 3161 timestamp to the anticipated size of the PKCS #7 message. If the value is zero or negative, a dummy time stamping request will be sent to the time-stamp server and the value of this parameter will be subtracted from the size of the response; as the response will be wrapped in an attribute, the value of this parameter should be smaller than -25. The default value is 8192. See also string parameter "TimeStampServerURL".
Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter.
See also
getInteger()
void setLength ( string  aName,
LengthType  aType,
double  aValue 
)

Set a length parameter.

Available length parameters are:

  • FontSize The maximum font size. For DigSig signature fields, this parameter defines the maximum font size for the appearance stream of PDF documents. The font size will be reduced to make all text lines fit horizontally into the signature field. The default value depends on the profile passed to SignDocDocument.createSignatureParameters():
    ProfileValue
    "" LengthType.FieldHeight and 0.1
    "image"LengthType.FieldHeight and 0.1
    See also string parameter "FontName", color parameter "TextColor", and blob parameter "Template".
  • ImageMargin The margin to add around the image. For DigSig signature fields, this parameter defines the margin to be added around the image in the appearance stream of PDF documents. This margin is added at all four edges of the image. The default value depends on the profile passed to SignDocDocument.createSignatureParameters().
    ProfileValue
    "" LengthType.Abs and 1.0
    "image"LengthType.Abs and 1.0
    See also blob parameter "Template".
  • TextHMargin The horizontal margin for text. For DigSig signature fields, this parameter defines the horizontal margin of text in the appearance stream of PDF documents. The margin will be added on both sides of the text. The default value depends on the profile passed to SignDocDocument.createSignatureParameters():
    ProfileValue
    "" LengthType.FieldHeight and 0.1
    "image"LengthType.FieldHeight and 0.1
    See also blob parameter "Template".
Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aTypeDefine how the length is specified.
[in]aValueThe value of the parameter.
See also
getLength(), getLengthType()
void setPasswordProvider ( PasswordProvider  aPasswordProvider)

Set an object which asks the user for a password.

By default, SignDoc SDK uses the method specified by string parameter "PasswordProvider" for asking the user for a password. You can use your own dialog by calling this function.

See de.softpro.doc.PasswordProvider for details. See also string parameter "PasswordProvider".

Parameters
[in]aPasswordProviderThe object that will let the user select a certificate.
See also
hasCallback()
void setPKCS7 ( SignPKCS7  aPKCS7)

Set an object which will create a PKCS #7 or CAdES signature.

By default, PKCS #7 and CAdES signatures are handled internally which means that the private key must be available on this machine.

Requirements for string parameters:

  • CommonName must not be set
  • Country must not be set
  • GenerateECCKeyPair must not be set
  • Locality must not be set
  • Organization must not be set
  • OrganizationUnit must not be set

Requirements for integer parameters:

Requirements for blob parameters:

  • Certificate must not be set
  • CertificatePrivateKey must not be set

setRSA(), setECDSA(), and setDSA() must not have been called

The SignPKCS7 interface is quite hard to use, please use setRSA() and the SignRSA interface or setECDSA() and the SignECDSA interface or setDSA() and the SignDSA interface instead.

Parameters
[in]aPKCS7The object that will create the PKCS #7 or CAdES signature.
See also
hasCallback(), setDSA(), setECDSA(), setRSA(), setTimeStamper()
void setRSA ( SignRSA  aRSA)

Set an object which will compute an RSA signature.

By default, RSA signatures are computed internally which means that the private key must be available on this machine.

Requirements for string parameters:

  • GenerateECCKeyPair must not be set

Requirements for integer parameters:

  • GenerateKeyPair must not be set
  • SelectCertificate must be zero (which is the default value)

Requirements for blob parameters:

  • Certificate must not be set
  • CertificatePrivateKey must not be set

setDSA(), setECDSA(), and setPKCS7() must not have been called

Parameters
[in]aRSAThe object that will compute the RSA signature.
See also
hasCallback(), setDSA(), setECDSA(), setPKCS7()
void setString ( string  aName,
string  aValue 
)

Set a string parameter.

Available string parameters are:

  • Adviser The adviser. For DigSig signature fields, the adviser may be used for the appearance stream of PDF documents. The default value is empty. Complex scripts are supported, see Complex Scripts.
  • BiometricKeyPath The pathname of a file containing the public key in PKCS #1 or X.509 format for encrypting the biometric data with integer parameter "BiometricEncryption" set to BiometricEncryption.RSA. See also blob parameter "BiometricKey" and Encryption of biometric data. See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.
  • BiometricPassphrase Passphrase to be used if integer parameter "BiometricEncryption" is BiometricEncryption.Passphrase. Should contain ASCII characters only.
  • CertificatePicker How to let the user pick a certificate. The following values are available:
    • "console": ask for the certificate on the console (/dev/tty or CONIN$)
    • "fail": the operation will fail due to no password being available
    • "gtk3": use a GTK 3 dialog
    • "wx": use a wxWidgets dialog (any version), currently equivalent to "wx3.2"
    • "wx3.2": use a wxWidgets 3.2 dialog
    The default value is "wx". See CertificateSelectionFlags.Software, CertificateSelectionFlags.Hardware, and CertificateSelectionFlags.NeverAsk. This parameter is ignored if setCertificatePicker() has been called with a non-null argument.
  • CertificateSigningAlgorithm The signing algorithm for the self-signed certificate:
    • "ECDSA-SHA-1"
    • "ECDSA-SHA-224"
    • "ECDSA-SHA-256"
    • "ECDSA-SHA-384"
    • "ECDSA-SHA-512"
    • "ECDSA-SHA3-256"
    • "ECDSA-SHA3-384"
    • "ECDSA-SHA3-512"
    • "RSA-MD5"
    • "RSA-RIPEMD-160"
    • "RSA-SHA-1"
    • "RSA-SHA-256"
    • "RSA-SHA-384"
    • "RSA-SHA-512"
    • "RSA-SHA3-256"
    • "RSA-SHA3-384"
    • "RSA-SHA3-512"
    If a self-signed certificate is to be generated, the signing algorithm can be set. If not set, a suitable default value will be used.
  • Comment The comment. For DigSig signature fields, the comment may be used for the appearance stream of PDF documents. The comment can contain multiple lines which are separated by '
    '. The default value is empty. Complex scripts are supported, see Complex Scripts.
  • CommonName The common name for the self-signed certificate. If a self-signed certificate is to be generated, the common name (CN) must be set. See also string parameter "Signer".
  • ContactInfo The contact information provided by the signer. For DigSig signature fields, the contact information will be stored in the digital signature. For DigSig signature fields, the contact information may be used for the appearance stream of PDF documents. The default value is empty. Complex scripts are supported, see Complex Scripts.
  • Country The country name for the self-signed certificate. If a self-signed certificate is to be generated, the country name (C) should be set. Use ISO 3166 country codes. The default value is empty.
  • DetachedHashAlgorithm Hash algorithm to be used for a detached signature (ie, if integer parameter "Method" is SigningMethod.DigSigPKCS7Detached or SigningMethod.DigSigCadesDetached. The following values are supported:
    • "default": default hash algorithm. For RSA, use the hash algorithm specified by the DigestMethod values of the signature field seed value dictionary or, if not present, SHA-256 (if supported), or SHA-1 (as last resort). For ECDSA, use the hash algorithm recommended for the elliptic curve used by the signing certificate's key.
    • "RIPEMD-160". Not supported under Windows.
    • "SHA-1". Deprecated, but supported everywhere.
    • "SHA-224". Supported for ECDSA signatures only.
    • "SHA-256". If SHA-256 is selected but not supported, SignDocDocument.addSignature() will fall back to SHA-1.
    • "SHA-384". If SHA-384 is selected but not supported, SignDocDocument.addSignature() will fall back to SHA-1.
    • "SHA-512". If SHA-384 is selected but not supported, SignDocDocument.addSignature() will fall back to SHA-1.
    • "SHA3-256".
    • "SHA3-384".
    • "SHA3-512".
    The default value is "default". See also integer parameters "Method" and "IgnoreSeedValues".
  • Filter The name of the preferred filter. For DigSig signature fields, the filter name will be stored in the digital signature. The default value is "SOFTPRO DigSig Security". You might want to set the filter to "Adobe.PPKLite".
  • FilterCertificatesByPolicy A required certificate policy. Setting this parameter adds the specified OID to a list of required policy object identifiers. All specified policies are required for a certificate to be accepted. Pass an empty value to clear the list. The value must be a valid ASN.1 object identifier. A PDF document may contain (in its certificate seed value dictionaries) additional restrictions for acceptable certificates. SignDocDocument.addSignature() will fail if no matching certificate is available for signing. Note that CertificateSelectionFlags.Software and/or CertificateSelectionFlags.Hardware must be included in integer parameter "SelectCertificate" to make certificates available at all.
  • FilterCertificatesBySubjectDN An acceptable subject Distinguished Name (DN). Setting this parameter adds the specified DN to a list of acceptable DNs. Pass an empty value to clear the list. The DN must be formatted according to RFC 4514, using short names for the attribute types. Multi-valued RDNs and multiple RDNs specifying a value for the same attribute are not allowed. A PDF document may contain (in its certificate seed value dictionaries) additional restrictions for acceptable certificates. SignDocDocument.addSignature() will fail if no matching certificate is available for signing. Note that CertificateSelectionFlags.Software and/or CertificateSelectionFlags.Hardware must be included in integer parameter "SelectCertificate" to make certificates available at all.
  • FontName The name of the font to be used for text in the appearance of a DigSig signature field in a PDF document. The font name can be the name of a standard font, the name of an already embedded font, or the name of a font defined by a font configuration file. If the name is empty, the font name will be taken from the field's text field attributes. If the field doesn't have text field attributes, the document's text field attributes will be used. If this also fails, standard font Helvetica will be used (which will break PDF/A conformance). The default value is empty. See also length parameter "FontSize", color parameter "TextColor", and blob parameter "Template".
  • GenerateECCKeyPair Start generation of an elliptic curve key pair for the self-signed certificate if non-empty. The value is the name or the object identifier of the curve, e.g., prime256v1. If a self-signed certificate is to be generated, the private key can either be generated by setting this parameter or set as blob parameter "CertificatePrivateKey". The default value is empty. See also integer parameter "GenerateKeyPair". "GenerateECCKeyPair" and "GenerateKeyPair" are mutually exclusive.
  • LegalAttestation "An attestation, created by the author of the document, explaining the presence of [...] any [...] content affecting the legal integrity of the document." This parameter should be set if creating a certification signature (see integer parameter DocMDP). It must not be set for other signatures. See also SignDocDocument.getLegalAttestation().
  • Locality The location name for the self-signed certificate. If a self-signed certificate is to be generated, the location name (L) should be set. The default value is empty. Do not confuse "Locality" and "Location"!
  • Location The host name or physical location of signing. For DigSig signature fields, the location will be stored in the digital signature. For DigSig signature fields, the location may be used for the appearance stream of PDF documents. The default value is empty. Complex scripts are supported, see Complex Scripts. Do not confuse "Location" and "Locality"!
  • Next The next step to be performed for multi-phase signing. This parameter is set by SignDocDocument.addSignature(), any value set with setString() is ignored. The following values are defined:
    • "": signing complete (successfully or failed).
    • "DSA": provide a DSA signature in blob parameter "MultiPhaseData" in the next step.
    • "ECDSA": provide an ECDSA signature in blob parameter "MultiPhaseData" in the next step.
    • "PKCS7": provide a PKCS #7 message in blob parameter "MultiPhaseData" in the next step.
    • "RSA": provide an RSA signature in blob parameter "MultiPhaseData" in the next step.
    • "TimeStamper": provide a time-stamp token or a time-stamp response in blob parameter "MultiPhaseData" in the next step.
    See also boolean parameters "MultiPhase" and "LastPhase".
  • Organization The organization name for the self-signed certificate. If a self-signed certificate is to be generated, the organization name (O) should be set. The default value is empty.
  • OrganizationUnit The organization unit name for the self-signed certificate. If a self-signed certificate is to be generated, the organization unit name (OU) should be set. The default value is empty.
  • OutputPath Specify the file to which the signed document shall be saved. If this parameter is non-empty, the file backing the document, if any, won't be modified. If this parameter is empty and the document is backed by a file (ie, the last load or save operation was from or to a file, respectively) and either single-phase signing is used or this is the last phase of multi-phase signing (see boolean parameters "MultiPhase" and "LastPhase"), the signed document will be written to that file. The special value "<memory>" causes the document to be saved to and signed in memory (available for PDF documents only). The default value is empty. See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.
  • PasswordProvider How to ask the user for a password. If string parameter "PKCS#11Module" is set and string parameter "PKCS#11Password" is not set or if a PKCS #12 blob is passed in blob parameter "Certificate" and string parameter "PKCS#12Password" is not set, SignDoc SDK may have to ask the user for a password. The following values are available:
    • "console": ask for the password on the console (/dev/tty or CONIN$)
    • "gtk3": use a GTK 3 dialog
    • "none": let the PKCS #11 provider handle authentication, use empty password for PKCS #12
    • "wx": use a wxWidgets dialog (any version), currently equivalent to "wx3.2"
    • "wx3.2": use a wxWidgets 3.2 dialog
    The default value is "console". This parameter is ignored if "PKCS#11Password" is set or setPasswordProvider() has been called with a non-null argument.
  • PKCS#11Module The pathname of a PKCS #11 module (library) to be used for CertificateSelectionFlags.Hardware.
  • PKCS#11Password The password for logging into the PKCS #11 token. If empty, the user will be prompted for the password. See also string parameter "PasswordProvider".
  • PKCS#12Password The password for extracting the private key from the PKCS #12 blob set as blob parameter "Certificate". The encoding is UTF-8. See also string parameter "PasswordProvider".
  • Reason The reason for the signing. For DigSig signature fields, the reason will be stored in the digital signature. For DigSig signature fields, the reason may be used for the appearance stream of PDF documents. The default value is empty. Complex scripts are supported, see Complex Scripts.
  • RSASignatureScheme The RSA signature scheme to be used for PKCS #7 signatures with RSA keys:
    • "PKCS1": PKCS #1 (RSA v1.5). This signature scheme should be supported by all software that verifies DigSig signatures in PDF documents. However, it is considered obsolete due to security concerns.
    • "PSS": Probabilistic Signature Scheme (PSS) (RSA v2.0 and v2.1). Improved signature scheme, more secure than PKCS #1. However, this signature scheme may not be supported by all software that verifies DigSig signatures in PDF documents. For instance, Adobe Acrobat DC supports RSA-PSS since April 2017 (Windows) and August 2017 (MacOS). When using a certificate from a Windows certificate store (see integer parameter "SelectCertificate"), the private key must be provided by a CNG Key Storage Provider.
    The default value is "PKCS1".
  • SelectCertificateMessage A message to be displayed in the certificate selection dialog, see integer parameter "SelectCertificate".
  • SelectCertificateTitle The title of the certificate selection dialog, see integer parameter "SelectCertificate". A localized version of "Select Certificate" will be used if empty or not set.
  • Signer The signer name. This is the signer name that will be stored in the digital signature. If not set, the name will be taken from the signing certificate. For DigSig signature fields, the signer name may be used for the appearance stream of PDF documents. The default value is empty (meaning that the name will be taken from the certificate). See also string parameter "CommonName". Complex scripts are supported, see Complex Scripts.
  • SignTime The time of signing in free format. For DigSig signature fields, the time of signing may be used for the appearance stream of PDF documents. The default value is empty. See also string parameter "Timestamp".
  • Text1 A text to be included in the appearance stream of DigSig signature fields in PDF documents. The text can contain multiple lines which are separated by '
    '. The default value is empty. Complex scripts are supported, see Complex Scripts. See also blob parameter "Template".
  • Text2 See Text1.
  • Text3 See Text1.
  • Text4 See Text1.
  • Text5 See Text1.
  • Text6 See Text1.
  • Text7 See Text1.
  • Text8 See Text1.
  • Text9 See Text1.
  • Timestamp The timestamp to be used in the digital signature (instead of the current time). ISO 8601 format must be used: "yyyy-mm-ddThh:mm:ss" with optional timezone. For DigSig signature fields (PDF), the timestamp will be stored in the signature dictionary (transformed suitably for the M entry). If empty, the current time will be used. If the value is "-", the M entry will be omitted (this is only allowed if the PKCS #7 message contains a signingTime or timeStampToken attribute; note that the signingTime attribute is not allowed for method SigningMethod.DigSigCadesDetached). If the value is "TSA", the timestamp will be retrieved from the RFC 3161 time-stamp server configured by string parameter "TimeStampServerURL" (possibly overriden by the field's seed values) or from the UserTimeStamper set with setTimeStamper(). This parameter doesn't have an effect for document time stamps. For TIFF documents, the timestamp from the time-stamp server won't be used for string parameter "Timestamp" of SignDocVerificationResult.getSignatureString(). The timestamp from the time-stamp server will also be used as start of validity (notBefore) of the generated self-signed certificate (if generation of a self-signed certificate is configured). The default value is empty. See also string parameters "SignTime" and "TimeStampServerURL".
  • TimeStampClientCertificatePath The pathname of a file containing the certificate in PEM format for authenticating to an RFC 3161 time-stamp server over HTTPS. If the is non-empty, string parameter "TimeStampClientKeyPath" must also be set. If the value is empty, the client won't authenticate itself. The default value is empty. See also string parameters "TimeStampServerURL", and "TimeStampClientKeyPath". See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.
  • TimeStampClientKeyPath The pathname of a file containing the private key in PEM format for authenticating to an RFC 3161 time-stamp server over HTTPS. If the is non-empty, string parameter "TimeStampClientCertificatePath" must also be set. If the value is empty, the client won't authenticate itself. The default value is empty. See also string parameters "TimeStampServerURL" and "TimeStampClientKeyPath". See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.
  • TimeStampHashAlgorithm Hash algorithm for RFC 3161 time stamps:
    • "default": use a default value. For signatures, use the same hash algorithm as used for the document hash. For document time stamps, SHA-256 (if supported by the time stamp server) SHA-1 (if SHA-256 is not supported by the time stamp server) will be used. The hash algorithm requested for the document hash will be used for the time stamp even if the document hash falls back to SHA-1 (see "default" for string parameter "DetachedHashAlgorithm"). SHA-256 will be used if the document hash is SHA-224. SHA-256 will be used if string parameter "DetachedHashAlgorithm" is "default" and the document hash is SHA-384 or SHA-512 (this can happen for keys using certain elliptic curves).
    • "SHA-1"
    • "SHA-256"
    • "SHA-384"
    • "SHA-512"
    The default value is "default". See also string parameter "TimeStampServerURL".
  • TimeStampServerPassword The password for Basic/Digest HTTP authentication to the time-stamp server. Non-ASCII values probably don't work. If this parameter is set, string parameter "TimeStampServerUser" must also be set.
  • TimeStampServerURL The URL of an RFC 3161 time-stamp server. If string parameter "Timestamp" is empty and string parameter "TimeStampServerURL" is non-empty, a time stamp will be obtained from a time-stamp server. The scheme of the URL must be either "http" or "https". The time-stamp server URL specified by the document's signature field seed value dictionary overrides the "TimeStampServerURL" parameter unless IgnoreSeedValues.TimeStamp is set in integer parameter "IgnoreSeedValues". An error will be returned by SignDocDocument.addSignature() if a time-stamp server is to be used and integer parameter "Method" is not SigningMethod.DigSigPKCS7Detached, SigningMethod.DigSigPKCS7SHA1, or SigningMethod.DigSigCadesDetached. See also integer parameters "TimeStampRetries", "TimeStampServerTimeout", and "TimeStampSize", and string parameters "TimeStampClientCertificatePath", "TimeStampClientKeyPath", "TimeStampHashAlgorithm", "TimeStampServerPassword", "TimeStampServerUser", and "TimeStampUserAgent". See also SignDocDocumentLoader.loadTrustedCertificatesFromFile(), SignDocDocumentLoader.loadTrustedCertificatesFromMemory(), and SignDocDocumentLoader.loadTrustedCertificatesFromStream().
  • TimeStampServerUser The user name for Basic/Digest HTTP authentication to the time-stamp server. Non-ASCII values probably don't work. If this parameter is set, string parameter "TimeStampServerPassword" must also be set.
  • TimeStampUserAgent The value of the User-Agent header field sent to the time-stamp server. The default value is "SignDoc".

Additionally, you can store your own strings in the signature by using a name starting with "Prop_", except for "Prop_AuthTime", "Prop_AuthType", "Prop_Build", and any name starting with "Prop_BiometricData", see SignDocVerificationResult.getSignatureString(). The name shall contain the following characters only: 0-9, a-z, A-Z, '-', and '_'. The length of the value is restricted for PDF documents and depends on the characters being used; the value encoded as PDF text string shall not exceed 32767 octets.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter.
See also
getString()
void setTextItemDirection ( string  aItem,
SignatureParametersHAlignment  aHAlignment,
TextItemDirection  aDirection 
)

Set the paragraph direction of text items.

This function sets the paragraph direction of all existing text items matching aItem.

See also blob parameter "Template".

Parameters
[in]aItemSelect the text items:
  • Signer String parameter "Signer".
  • SignTime String parameter "SignTime".
  • Comment String parameter "Comment".
  • Adviser String parameter "Adviser".
  • ContactInfo String parameter "ContactInfo".
  • Location String parameter "Location".
  • Reason String parameter "Reason".
  • Text1 String parameter "Text1".
  • Text2 String parameter "Text2".
  • Text3 String parameter "Text3".
  • Text4 String parameter "Text4".
  • Text5 String parameter "Text5".
  • Text6 String parameter "Text6".
  • Text7 String parameter "Text7".
  • Text8 String parameter "Text8".
  • Text9 String parameter "Text9".
[in]aHAlignmentHorizontal alignment. This value overrides integer parameter "TextHAlignment" unless it is SignatureParametersHAlignment.Default.
[in]aDirectionThe paragraph direction, see enum TextItemDirection. 0 is treated like TextItemDirection.LTR.
See also
addTextItem()
void setTimeStamper ( UserTimeStamper  aTimeStamper)

Set an object which will create an RFC 3161 time stamp.

By default, RFC 3161 time stamps are created by asking the TSA configured in string parameter TimeStampServerURL.

See UserTimeStamper for details.

Parameters
[in]aTimeStamperThe object that will create the RFC 3161 time stamp.
See also
hasCallback(), setPKCS7()