SignDoc SDK (.NET without exceptions)
5.0.0
|
Parameters for signing a document. More...
Public Member Functions | |
~SignDocSignatureParameters () | |
Destructor. More... | |
!SignDocSignatureParameters () | |
Finalizer. More... | |
void | setString (out ReturnCode aReturnCode, string aName, string aValue) |
Set a string parameter. More... | |
void | setInteger (out ReturnCode aReturnCode, string aName, int aValue) |
Set an integer parameter. More... | |
void | setBlob (out ReturnCode aReturnCode, string aName, byte[] aValue) |
Set a blob parameter. More... | |
void | setLength (out ReturnCode aReturnCode, string aName, LengthType aType, double aValue) |
Set a length parameter. More... | |
void | setColor (out ReturnCode aReturnCode, string aName, SignDocColor aValue) |
Set a color parameter. More... | |
void | addTextItem (out ReturnCode aReturnCode, string aItem, TextGroup aGroup) |
Add another string to be displayed, top down. More... | |
void | addTextItem2 (out ReturnCode aReturnCode, string aItem, TextGroup aGroup, SignatureParametersHAlignment aHAlignment, TextItemDirection aDirection) |
Add another string to be displayed, top down, with paragraph direction. More... | |
void | clearTextItems (out ReturnCode aReturnCode) |
Remove all strings that were to be displayed. More... | |
void | setTextItemDirection (out ReturnCode aReturnCode, string aItem, SignatureParametersHAlignment aHAlignment, TextItemDirection aDirection) |
Set the paragraph direction of text items. More... | |
void | setPKCS7 (out ReturnCode aReturnCode, SignPKCS7 aPKCS7) |
Set an object which will create a PKCS #7 or CAdES signature. More... | |
void | setRSA (out ReturnCode aReturnCode, SignRSA aRSA) |
Set an object which will compute an RSA signature. More... | |
void | setECDSA (out ReturnCode aReturnCode, SignECDSA aECDSA) |
Set an object which will compute an ECDSA signature. More... | |
SigningMethodFlags | getAvailableMethods () |
Get a bitset indicating which signing methods are available for this signature field. More... | |
byte[] | getTemplate (out ReturnCode aReturnCode) |
Get an XML document specifying the current layout. 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... | |
Parameters for signing a document.
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. 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.
Additionally:
For TIFF documents, an additional, simplified signing method is available:
The following parameters control the signing method and related aspects of the signature:
The following parameters control the private key used for signing:
The following parameters control rendering of the signature image from biometric data:
The following parameters put additional data into the signature:
The following parameters provide texts for the appearance of a signature in PDF documents:
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"):
The following parameters control the signing certificate:
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):
The following parameters are used for putting biometric data (handwritten signature) into the signature:
The following parameters control the certificate selection dialog:
The following parameters control RFC 3161 timestamps:
The following parameters put additional certificates and revocation information into the signature:
The following parameters do not fall into the above categories:
Destructor.
Finalizer.
void addTextItem | ( | out ReturnCode | aReturnCode, |
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():
Profile | Value |
---|---|
"" | "Signer"/TextGroup.Master, "SignTime"/TextGroup.Master |
"image" | (empty) |
The paragraph direction is 0 which is treated like TextItemDirection.LTR.
See also blob parameter "Template".
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
[in] | aItem | Select the string to be added:
|
[in] | aGroup | The string's group for font size computation. |
void addTextItem2 | ( | out ReturnCode | aReturnCode, |
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():
Profile | Value |
---|---|
"" | #"Signer"/TextGroup.Master, "SignTime"/TextGroup.Master |
"image" | (empty) |
See also blob parameter "Template".
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
[in] | aItem | Select the string to be added:
|
[in] | aGroup | The string's group for font size computation. |
[in] | aHAlignment | Horizontal alignment. This value overrides integer parameter "TextHAlignment" unless it is SignatureParametersHAlignment.Default. |
[in] | aDirection | The paragraph direction, see enum TextItemDirection. 0 is treated like TextItemDirection.LTR. |
void clearTextItems | ( | out ReturnCode | aReturnCode | ) |
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".
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
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.
string getErrorMessage | ( | ) |
Get an error message for the last function call.
byte [] getTemplate | ( | out ReturnCode | aReturnCode | ) |
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.
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
|
static |
Get the type of a parameter.
[in] | aName | The name of the parameter (case-sensitive). |
void setBlob | ( | out ReturnCode | aReturnCode, |
string | aName, | ||
byte[] | aValue | ||
) |
Set a blob parameter.
Available blob parameters are:
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 '_'.
[out] | aReturnCode | The return code, ReturnCode.OK if successful, ReturnCode.UnknownParameter if aName is not the name of a blob parameter, ReturnCode.InvalidValue if aValue is invalid. |
[in] | aName | The name of the parameter (case-sensitive). |
[in] | aValue | The value. |
void setColor | ( | out ReturnCode | aReturnCode, |
string | aName, | ||
SignDocColor | aValue | ||
) |
Set a color parameter.
Available color parameters are:
[out] | aReturnCode | The return code, ReturnCode.OK if successful, ReturnCode.UnknownParameter if aName is not the name of a color parameter, ReturnCode.InvalidValue if aValue is invalid. |
[in] | aName | The name of the parameter (case-sensitive). |
[in] | aValue | The value of the parameter. |
void setECDSA | ( | out ReturnCode | aReturnCode, |
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:
Requirements for integer parameters:
Requirements for blob parameters:
setRSA() and setPKCS7() must not have been called
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
[in] | aECDSA | The object that will compute the ECDSA signature. |
void setInteger | ( | out ReturnCode | aReturnCode, |
string | aName, | ||
int | aValue | ||
) |
Set an integer parameter.
Available integer parameters are:
Profile | Value |
---|---|
"" | SignatureParametersHAlignment.Center |
"image" | SignatureParametersHAlignment.Center |
Profile | Value |
---|---|
"" | SignatureParametersVAlignment.Top |
"image" | SignatureParametersHAlignment.Center |
Profile | Value |
---|---|
"" | SignatureParametersHAlignment.Center |
"image" | SignatureParametersHAlignment.Center |
Profile | Value |
---|---|
"" | TextPosition.Below |
"image" | TextPosition.Overlay |
Profile | Value |
---|---|
"" | SignatureParametersVAlignment.Bottom |
"image" | SignatureParametersHAlignment.Center |
[out] | aReturnCode | The return code, ReturnCode.OK if successful, ReturnCode.UnknownParameter if aName is not the name of an integer parameter, ReturnCode.InvalidValue if aValue is invalid. |
[in] | aName | The name of the parameter (case-sensitive). |
[in] | aValue | The value of the parameter. |
void setLength | ( | out ReturnCode | aReturnCode, |
string | aName, | ||
LengthType | aType, | ||
double | aValue | ||
) |
Set a length parameter.
Available length parameters are:
Profile | Value |
---|---|
"" | LengthType.FieldHeight and 0.1 |
"image" | LengthType.FieldHeight and 0.1 |
Profile | Value |
---|---|
"" | LengthType.Abs and 1.0 |
"image" | LengthType.Abs and 1.0 |
Profile | Value |
---|---|
"" | LengthType.FieldHeight and 0.1 |
"image" | LengthType.FieldHeight and 0.1 |
[out] | aReturnCode | The return code, ReturnCode.OK if successful, ReturnCode.UnknownParameter if aName is not the name of a length parameter, ReturnCode.InvalidValue if aValue is invalid. |
[in] | aName | The name of the parameter (case-sensitive). |
[in] | aType | Define how the length is specified. |
[in] | aValue | The value of the parameter. |
void setPKCS7 | ( | out ReturnCode | aReturnCode, |
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:
Requirements for integer parameters:
Requirements for blob parameters:
setRSA() and setECDSA() 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 instead.
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
[in] | aPKCS7 | The object that will create the PKCS #7 or CAdES signature. |
void setRSA | ( | out ReturnCode | aReturnCode, |
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:
Requirements for integer parameters:
Requirements for blob parameters:
setECDSA() and setPKCS7() must not have been called
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
[in] | aRSA | The object that will compute the RSA signature. |
void setString | ( | out ReturnCode | aReturnCode, |
string | aName, | ||
string | aValue | ||
) |
Set a string parameter.
Available string parameters are:
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.
[out] | aReturnCode | The return code, ReturnCode.OK if successful, ReturnCode.UnknownParameter if aName is not the name of a string parameter, ReturnCode.InvalidValue if aValue is invalid. |
[in] | aName | The name of the parameter (case-sensitive). |
[in] | aValue | The value of the parameter. |
void setTextItemDirection | ( | out ReturnCode | aReturnCode, |
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".
[out] | aReturnCode | The return code, ReturnCode.OK iff successful. |
[in] | aItem | Select the text items:
|
[in] | aHAlignment | Horizontal alignment. This value overrides integer parameter "TextHAlignment" unless it is SignatureParametersHAlignment.Default. |
[in] | aDirection | The paragraph direction, see enum TextItemDirection. 0 is treated like TextItemDirection.LTR. |