de::softpro::doc::SignDocVerificationResult Class Reference

Information about a signature field returned by SignDocDocument::verifySignature() or SignDocDocument::verifySignature2(). More...

#include <SignDocSDK-cpp.h>

Public Types
enum	ReturnCode {   rc_ok = SignDocDocument::rc_ok, rc_invalid_argument = SignDocDocument::rc_invalid_argument, rc_not_supported = SignDocDocument::rc_not_supported, rc_not_verified = SignDocDocument::rc_not_verified,   rc_property_not_found = SignDocDocument::rc_property_not_found, rc_no_biometric_data = SignDocDocument::rc_no_biometric_data, rc_unexpected_error = SignDocDocument::rc_unexpected_error }
	Return codes. More...
enum	SignatureState {   ss_unmodified, ss_document_extended, ss_document_modified, ss_unsupported_signature,   ss_invalid_certificate, ss_empty }
	State of a signature. More...
enum	ModificationState { ms_unmodified, ms_allowed, ms_prohibited }
	Modification state of the document for a certain signature. More...
enum	TimeStampState { tss_valid, tss_missing, tss_invalid }
	State of the RFC 3161 time stamp. More...
enum	CertificateChainState {   ccs_ok, ccs_broken_chain, ccs_untrusted_root, ccs_critical_extension,   ccs_not_time_valid, ccs_path_length, ccs_invalid, ccs_error }
	Certificate chain state for verifyCertificateChain() and verifyTimeStampCertificateChain(). More...
enum	CertificateRevocationState {   crs_ok, crs_not_checked, crs_offline, crs_revoked,   crs_error }
	Certificate revocation state for getCertificateRevocationState() and getTimeStampCertificateRevocationState(). More...
Public Member Functions
	SignDocVerificationResult ()
	Constructor.
	~SignDocVerificationResult ()
	Destructor.
ReturnCode	getState (SignatureState &aOutput)
	Get the signature state.
ReturnCode	getModificationState (ModificationState &aOutput)
	Get the modification state of a PDF document.
ReturnCode	getMethod (SignDocSignatureParameters::Method &aOutput)
	Get the signing method.
int	getDocMDP ()
	Get the DocMDP P value of a certification signature.
int	getLockMDP ()
	Get the lock MDP value of the signature.
ReturnCode	getDigestAlgorithm (std::string &aOutput)
	Get the message digest algorithm of the signature.
ReturnCode	getCertificates (std::vector< std::vector< unsigned char > > &aOutput)
	Get the certificates of the signature.
ReturnCode	verifyCertificateChain (const SignDocVerificationParameters *aParameters, CertificateChainState &aOutput)
	Verify the certificate chain of the signature's certificate.
ReturnCode	getCertificateRevocationState (CertificateRevocationState &aOutput)
	Get the revocation state of the certificate chain of the signature's certificate.
ReturnCode	verifyCertificateSimplified (const SignDocVerificationParameters *aParameters)
	Simplified verification of the certificate chain and revocation status of the signature's certificate.
ReturnCode	getCertificateChainLength (int &aOutput)
	Get the certificate chain length.
ReturnCode	getSignatureString (Encoding aEncoding, const std::string &aName, std::string &aOutput)
	Get a string parameter from the signature field.
ReturnCode	getSignatureBlob (const std::string &aName, std::vector< unsigned char > &aOutput)
	Get a blob property from the signature field.
ReturnCode	getBiometricData (const unsigned char *aKeyPtr, size_t aKeySize, const wchar_t *aKeyPath, const char *aPassphrase, std::vector< unsigned char > &aOutput)
	Get the biometric data of the field.
ReturnCode	getBiometricData (Encoding aEncoding, const unsigned char *aKeyPtr, size_t aKeySize, const char *aKeyPath, const char *aPassphrase, std::vector< unsigned char > &aOutput)
	Get the biometric data of the field.
ReturnCode	getEncryptedBiometricData (std::vector< unsigned char > &aOutput)
	Get the encrypted biometric data of the field.
ReturnCode	getBiometricEncryption (SignDocSignatureParameters::BiometricEncryption &aOutput)
	Get the encryption method used for biometric data of the signature field.
ReturnCode	checkBiometricHash (const unsigned char *aBioPtr, size_t aBioSize, bool &aOutput)
	Check the hash of the biometric data.
ReturnCode	getTimeStampState (TimeStampState &aOutput)
	Get the state of the RFC 3161 time stamp.
ReturnCode	getTimeStampDigestAlgorithm (std::string &aOutput)
	Get the message digest algorithm of the RFC 3161 time stamp.
ReturnCode	verifyTimeStampCertificateChain (const SignDocVerificationParameters *aParameters, CertificateChainState &aOutput)
	Verify the certificate chain of the RFC 3161 time stamp.
ReturnCode	getTimeStampCertificateRevocationState (CertificateRevocationState &aOutput)
	Get the revocation state of the certificate chain of the RFC 3161 time stamp.
ReturnCode	verifyTimeStampCertificateSimplified (const SignDocVerificationParameters *aParameters)
	Simplified verification of the certificate chain and revocation status of the RFC 3161 time stamp.
ReturnCode	getTimeStamp (std::string &aOutput)
	Get the value of the RFC 3161 time stamp.
ReturnCode	getTimeStampCertificates (std::vector< std::vector< unsigned char > > &aOutput)
	Get the certificates of the RFC 3161 time stamp.
const char *	getErrorMessage (Encoding aEncoding) const
	Get an error message for the last function call.
const wchar_t *	getErrorMessageW () const
	Get an error message for the last function call.
	SignDocVerificationResult (SIGNDOC_VerificationResult *aP)
	Internal function.
SIGNDOC_VerificationResult *	getImpl ()
	Internal function.
const SIGNDOC_VerificationResult *	getImpl () const
	Internal function.
void	setImpl (SIGNDOC_VerificationResult *aP)
	Internal function.

---

Detailed Description

Information about a signature field returned by SignDocDocument::verifySignature() or SignDocDocument::verifySignature2().

The SignDocDocument object must live longer than any SignDocVerificationResult objects returned by its verifySignature() and verifySignature2() functions.

---

Member Enumeration Documentation

enum de::softpro::doc::SignDocVerificationResult::CertificateChainState

Certificate chain state for verifyCertificateChain() and verifyTimeStampCertificateChain().

Enumerator:

ccs_ok	Chain OK.
ccs_broken_chain	Chain broken.
ccs_untrusted_root	Untrusted root certificate.
ccs_critical_extension	A certificate has an unknown critical extension.
ccs_not_time_valid	A certificate is not yet valid or is expired.
ccs_path_length	Path length constraint not satisfied.
ccs_invalid	Invalid certificate or chain.
ccs_error	Other error.

enum de::softpro::doc::SignDocVerificationResult::CertificateRevocationState

Certificate revocation state for getCertificateRevocationState() and getTimeStampCertificateRevocationState().

Enumerator:

crs_ok	No certificate revoked.
crs_not_checked	Revocation not checked.
crs_offline	Revocation server is offline.
crs_revoked	At least one certificate has been revoked.
crs_error	Error.

enum de::softpro::doc::SignDocVerificationResult::ModificationState

Modification state of the document for a certain signature.

Enumerator:

ms_unmodified	The document has not been modified since the signature was added.
ms_allowed	All the modifications are allowed by the signature.
ms_prohibited	There are modifications that are not allowed by the signature.

enum de::softpro::doc::SignDocVerificationResult::ReturnCode

Return codes.

Do not forget to update de/softpro/doc/SignDocException.java!

Enumerator:

rc_ok	No error.
rc_invalid_argument	Invalid argument.
rc_not_supported	Operation not supported.
rc_not_verified	SignDocDocument::verifySignature() has not been called.
rc_property_not_found	Property not found.
rc_no_biometric_data	No biometric data (or hash) available.
rc_unexpected_error	Unexpected error.

enum de::softpro::doc::SignDocVerificationResult::SignatureState

State of a signature.

Enumerator:

ss_unmodified	No error, signature and document verified.
ss_document_extended	No error, signature and document verified, document modified by adding data to the signed document.
ss_document_modified	Document modified (possibly forged).
ss_unsupported_signature	Unsupported signature method.
ss_invalid_certificate	Invalid certificate.
ss_empty	Signature field without signature.

enum de::softpro::doc::SignDocVerificationResult::TimeStampState

State of the RFC 3161 time stamp.

Enumerator:

tss_valid	No error, an RFC 3161 time stamp is present and valid (but you have to check the certificate chain and revocation).
tss_missing	There is no RFC 3161 time stamp.
tss_invalid	An RFC 3161 time stamp is present but invalid.

---

Constructor & Destructor Documentation

de::softpro::doc::SignDocVerificationResult::SignDocVerificationResult

(

)

[inline]

Constructor.

de::softpro::doc::SignDocVerificationResult::~SignDocVerificationResult

(

)

[inline]

Destructor.

de::softpro::doc::SignDocVerificationResult::SignDocVerificationResult

(

SIGNDOC_VerificationResult *

aP )

[inline]

Internal function.

---

Member Function Documentation

ReturnCode de::softpro::doc::SignDocVerificationResult::checkBiometricHash	(	const unsigned char *	aBioPtr,
		size_t	aBioSize,
		bool &	aOutput
	)		[inline]

Check the hash of the biometric data.

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

Parameters:

[in]	aBioPtr	Pointer to unencrypted biometric data, typically retrieved by getBiometricData().
[in]	aBioSize	Size of unencrypted biometric data in octets.
[out]	aOutput	Result of the operation: true if the hash is OK, false if the hash doesn't match (the document has been tampered with).

Returns:

rc_ok iff successful.

See also:

getBiometricData(), getEncryptedBiometricData(), getMethod()

ReturnCode de::softpro::doc::SignDocVerificationResult::getBiometricData	(	const unsigned char *	aKeyPtr,
		size_t	aKeySize,
		const wchar_t *	aKeyPath,
		const char *	aPassphrase,
		std::vector< unsigned char > &	aOutput
	)		[inline]

Get the biometric data of the field.

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

• be_rsa Either aKeyPtr or aKeyPath must be non-NULL, aPassphrase is required if the key file is encrypted
• be_fixed aKeyPtr, aKeyPath, and aPassphrase must be NULL
• be_binary aKeyPtr must be non-NULL, aKeySize must be 32, aPassphrase must be NULL
• be_passphrase aKeyPtr must point to the passphrase (which should contain ASCII characters only), aPassphrase must be NULL

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

Note:

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

Parameters:

[in]	aKeyPtr	Pointer to the first octet of the key (must be NULL if aKeyPath is not NULL).
[in]	aKeySize	Size of the key pointed to by aKeyPtr (must be 0 if aKeyPath is not NULL).
[in]	aKeyPath	Pathname 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]	aPassphrase	Passphrase 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 SignDocSignatureParameters::be_rsa. The passphrase must contain ASCII characters only.
[out]	aOutput	The decrypted biometric data will be stored here.

Returns:

rc_ok if successful, rc_no_biometric_data if no biometric data is availabable.

See also:

checkBiometricHash(), getBiometricEncryption(), getEncryptedBiometricData(), getMethod()

ReturnCode de::softpro::doc::SignDocVerificationResult::getBiometricData	(	Encoding	aEncoding,
		const unsigned char *	aKeyPtr,
		size_t	aKeySize,
		const char *	aKeyPath,
		const char *	aPassphrase,
		std::vector< unsigned char > &	aOutput
	)		[inline]

Get the biometric data of the field.

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

• be_rsa Either aKeyPtr or aKeyPath must be non-NULL, aPassphrase is required if the key file is encrypted
• be_fixed aKeyPtr, aKeyPath, and aPassphrase must be NULL
• be_binary aKeyPtr must be non-NULL, aKeySize must be 32, aPassphrase must be NULL
• be_passphrase aKeyPtr must point to the passphrase (which should contain ASCII characters only), aPassphrase must be NULL

Note:

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

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

Parameters:

[in]	aEncoding	The encoding of the string pointed to by aKeyPath.
[in]	aKeyPtr	Pointer to the first octet of the key (must be NULL if aKeyPath is not NULL).
[in]	aKeySize	Size of the key pointed to by aKeyPtr (must be 0 if aKeyPath is not NULL).
[in]	aKeyPath	Pathname 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]	aPassphrase	Passphrase 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 SignDocSignatureParameters::be_rsa. The passphrase must contain ASCII characters only.
[out]	aOutput	The decrypted biometric data will be stored here.

Returns:

rc_ok if successful, rc_no_biometric_data if no biometric data is availabable.

See also:

checkBiometricHash(), getBiometricEncryption(), getEncryptedBiometricData(), getMethod()

ReturnCode de::softpro::doc::SignDocVerificationResult::getBiometricEncryption

(

SignDocSignatureParameters::BiometricEncryption &

aOutput )

[inline]

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

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

Parameters:

[out]

aOutput

The encryption method.

Returns:

rc_ok if successful, rc_no_biometric_data if no biometric data is availabable.

See also:

getBiometricData(), getEncryptedBiometricData(), getMethod()

ReturnCode de::softpro::doc::SignDocVerificationResult::getCertificateChainLength

(

int &

aOutput )

[inline]

Get the certificate chain length.

verifyCertificateChain() or verifyCertificateSimplified() must have been called successfully.

This function fails for document time stamps, see getMethod() and getTimeStampCertificates().

Parameters:

[out]

aOutput

The 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:

rc_ok if successful, rc_not_verified if verification has failed.

See also:

getMethod(), getTimeStampCertificates(), verifyCertificateChain(), verifyCertificateSimplified()

ReturnCode de::softpro::doc::SignDocVerificationResult::getCertificateRevocationState

(

CertificateRevocationState &

aOutput )

[inline]

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

verifyCertificateChain() must have been called successfully.

getErrorMessage() will return an error message if this function fails (return value not rc_ok) or the verification result returned in aOutput is not crs_ok.

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

This function fails for document time stamps, see getMethod() and getTimeStampCertificateRevocationState().

Parameters:

[out]

aOutput

The result of the certificate revocation check.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

See also:

getCertificateChainLength(), getTimeStampCertificateRevocationState(), verifyCertificateChain(), verifyCertificateSimplified()

ReturnCode de::softpro::doc::SignDocVerificationResult::getCertificates

(

std::vector< std::vector< unsigned char > > &

aOutput )

[inline]

Get the certificates of the signature.

This function fails for document time stamps, see getMethod() and getTimeStampCertificates().

Parameters:

[out]

aOutput

The 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:

rc_ok if successful, rc_not_verified if verification has failed.

See also:

getMethod(), getTimeStampCertificates(), verifyCertificateChain()

ReturnCode de::softpro::doc::SignDocVerificationResult::getDigestAlgorithm

(

std::string &

aOutput )

[inline]

Get the message digest algorithm of the signature.

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

DigestMethod	getDigestAlgorithm()	DetachedHashAlgorithm
n/a	"MD5"	n/a
"RIPEMD160"	"RIPEMD-160"	SignDocSignatureParameters::dha_ripemd160
"SHA1"	"SHA-1"	SignDocSignatureParameters::dha_sha1
-	"SHA-224"	SignDocSignatureParameters::dha_sha224
"SHA256"	"SHA-256"	SignDocSignatureParameters::dha_sha256
"SHA384"	"SHA-384"	SignDocSignatureParameters::dha_sha384
"SHA512"	"SHA-512"	SignDocSignatureParameters::dha_sha512

Parameters:

[out]

aOutput

The message digest algorithm (such as "SHA-1") will be stored here. If the message digest algorithm is unsupported, an empty string will be stored.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

int de::softpro::doc::SignDocVerificationResult::getDocMDP

(

)

[inline]

Get the DocMDP P value of a certification signature.

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

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:

getLockMDP(), getModificationState(), SignDocDocument::getDocMDP(), SignDocField::getDocMDP(), SignDocSignature::getDocMDP()

ReturnCode de::softpro::doc::SignDocVerificationResult::getEncryptedBiometricData

(

std::vector< unsigned char > &

aOutput )

[inline]

Get the encrypted biometric data of the field.

Use this function if you cannot use 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 SignDocSignatureParameters::be_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:

• 4 octets: method (SignDocSignatureParameters::be_fixed, SignDocSignatureParameters::be_binary, SignDocSignatureParameters::be_passphrase)
• 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.

If the version number is 3, the encryption method is SignDocSignatureParameters::be_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 getMethod().

Parameters:

[out]

aOutput

The decrypted biometric data will be stored here. See above for the format.

Returns:

rc_ok if successful, rc_no_biometric_data if no biometric data is availabable.

See also:

checkBiometricHash(), getBiometricData(), getBiometricEncryption(), getMethod()

const char* de::softpro::doc::SignDocVerificationResult::getErrorMessage

(

Encoding

aEncoding )

const [inline]

Get an error message for the last function call.

Parameters:

[in]

aEncoding

The encoding to be used for the error message.

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 this object is destroyed or a member function of this object is called.

See also:

getErrorMessageW()

const wchar_t* de::softpro::doc::SignDocVerificationResult::getErrorMessageW

(

)

const [inline]

Get an error message for the last function call.

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 this object is destroyed or a member function of this object is called.

See also:

getErrorMessage()

SIGNDOC_VerificationResult* de::softpro::doc::SignDocVerificationResult::getImpl

(

)

[inline]

Internal function.

const SIGNDOC_VerificationResult* de::softpro::doc::SignDocVerificationResult::getImpl

(

)

const [inline]

Internal function.

int de::softpro::doc::SignDocVerificationResult::getLockMDP

(

)

[inline]

Get the lock MDP value of the signature.

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

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:

getDocMDP(), getModificationState(), SignDocDocument::getLockMDP(), SignDocField::getLockMDP(), SignDocSignature::getLockMDP()

ReturnCode de::softpro::doc::SignDocVerificationResult::getMethod

(

SignDocSignatureParameters::Method &

aOutput )

[inline]

Get the signing method.

If the output is SignDocSignatureParameters::m_digsig_cades_rfc3161, the signature is a document time stamp. Use verifyTimeStampCertificateChain() etc. instead of verifyCertificateChain() etc. for document time stamps.

Parameters:

[out]

aOutput

The signing method, see SignDocSignatureParameters::Method. SignDocSignatureParameters::m_default is never returned.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

ReturnCode de::softpro::doc::SignDocVerificationResult::getModificationState

(

ModificationState &

aOutput )

[inline]

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]

aOutput

The modification state.

Returns:

rc_ok iff successful.

See also:

getDocMDP(), getErrorMessage(), getLockMDP(), getState(), SignDocDocument::verifySignature()

ReturnCode de::softpro::doc::SignDocVerificationResult::getSignatureBlob	(	const std::string &	aName,
		std::vector< unsigned char > &	aOutput
	)		[inline]

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_BiometricData", and "Prop_Build", which are reserved), see SignDocSignatureParameters::setBlob().

Parameters:

[in]	aName	The name of the parameter.
[out]	aOutput	The blob retrieved from the signature field.

Returns:

rc_ok if successful, rc_not_verified if verification has failed, rc_property_not_found if the parameter does not exist.

See also:

getSignatureString(), SignDocSignatureParameters::setBlob()

ReturnCode de::softpro::doc::SignDocVerificationResult::getSignatureString	(	Encoding	aEncoding,
		const std::string &	aName,
		std::string &	aOutput
	)		[inline]

Get a string parameter from the signature field.

Available string parameters are:

• ContactInfo The contact information provided by the signer.
• DigestEncryptionAlgorithmOID The OID of the digestEncryptionAlgorithm element of the PKCS #7 signature, empty if not present. For instance, the OID is "1.2.840.113549.1.1.10" for RSA-PSS.
• Filter The name of the preferred filter.
• Location The host name or physical location of signing.
• Reason The reason for the signing.
• Signer The signer.
• Timestamp The timestamp of the signature in ISO 8601 format: "yyyy-mm-ddThh:mm:ss" with optional timezone. Note that the timestamp can alternatively be stored in the PKCS #7 message, see getTimeStamp().
• VerificationTime The verification time in ISO 8601 format: "yyyy-mm-ddThh:mm:ss" with timezone. This value comes from the SignDocVerificationParameters object or the local clock, not from the signature field. It is set by verifyCertificateChain(), verifyCertificateSimplified(), verifyTimeStampCertificateChain(), and verifyTimeStampCertificateSimplified(). Empty if not available.

Additionally, you can store your own strings in the signature by using a name starting with "Prop_", except for "Prop_AuthTime", "Prop_AuthType", "Prop_BiometricData", and "Prop_Build", which are reserved), see SignDocSignatureParameters::setString().

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

Parameters:

[in]	aEncoding	The encoding to be used for aOutput.
[in]	aName	The name of the parameter.
[out]	aOutput	The string retrieved from the signature field. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

Returns:

rc_ok if successful, rc_not_verified if verification has failed, rc_property_not_found if the parameter does not exist, rc_not_supported if the value cannot be encoded according to aEncoding.

See also:

getMethod(), getSignatureBlob(), getTimeStamp(), SignDocDocument::getLastTimestamp(), SignDocSignatureParameters::setString()

Todo:

document which parameters are available for which methods

ReturnCode de::softpro::doc::SignDocVerificationResult::getState

(

SignatureState &

aOutput )

[inline]

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 is ss_unsupported_signature or ss_invalid_certificate, getErrorMessage() will provide additional information.

If the state is ss_document_extended, getModificationState() will provide additional information.

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

If the output is ss_document_extended for a PDF document, you should call getModificationState() to get additional information.

Parameters:

[out]

aOutput

The signature state.

Returns:

rc_ok iff successful.

See also:

getErrorMessage(), getModificationState(), verifyCertificateChain(), SignDocDocument::verifySignature()

ReturnCode de::softpro::doc::SignDocVerificationResult::getTimeStamp

(

std::string &

aOutput )

[inline]

Get the value of the RFC 3161 time stamp.

You must call verifyTimeStampCertificateChain() and getTimeStampCertificateRevocationState() 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 getSignatureString().

Parameters:

[out]

aOutput

The RFC 3161 time stamp in ISO 8601 format: "yyyy-mm-ddThh:mm:ssZ" (without milliseconds).

Returns:

rc_ok iff successful.

See also:

getSignatureString(), getTimeStampCertificateRevocationState(), verifyTimeStampCertificateChain()

ReturnCode de::softpro::doc::SignDocVerificationResult::getTimeStampCertificateRevocationState

(

CertificateRevocationState &

aOutput )

[inline]

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

verifyTimeStampCertificateChain() must have been called successfully.

getErrorMessage() will return an error message if this function fails (return value not rc_ok) or the verification result returned in aOutput is not crs_ok.

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

Parameters:

[out]

aOutput

The result of the certificate revocation check.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

See also:

verifyTimeStampCertificateChain(), verifyTimeStampCertificateSimplified()

ReturnCode de::softpro::doc::SignDocVerificationResult::getTimeStampCertificates

(

std::vector< std::vector< unsigned char > > &

aOutput )

[inline]

Get the certificates of the RFC 3161 time stamp.

Parameters:

[out]

aOutput

The 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:

rc_ok if successful, rc_not_verified if verification has failed.

ReturnCode de::softpro::doc::SignDocVerificationResult::getTimeStampDigestAlgorithm

(

std::string &

aOutput )

[inline]

Get the message digest algorithm of the RFC 3161 time stamp.

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

getTimeStampDigestAlgorithm()	TimeStampHashAlgorithm
"MD5"	n/a
"RIPEMD-160"	n/a
"SHA-1"	SignDocSignatureParameters::tsha_sha1
"SHA-256"	SignDocSignatureParameters::tsha_sha256
"SHA-384"	SignDocSignatureParameters::tsha_sha384
"SHA-512"	SignDocSignatureParameters::tsha_sha512

Parameters:

[out]

aOutput

The message digest algorithm (such as "SHA-1") will be stored here. If the message digest algorithm is unsupported, an empty string will be stored.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

ReturnCode de::softpro::doc::SignDocVerificationResult::getTimeStampState

(

TimeStampState &

aOutput )

[inline]

Get the state of the RFC 3161 time stamp.

Parameters:

[out]

aOutput

The state of the RFC 3161 time stamp.

Returns:

rc_ok iff successful.

void de::softpro::doc::SignDocVerificationResult::setImpl

(

SIGNDOC_VerificationResult *

aP )

[inline]

Internal function.

ReturnCode de::softpro::doc::SignDocVerificationResult::verifyCertificateChain	(	const SignDocVerificationParameters *	aParameters,
		CertificateChainState &	aOutput
	)		[inline]

Verify the certificate chain of the signature's certificate.

getErrorMessage() will return an error message if this function fails (return value not rc_ok) or the verification result returned in aOutput is not ccs_ok.

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

This function fails for document time stamps, see getMethod() and verifyTimeStampCertificateChain().

Parameters:

[in]	aParameters	A pointer to an object containing Verification parameters or NULL for default parameters.
[out]	aOutput	The result of the certificate chain verification.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

See also:

getCertificateChainLength(), getCertificateRevocationState(), verifyCertificateSimplified(), verifyTimeStampCertificateChain()

ReturnCode de::softpro::doc::SignDocVerificationResult::verifyCertificateSimplified

(

const SignDocVerificationParameters *

aParameters )

[inline]

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, getErrorMessage() will return an error message if this function fails. Do not attempt to base decisions on that error message, please use verifyCertificateChain() instead of this function if you need details about the failure.

This function fails for document time stamps, see getMethod() and verifyTimeStampCertificateSimplified().

Parameters:

[in]

aParameters

Verification parameters or NULL for default parameters.

Returns:

rc_ok if successful, rc_not_verified if verification has failed, rc_invalid_argument if the arguments are invalid.

See also:

getCertificateChainLength(), getMethod(), verifyCertificateChain(), verifyTimeStampCertificateSimplified()

ReturnCode de::softpro::doc::SignDocVerificationResult::verifyTimeStampCertificateChain	(	const SignDocVerificationParameters *	aParameters,
		CertificateChainState &	aOutput
	)		[inline]

Verify the certificate chain of the RFC 3161 time stamp.

getErrorMessage() will return an error message if this function fails (return value not rc_ok) or the verification result returned in aOutput is not ccs_ok.

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

Parameters:

[in]	aParameters	Verification parameters or NULL for default parameters.
[out]	aOutput	The result of the certificate chain verification.

Returns:

rc_ok if successful, rc_not_verified if verification has failed.

See also:

getTimeStampCertificateRevocationState(), verifyTimeStampCertificateSimplified()

ReturnCode de::softpro::doc::SignDocVerificationResult::verifyTimeStampCertificateSimplified

(

const SignDocVerificationParameters *

aParameters )

[inline]

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, getErrorMessage() will return an error message if this function fails. Do not attempt to base decisions on that error message, please use verifyTimeStampCertificateChain() and getTimeStampCertificateRevocationState() instead of this function if you need details about the failure.

For integer parameter "CertificateChainVerificationPolicy", ccvp_accept_self_signed_with_bio and ccvp_accept_self_signed_with_rsa_bio are treated like ccvp_accept_self_signed.

Parameters:

[in]

aParameters

Verification parameters or NULL for default parameters.

Returns:

rc_ok if successful, rc_not_verified if verification has failed, rc_invalid_argument if the arguments are invalid, rc_not_supported if there is no RFC 3161 time stamp.

See also:

getTimeStampCertificateRevocationState(), verifyTimeStampCertificateChain()

---

The documentation for this class was generated from the following file:

• SignDocSDK-cpp.h