SignDoc SDK (C)  5.0.0
Public Member Functions | List of all members
SIGNDOC_VerificationResult Class Reference

Information about a signature field returned by SIGNDOC_Document_verifySignature() or SIGNDOC_Document_verifySignature2(). More...

#include <SignDocSDK-c.h>

Public Member Functions

void SIGNDOC_VerificationResult_delete (struct SIGNDOC_VerificationResult *aObj)
 SIGNDOC_VerificationResult destructor. More...
 
int SIGNDOC_VerificationResult_getState (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the signature state. More...
 
int SIGNDOC_VerificationResult_getModificationState (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the modification state of a PDF document. More...
 
int SIGNDOC_VerificationResult_getMethod (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the signing method. More...
 
int SIGNDOC_VerificationResult_getDocMDP (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj)
 Get the DocMDP P value of a certification signature. More...
 
int SIGNDOC_VerificationResult_getLockMDP (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj)
 Get the lock MDP value of the signature. More...
 
int SIGNDOC_VerificationResult_getDigestAlgorithm (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, char **aOutput)
 Get the message digest algorithm of the signature. More...
 
int SIGNDOC_VerificationResult_getCertificates (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, struct SIGNDOC_ByteArrayArray *aOutput)
 Get the certificates of the signature. More...
 
int SIGNDOC_VerificationResult_verifyCertificateChain (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const struct SIGNDOC_VerificationParameters *aParameters, int *aOutput)
 Verify the certificate chain of the signature's certificate. More...
 
int SIGNDOC_VerificationResult_getCertificateRevocationState (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the revocation state of the certificate chain of the signature's certificate. More...
 
int SIGNDOC_VerificationResult_verifyCertificateSimplified (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const struct SIGNDOC_VerificationParameters *aParameters)
 Simplified verification of the certificate chain and revocation status of the signature's certificate. More...
 
int SIGNDOC_VerificationResult_getCertificateChainLength (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the certificate chain length. More...
 
int SIGNDOC_VerificationResult_getSignatureString (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int aEncoding, const char *aName, char **aOutput)
 Get a string parameter from the signature field. More...
 
int SIGNDOC_VerificationResult_getSignatureBlob (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const char *aName, struct SIGNDOC_ByteArray *aOutput)
 Get a blob property from the signature field. More...
 
int SIGNDOC_VerificationResult_getBiometricData (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int aEncoding, const unsigned char *aKeyPtr, size_t aKeySize, const char *aKeyPath, const char *aPassphrase, struct SIGNDOC_ByteArray *aOutput)
 Get the biometric data of the field. More...
 
int SIGNDOC_VerificationResult_getBiometricDataW (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const unsigned char *aKeyPtr, size_t aKeySize, const wchar_t *aKeyPath, const char *aPassphrase, struct SIGNDOC_ByteArray *aOutput)
 Get the biometric data of the field. More...
 
int SIGNDOC_VerificationResult_getEncryptedBiometricData (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, struct SIGNDOC_ByteArray *aOutput)
 Get the encrypted biometric data of the field. More...
 
int SIGNDOC_VerificationResult_getBiometricEncryption (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the encryption method used for biometric data of the signature field. More...
 
int SIGNDOC_VerificationResult_checkBiometricHash (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const unsigned char *aBioPtr, size_t aBioSize, SIGNDOC_Boolean *aOutput)
 Check the hash of the biometric data. More...
 
int SIGNDOC_VerificationResult_getTimeStampState (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the state of the RFC 3161 time stamp. More...
 
int SIGNDOC_VerificationResult_getTimeStampDigestAlgorithm (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, char **aOutput)
 Get the message digest algorithm of the RFC 3161 timestamp. More...
 
int SIGNDOC_VerificationResult_verifyTimeStampCertificateChain (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const struct SIGNDOC_VerificationParameters *aParameters, int *aOutput)
 Verify the certificate chain of the RFC 3161 time stamp. More...
 
int SIGNDOC_VerificationResult_getTimeStampCertificateRevocationState (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int *aOutput)
 Get the revocation status of the certificate chain of the RFC 3161 time stamp. More...
 
int SIGNDOC_VerificationResult_verifyTimeStampCertificateSimplified (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, const struct SIGNDOC_VerificationParameters *aParameters)
 Simplified verification of the certificate chain and revocation status of the RFC 3161 time stamp. More...
 
int SIGNDOC_VerificationResult_getTimeStamp (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, char **aOutput)
 Get the value of the RFC 3161 time stamp. More...
 
int SIGNDOC_VerificationResult_getTimeStampCertificates (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, struct SIGNDOC_ByteArrayArray *aOutput)
 Get the certificates of the RFC 3161 time stamp. More...
 
const char * SIGNDOC_VerificationResult_getErrorMessage (struct SIGNDOC_Exception **aEx, struct SIGNDOC_VerificationResult *aObj, int aEncoding)
 Get an error message for the last function call. More...
 
const wchar_t * SIGNDOC_VerificationResult_getErrorMessageW (struct SIGNDOC_Exception **aEx, const struct SIGNDOC_VerificationResult *aObj)
 Get an error message for the last function call. More...
 

Detailed Description

Information about a signature field returned by SIGNDOC_Document_verifySignature() or SIGNDOC_Document_verifySignature2().

If the SIGNDOC_Document object is destroyed before the SIGNDOC_VerificationResult objects returned by its SIGNDOC_Document_verifySignature() and SIGNDOC_Document_verifySignature2() functions, some functions may fail.

Member Function Documentation

int SIGNDOC_VerificationResult_checkBiometricHash ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const unsigned char *  aBioPtr,
size_t  aBioSize,
SIGNDOC_Boolean *  aOutput 
)

Check the hash of the biometric data.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aBioPtrPointer to unencrypted biometric data, typically retrieved by getBiometricData().
[in]aBioSizeSize of unencrypted biometric data in octets.
[out]aOutputResult of the operation: SIGNDOC_TRUE if the hash is OK, SIGNDOC_FALSE if the hash doesn't match (the document has been tampered with).
Returns
SIGNDOC_RETURNCODE_OK iff successful.
See also
SIGNDOC_VerificationResult_getBiometricData(), SIGNDOC_VerificationResult_getEncryptedBiometricData(), SIGNDOC_VerificationResult_getMethod()
void SIGNDOC_VerificationResult_delete ( struct SIGNDOC_VerificationResult *  aObj)

SIGNDOC_VerificationResult destructor.

Parameters
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
int SIGNDOC_VerificationResult_getBiometricData ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int  aEncoding,
const unsigned char *  aKeyPtr,
size_t  aKeySize,
const char *  aKeyPath,
const char *  aPassphrase,
struct SIGNDOC_ByteArray *  aOutput 
)

Get the biometric data of the field.

Use SIGNDOC_VerificationResult_getBiometricEncryption() to find out what parameters need to be passed:

Note
Don't forget to overwrite the biometric data in memory after use!

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aEncodingThe encoding of the string pointed to by aKeyPath (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]aKeyPtrPointer to the first octet of the key (must be NULL if aKeyPath is not NULL).
[in]aKeySizeSize of the key pointed to by aKeyPtr (must be 0 if aKeyPath is not NULL).
[in]aKeyPathPathname of the file containing the key (must be NULL if aKeyPtr is not NULL). See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.
[in]aPassphrasePassphrase for decrypting the key contained in the file named by aKeyPath. If this argument is NULL or points to the empty string, it will be assumed that the key file is not protected by a passphrase. aPassphrase is used only when reading the key from a file for SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_RSA. The passphrase must contain ASCII characters only.
[in,out]aOutputThe decrypted biometric data will be stored here.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NO_BIOMETRIC_DATA if no biometric data is availabable.
See also
SIGNDOC_VerificationResult_checkBiometricHash(), SIGNDOC_VerificationResult_getBiometricEncryption(), SIGNDOC_VerificationResult_getEncryptedBiometricData(), SIGNDOC_VerificationResult_getMethod()
int SIGNDOC_VerificationResult_getBiometricDataW ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const unsigned char *  aKeyPtr,
size_t  aKeySize,
const wchar_t *  aKeyPath,
const char *  aPassphrase,
struct SIGNDOC_ByteArray *  aOutput 
)

Get the biometric data of the field.

Use SIGNDOC_VerificationResult_getBiometricEncryption() to find out what parameters need to be passed:

Note
Don't forget to overwrite the biometric data in memory after use!

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aKeyPtrPointer to the first octet of the key (must be NULL if aKeyPath is not NULL).
[in]aKeySizeSize of the key pointed to by aKeyPtr (must be 0 if aKeyPath is not NULL).
[in]aKeyPathPathname of the file containing the key (must be NULL if aKeyPtr is not NULL). See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.
[in]aPassphrasePassphrase for decrypting the key contained in the file named by aKeyPath. If this argument is NULL or points to the empty string, it will be assumed that the key file is not protected by a passphrase. aPassphrase is used only when reading the key from a file for SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_RSA. The passphrase must contain ASCII characters only.
[in,out]aOutputThe decrypted biometric data will be stored here.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NO_BIOMETRIC_DATA if no biometric data is availabable.
See also
SIGNDOC_VerificationResult_checkBiometricHash(), SIGNDOC_VerificationResult_getBiometricEncryption(), SIGNDOC_VerificationResult_getEncryptedBiometricData(), SIGNDOC_VerificationResult_getMethod()
int SIGNDOC_VerificationResult_getBiometricEncryption ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the encryption method used for biometric data of the signature field.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe encryption method: SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_RSA, SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_FIXED, SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_BINARY, or SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_PASSPHRASE.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NO_BIOMETRIC_DATA if no biometric data is availabable.
See also
SIGNDOC_VerificationResult_getBiometricData(), SIGNDOC_VerificationResult_getEncryptedBiometricData(), SIGNDOC_VerificationResult_getMethod()
int SIGNDOC_VerificationResult_getCertificateChainLength ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the certificate chain length.

SIGNDOC_VerificationResult_verifyCertificateChain() or SIGNDOC_VerificationResult_verifyCertificateSimplified() must have been called successfully.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod() and SIGNDOC_VerificationResult_getTimeStampCertificates().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe chain length will be stored here if this function is successful. If the signature was performed with a self-signed certificate, the chain length will be 1.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
See also
SIGNDOC_VerificationResult_getMethod(), SIGNDOC_VerificationResult_getTimeStampCertificates(), SIGNDOC_VerificationResult_verifyCertificateChain(), SIGNDOC_VerificationResult_verifyCertificateSimplified()
int SIGNDOC_VerificationResult_getCertificateRevocationState ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the revocation state of the certificate chain of the signature's certificate.

SIGNDOC_VerificationResult_verifyCertificateChain() must have been called successfully.

SIGNDOC_VerificationResult_getErrorMessage() will return an error message if this function fails (return value not SIGNDOC_RETURNCODE_OK) or the verification result returned in aOutput is not SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_OK.

If SIGNDOC_VERIFICATIONPARAMETERS_VERIFICATIONFLAGS_CHECK_REVOCATION was not set in integer parameter "VerificationFlags" for the most recent call to SIGNDOC_VerificationResult_verifyCertificateChain(), this function will return SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_NOT_CHECKED in aOutput.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod() and SIGNDOC_VerificationResult_getTimeStampCertificateRevocationState().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe result of the certificate revocation check: SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_OK, SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_NOT_CHECKED, SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_OFFLINE, SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_REVOKED, or SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_ERROR.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
See also
SIGNDOC_VerificationResult_getCertificateChainLength(), SIGNDOC_VerificationResult_getMethod(), SIGNDOC_VerificationResult_getTimeStampCertificateRevocationState(), SIGNDOC_VerificationResult_verifyCertificateChain(), SIGNDOC_VerificationResult_verifyCertificateSimplified()
int SIGNDOC_VerificationResult_getCertificates ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
struct SIGNDOC_ByteArrayArray *  aOutput 
)

Get the certificates of the signature.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod() and SIGNDOC_VerificationResult_getTimeStampCertificates().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in,out]aOutputThe ASN.1-encoded X.509 certificates will be stored here. If there are multiple certificates, the first one (at index 0) is the signing certificate.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
See also
SIGNDOC_VerificationResult_getMethod(), SIGNDOC_VerificationResult_getTimeStampCertificates()
int SIGNDOC_VerificationResult_getDigestAlgorithm ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
char **  aOutput 
)

Get the message digest algorithm of the signature.

Note that the values returned by this functions are different from the Digest values used by SIGNDOC_Field_getSeedValueDigestMethod() and friends:

DigestMethodSIGNDOC_
VerificationResult_
getDigestAlgorithm()		DetachedHashAlgorithm
n/a "MD5" n/a
"RIPEMD160" "RIPEMD-160" "RIPEMD-160"
"SHA1" "SHA-1" "SHA-1"
- "SHA-224" "SHA-224"
"SHA256" "SHA-256" "SHA-256"
"SHA384" "SHA-384" "SHA-384"
"SHA512" "SHA-512" "SHA-512"
Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe message digest algorithm (such as "SHA-1") will be stored here. If the message digest algorithm is unsupported, an empty string will be stored. The string must be freed with SIGNDOC_free().
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
int SIGNDOC_VerificationResult_getDocMDP ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj 
)

Get the DocMDP P value of a certification signature.

The MDP value specifies what modifications to the document are allowed by the certification signature.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
Returns
-1 if the signature is not a certification signature, 1 if no modifications are allowed, 2 if only filling in forms, instantiating page templates, and signing are permitted, 3 if only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations are permitted. For TIFF documents, this function always returns -1.
See also
SIGNDOC_VerificationResult_getModificationState(), SIGNDOC_Document_getDocMDP(), SIGNDOC_Field_getDocMDP()
int SIGNDOC_VerificationResult_getEncryptedBiometricData ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
struct SIGNDOC_ByteArray *  aOutput 
)

Get the encrypted biometric data of the field.

Use this function if you cannot use SIGNDOC_VerificationResult_getBiometricData() for decrypting the biometric data (for instance, because the private key is stored in an HSM).

In the following description of the format of the encrypted data retrieved by this function, all numbers are stored in little-endian format (however, RSA uses big-endian format):

  • 4 octets: version number
  • 4 octets: number of following octets (hash and body)
  • 32 octets: SHA-256 hash of body (ie, of the octets which follow)
  • body (format depends on version number)

If the version number is 1, the encryption method is SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_RSA with a 2048-bit key and the body has this format:

  • 32 octets: SHA-256 hash of unencrypted biometric data
  • 256 octets: AES-256 session key encrypted with 2048-bit RSA 2.0 (OAEP) with SHA-256
  • rest: biometric data encrypted with AES-256 in CBC mode using padding as described in RFC 2246. The IV is zero (not a problem as the session key is random).

If the version number is 2, the body has this format:

If the version number is 3, the encryption method is SIGNDOC_SIGNATUREPARAMETERS_BIOMETRICENCRYPTION_RSA with a key longer than 2048 bits and the body has this format:

  • 4 octets: size n of encrypted AES key in octets
  • n octets: AES-256 session key encrypted with RSA 2.0 (OAEP) with SHA-256
  • 32 octets: IV (only the first 16 octets are used, please ignore the rest)
  • 32 octets: SHA-256 hash of unencrypted biometric data
  • rest: biometric data encrypted with AES-256 in CBC mode using padding as described in RFC 2246.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in,out]aOutputThe decrypted biometric data will be stored here. See above for the format.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NO_BIOMETRIC_DATA if no biometric data is availabable.
See also
SIGNDOC_VerificationResult_checkBiometricHash(), SIGNDOC_VerificationResult_getBiometricData(), SIGNDOC_VerificationResult_getBiometricEncryption(), SIGNDOC_VerificationResult_getMethod()
const char * SIGNDOC_VerificationResult_getErrorMessage ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int  aEncoding 
)

Get an error message for the last function call.

Note
Do not call SIGNDOC_free() on the return value.
Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aEncodingThe encoding to be used for the error message (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
Returns
A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until aObj is destroyed or a member function of aObj is called.
See also
SIGNDOC_VerificationResult_getErrorMessage()
const wchar_t * SIGNDOC_VerificationResult_getErrorMessageW ( struct SIGNDOC_Exception **  aEx,
const struct SIGNDOC_VerificationResult *  aObj 
)

Get an error message for the last function call.

Note
Do not call SIGNDOC_free() on the return value.
Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
Returns
A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until aObj is destroyed or a member function of aObj is called.
See also
SIGNDOC_VerificationResult_getErrorMessage()
int SIGNDOC_VerificationResult_getLockMDP ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj 
)

Get the lock MDP value of the signature.

The lock MDP value specifies what modifications to the document are allowed by the signature.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
Returns
-1 if the signature does not have a lock MDP value, 1 if no modifications are allowed, 2 if only filling in forms, instantiating page templates, and signing are permitted, 3 if only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations are permitted. For TIFF documents, this function always returns -1.
See also
SIGNDOC_VerificationResult_getModificationState(), SIGNDOC_Document_getLockMDP(), SIGNDOC_Field_getLockMDP()
int SIGNDOC_VerificationResult_getMethod ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the signing method.

If the output is SIGNDOC_SIGNATUREPARAMETERS_METHOD_DIGSIG_CADES_RFC3161, the signature is a document time stamp. Use SIGNDOC_VerificationResult_verifyTimeStampCertificateChain() etc. instead of SIGNDOC_VerificationResult_verifyCertificateChain() etc. for document time stamps.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe signing method: SIGNDOC_SIGNATUREPARAMETERS_METHOD_DIGSIG_PKCS1, SIGNDOC_SIGNATUREPARAMETERS_METHOD_DIGSIG_PKCS7_DETACHED, SIGNDOC_SIGNATUREPARAMETERS_METHOD_DIGSIG_PKCS7_SHA1, SIGNDOC_SIGNATUREPARAMETERS_METHOD_HASH, SIGNDOC_SIGNATUREPARAMETERS_METHOD_DIGSIG_CADES_DETACHED, or SIGNDOC_SIGNATUREPARAMETERS_METHOD_DIGSIG_CADES_RFC3161.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
int SIGNDOC_VerificationResult_getModificationState ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the modification state of a PDF document.

Use this function to find out if the modifications applied to a PDF document after adding a signature are allowed by that signature.

As there is no specification for the modifications allowed or prohibited by a signature, this function tries to mimic the behavior of Adobe Reader.

For TIFF documents, the output is computed directly from the output of getState().

Note
This function can be slow for PDF documents.
Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe signature state: SIGNDOC_VERIFICATIONRESULT_MODIFICATIONSTATE_UNMODIFIED, SIGNDOC_VERIFICATIONRESULT_MODIFICATIONSTATE_ALLOWED, or SIGNDOC_VERIFICATIONRESULT_MODIFICATIONSTATE_PROHIBITED.
Returns
SIGNDOC_RETURNCODE_OK iff successful.
See also
SIGNDOC_VerificationResult_getDocMDP(), SIGNDOC_VerificationResult_getErrorMessage(), SIGNDOC_VerificationResult_getLockMDP(), SIGNDOC_VerificationResult_getState(), SIGNDOC_Document_verifySignature()
int SIGNDOC_VerificationResult_getSignatureBlob ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const char *  aName,
struct SIGNDOC_ByteArray *  aOutput 
)

Get a blob property from the signature field.

Available blob parameters are:

  • BiometricHash A message digest computed over the document hash and the unencrypted biometric data, empty if not present.
  • Contents The Contents entry of the signature dictionary, that is, the digital signature (PDF documents only).
  • DigestEncryptionAlgorithm The DER-encoded digestEncryptionAlgorithm element of the PKCS #7 signature, empty if not present.
  • Signature The PKCS #1 or DER-encoded PKCS #7 signature.

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" (which are reserved), see SIGNDOC_SignatureParameters_setBlob().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aNameThe name of the property.
[in,out]aOutputThe decrypted biometric data will be stored here.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed, SIGNDOC_RETURNCODE_PROPERTY_NOT_FOUND if the property does not exist.
See also
SIGNDOC_VerificationResult_getSignatureString(), SIGNDOC_SignatureParameters_setBlob()
int SIGNDOC_VerificationResult_getSignatureString ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int  aEncoding,
const char *  aName,
char **  aOutput 
)

Get a string parameter from the signature field.

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" (which are reserved), see SIGNDOC_SignatureParameters_setStringW().

The following parameters are not available for document time stamps, see SIGNDOC_VerificationResult_getMethod(): ContactInfo, Location, Reason, and Signer.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aEncodingThe encoding to be used for aOutput (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]aNameThe name of the parameter.
[out]aOutputThe string retrieved from the signature field. The string must be freed with SIGNDOC_free(). If flag SIGNDOC_DOCUMENT_FLAGS_KEEP_ESCAPE_SEQUENCES is set, the string may contain escape sequences for selecting natural languages.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed, SIGNDOC_RETURNCODE_PROPERTY_NOT_FOUND if the parameter does not exist, SIGNDOC_RETURNCODE_NOT_SUPPORTED if the value cannot be encoded according to aEncoding.
See also
SIGNDOC_VerificationResult_getMethod(), SIGNDOC_VerificationResult_getSignatureblob(), SIGNDOC_VerificationResult_getTimeStamp(), SIGNDOC_VerificationResult_SIGNDOC_Document_getLastTimestamp(), SIGNDOC_SignatureParameters_setString()
int SIGNDOC_VerificationResult_getState ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the signature state.

Use this function to find out if the document is still identical to the signed document, or has been updated since signed, or has been tampered with.

If the state SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_UNSUPPORTED_SIGNATURE or SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_INVALID_CERTIFICATE, SIGNDOC_VerificationResult_getErrorMessage() will provide additional information.

Use SIGNDOC_VerificationResult_verifyCertificateChain() to find out if you can trust the identity of the signer.

If the return value is SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_DOCUMENT_EXTENDED for a PDF document, you should call SIGNDOC_VerificationResult_getModificationState() to get additional information.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe signature state: SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_UNMODIFIED, SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_DOCUMENT_EXTENDED, SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_DOCUMENT_MODIFIED, SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_UNSUPPORTED_SIGNATURE, SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_INVALID_CERTIFICATE, o SIGNDOC_VERIFICATIONRESULT_SIGNATURESTATE_EMPTY.
Returns
SIGNDOC_RETURNCODE_OK iff successful.
See also
SIGNDOC_VerificationResult_getErrorMessage(), SIGNDOC_VerificationResult_verifyCertificateChain(), SIGNDOC_Document_verifySignature()
int SIGNDOC_VerificationResult_getTimeStamp ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
char **  aOutput 
)

Get the value of the RFC 3161 time stamp.

You must call SIGNDOC_VerificationResult_verifyTimeStampCertificateChain() and SIGNDOC_VerificationResult_verifyTimeStampCertificateRevocation() to find out whether the time stamp can be trusted. If either of these functions report a problem, the time stamp should not be displayed.

A signature has either an RFC 3161 time stamp (returned by this function) or a time stamp stored as string parameter (returned by SIGNDOC_VerificationResult_getSignatureString().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe RFC 3161 time stamp in ISO 8601 format: "yyyy-mm-ddThh:mm:ssZ" (without milliseconds). The string must be freed with SIGNDOC_free().
Returns
SIGNDOC_RETURNCODE_OK iff successful.
See also
SIGNDOC_VerificationResult_getSignatureString(), SIGNDOC_VerificationResult_verifyTimeStampCertificateChain(), SIGNDOC_VerificationResult_verifyTimeStampCertificateRevocation()
int SIGNDOC_VerificationResult_getTimeStampCertificateRevocationState ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the revocation status of the certificate chain of the RFC 3161 time stamp.

SIGNDOC_VerificationResult_verifyTimeStampCertificateChain() must have been called successfully. SIGNDOC_VerificationResult_getErrorMessage() will return an error message if this function fails (return value not SIGNDOC_RETURNCODE_OK) or the verification result returned in aOutput is not SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_OK.

If SIGNDOC_VERIFICATIONPARAMETERS_VERIFICATIONFLAGS_CHECK_REVOCATION was not set in integer parameter "VerificationFlags" of the most recent call to SIGNDOC_VerificationResult_verifyTimeStampCertificateChain(), this function will return SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_NOT_CHECKED in aOutput.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe result of the certificate revocation check: SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_OK, SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_NOT_CHECKED, SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_OFFLINE, SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_REVOKED, or SIGNDOC_VERIFICATIONRESULT_CERTIFICATEREVOCATIONSTATE_ERROR.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
See also
SIGNDOC_VerificationResult_verifyTimeStampCertificateChain(), SIGNDOC_VerificationResult_verifyTimeStampCertificateSimplified()
int SIGNDOC_VerificationResult_getTimeStampCertificates ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
struct SIGNDOC_ByteArrayArray *  aOutput 
)

Get the certificates of the RFC 3161 time stamp.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in,out]aOutputThe ASN.1-encoded X.509 certificates will be stored here. If there are multiple certificates, the first one (at index 0) is the signing certificate.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
int SIGNDOC_VerificationResult_getTimeStampDigestAlgorithm ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
char **  aOutput 
)

Get the message digest algorithm of the RFC 3161 timestamp.

The following table shows the supported digest algorithms and the respective value of string parameter "TimeStampHashAlgorithm":

getTimeStampDigestAlgorithm()TimeStampHashAlgorithm
"MD5" n/a
"RIPEMD-160" n/a
"SHA-1" "SHA-1"
"SHA-256" "SHA-256"
"SHA-384" "SHA-384"
"SHA-512" "SHA-512"
Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe message digest algorithm (such as "SHA-1") will be stored here. If the message digest algorithm is unsupported, an empty string will be stored. The string must be freed with SIGNDOC_free().
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
int SIGNDOC_VerificationResult_getTimeStampState ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
int *  aOutput 
)

Get the state of the RFC 3161 time stamp.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[out]aOutputThe state of the RFC 3161 time stamp: SIGNDOC_VERIFICATIONRESULT_TIMESTAMPSTATE_VALID, SIGNDOC_VERIFICATIONRESULT_TIMESTAMPSTATE_MISSING, or SIGNDOC_VERIFICATIONRESULT_TIMESTAMPSTATE_INVALID.
Returns
SIGNDOC_RETURNCODE_OK iff successful.
int SIGNDOC_VerificationResult_verifyCertificateChain ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const struct SIGNDOC_VerificationParameters *  aParameters,
int *  aOutput 
)

Verify the certificate chain of the signature's certificate.

Use this function to find out if you can trust the identity of the signer.

SIGNDOC_VerificationResult_getErrorMessage() will return an error message if this function fails (return value not SIGNDOC_RETURNCODE_OK) or the verification result returned in aOutput is not SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_OK.

Call SIGNDOC_VerificationResult_getCertificateRevocationState() after this function() to get the revocation state.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod() and SIGNDOC_VerificationResult_verifyTimeStampCertificateChain().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aParametersA pointer to an object containing verification parameters or NULL for default parameters.
[out]aOutputThe result of the certificate chain verification: SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_OK, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_BROKEN_CHAIN, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_UNTRUSTED_ROOT, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_CRITICAL_EXTENSION, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_NOT_TIME_VALID, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_PATH_LENGTH, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_INVALID, or SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_ERROR.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
See also
SIGNDOC_VerificationResult_getCertificateChainLength(), SIGNDOC_VerificationResult_getCertificateRevocationState(), SIGNDOC_VerificationResult_getMethod(), SIGNDOC_VerificationResult_verifyCertificateSimplified(), SIGNDOC_VerificationResult_verifyTimeStampCertificateChain()
int SIGNDOC_VerificationResult_verifyCertificateSimplified ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const struct SIGNDOC_VerificationParameters *  aParameters 
)

Simplified verification of the certificate chain and revocation status of the signature's certificate.

This function just returns a good / not good value according to policies defined by the arguments. It does not tell the caller what exactly is wrong. However, SIGNDOC_VerificationResult_getErrorMessage() will return an error message if this function fails. Do not attempt to base decisions on that error message, please use SIGNDOC_VerificationResult_verifyCertificateChain() and SIGNDOC_VerificationResult_getCertificateRevocationState() instead of this function if you need details about the failure.

This function fails for document time stamps, see SIGNDOC_VerificationResult_getMethod() and SIGNDOC_VerificationResult_verifyTimeStampCertificateSimplified().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aParametersA pointer to an object containing verification parameters or NULL for default parameters.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the arguments are invalid.
See also
SIGNDOC_VerificationResult_getCertificateChainLength(), SIGNDOC_VerificationResult_getCertificateRevocationState(), SIGNDOC_VerificationResult_getMethod(), SIGNDOC_VerificationResult_verifyCertificateChain(), SIGNDOC_VerificationResult_verifyTimeStampCertificateSimplified()
int SIGNDOC_VerificationResult_verifyTimeStampCertificateChain ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const struct SIGNDOC_VerificationParameters *  aParameters,
int *  aOutput 
)

Verify the certificate chain of the RFC 3161 time stamp.

SIGNDOC_VerificationResult_getErrorMessage() will return an error message if this function fails (return value not SIGNDOC_RETURNCODE_OK) or the verification result returned in aOutput is not SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_OK.

Call SIGNDOC_VerificationResult_getTimeStampCertificateRevocationState() to get the revocation state.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aParametersA pointer to an object containing verification parameters or NULL for default parameters.
[out]aOutputThe result of the certificate chain verification: SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_OK, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_BROKEN_CHAIN, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_UNTRUSTED_ROOT, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_CRITICAL_EXTENSION, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_NOT_TIME_VALID, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_PATH_LENGTH, SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_INVALID, or SIGNDOC_VERIFICATIONRESULT_CERTIFICATECHAINSTATE_ERROR.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed.
See also
SIGNDOC_VerificationResult_getTimeStampCertificateRevocationState(), SIGNDOC_VerificationResult_verifyTimeStampCertificateRevocation(), SIGNDOC_VerificationResult_verifyTimeStampCertificateSimplified()
int SIGNDOC_VerificationResult_verifyTimeStampCertificateSimplified ( struct SIGNDOC_Exception **  aEx,
struct SIGNDOC_VerificationResult *  aObj,
const struct SIGNDOC_VerificationParameters *  aParameters 
)

Simplified verification of the certificate chain and revocation status of the RFC 3161 time stamp.

This function just returns a good / not good value according to policies defined by the verification parameters. It does not tell the caller what exactly is wrong. However, SIGNDOC_VerificationResult_getErrorMessage() will return an error message if this function fails. Do not attempt to base decisions on that error message, please use SIGNDOC_VerificationResult_verifyTimeStampCertificateChain() and SIGNDOC_VerificationResult_verifyTimeStampCertificateRevocation() instead of this function if you need details about the failure.

For integer parameter "CertificateChainVerificationPolicy", SIGNDOC_VERIFICATIONPARAMETERS_CERTIFICATECHAINVERIFICATIONPOLICY_ACCEPT_SELF_SIGNED_WITH_BIO and SIGNDOC_VERIFICATIONPARAMETERS_CERTIFICATECHAINVERIFICATIONPOLICY_ACCEPT_SELF_SIGNED_WITH_RSA_BIO are treated like SIGNDOC_VERIFICATIONPARAMETERS_CERTIFICATECHAINVERIFICATIONPOLICY_ACCEPT_SELF_SIGNED.

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_VerificationResult object.
[in]aParametersA pointer to an object containing verification parameters or NULL for default parameters.
Returns
SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_NOT_VERIFIED if verification has failed, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the arguments are invalid, SIGNDOC_RETURNCODE_NOT_SUPPORTED if there is no RFC 3161 time stamp.
See also
SIGNDOC_VerificationResult_verifyTimeStampCertificateChain(), SIGNDOC_VerificationResult_verifyTimeStampCertificateRevocation()
The documentation for this class was generated from the following file: