de::softpro::doc::SignDocVerificationParameters Class Reference

Parameters for verifying a certificate chain. More...

#include <SignDocSDK-cpp.h>

Public Types
enum	CertificateChainVerificationPolicy {   ccvp_dont_verify, ccvp_accept_self_signed, ccvp_accept_self_signed_with_bio, ccvp_accept_self_signed_with_rsa_bio,   ccvp_require_trusted_root }
	Values for integer parameter "CertificateChainVerificationPolicy". More...
enum	CertificateRevocationVerificationPolicy { crvp_dont_check, crvp_offline, crvp_online }
	Values for integer parameter "CertificateRevocationVerificationPolicy". More...
enum	VerificationFlags {   vf_check_revocation = 0x01, vf_use_crl_only = 0x02, vf_use_ocsp_only = 0x04, vf_offline = 0x08,   vf_enforce_next_update = 0x10, vf_enforce_ocsp_signer = 0x20, vf_online = 0x40, vf_no_ocsp_nonce = 0x80,   vf_crl_first = 0x100, vf_ignore_no_revocation = 0x200 }
	Flags for certificate verification. More...
enum	VerificationModel { vm_minimal, vm_chain, vm_modified_shell, vm_shell }
	Values for integer parameter "VerificationModel". More...
enum	ReturnCode { rc_ok, rc_unknown, rc_not_supported, rc_invalid_value }
	Return codes. More...
Public Member Functions
	SignDocVerificationParameters ()
	Constructor.
	SignDocVerificationParameters (const SignDocVerificationParameters &aSource)
	Copy constructor.
	~SignDocVerificationParameters ()
	Destructor.
SignDocVerificationParameters &	operator= (const SignDocVerificationParameters &aSource)
	Assignment operator.
bool	operator== (const SignDocVerificationParameters &aRHS) const
	Compare against another SignDocVerificationParameters object.
void	setForUpdateDSS ()
	Set suitable values for using this object with SignDocDocument::updateDSS() and SignDocDocument::updateDSS2().
ReturnCode	setString (Encoding aEncoding, const std::string &aName, const std::string &aValue)
	Set a string parameter.
ReturnCode	setString (const std::string &aName, const wchar_t *aValue)
	Set a string parameter.
ReturnCode	setInteger (const std::string &aName, int aValue)
	Set an integer parameter.
ReturnCode	setBlob (const std::string &aName, const unsigned char *aData, size_t aSize)
	Set a blob parameter.
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.
	SignDocVerificationParameters (SIGNDOC_VerificationParameters *aP)
	Internal function.
SIGNDOC_VerificationParameters *	getImpl ()
	Internal function.
const SIGNDOC_VerificationParameters *	getImpl () const
	Internal function.
void	setImpl (SIGNDOC_VerificationParameters *aP)
	Internal function.

---

Detailed Description

Parameters for verifying a certificate chain.

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

If you use a NULL pointer instead of a pointer to a SignDocVerificationParameters object, the following default values will be used (those are identical to the default values for a freshly created SignDocVerificationParameters object):

• CertificateChainVerificationPolicy: ccvp_accept_self_signed_with_rsa_bio
• CertificateRevocationVerificationPolicy: crvp_dont_check
• ComputeOfflineNextUpdate: -1 (that is, embedded CRLs and OCSP responses without nextUpdate will be indefinitely valid)
• Timeout: 10000
• UserAgent: "SignDoc"
• VerificationFlags: 0 (that is, revocation checking is disabled)
• VerificationModel: vm_minimal
• VerificationTime: empty (that is, current date and time)

However, for SignDocDocument::updateDSS() and SignDocDocument::updateDSS2(), the following default values will be used if a NULL pointer is passed (those are identical to the values set by setForUpdateDSS()):

• CertificateChainVerificationPolicy: ccvp_accept_self_signed_with_rsa_bio
• CertificateRevocationVerificationPolicy: crvp_online
• ComputeOfflineNextUpdate: 0 (that is, embedded CRLs and OCSP responses without nextUpdate won't be valid)
• Timeout: 10000
• UserAgent: "SignDoc"
• VerificationFlags: 0
• VerificationModel: vm_shell
• VerificationTime: empty (that is, current date and time)

To make the signature maximally meaningful, verification parameters for SignDocDocument::addSignature() should include vf_check_revocation in integer parameter "VerificationFlags".

If integer parameter "CertificateChainVerificationPolicy" is ccvp_dont_verify, integer parameter "CertificateRevocationVerificationPolicy" must be crvp_dont_check.

See also:

SignDocDocument::renderPageAsImage(), SignDocDocument::updateDSS(), SignDocDocument::updateDSS2(), SignDocVerificationResult::verifyCertificateChain(), SignDocVerificationResult::verifyCertificateSimplified(), SignDocVerificationResult::verifyTimeStampCertificateChain(), SignDocVerificationResult::verifyTimeStampSimplified()

---

Member Enumeration Documentation

enum de::softpro::doc::SignDocVerificationParameters::CertificateChainVerificationPolicy

Values for integer parameter "CertificateChainVerificationPolicy".

See also:

setInteger()

Enumerator:

ccvp_dont_verify	Don't verify the certificate chain. Always pretend that the certificate chain is OK.
ccvp_accept_self_signed	Accept self-signed certificates. If the signing certificate is not self-signed, it must chain up to a trusted root certificate.
ccvp_accept_self_signed_with_bio	Accept self-signed certificates if biometric data is present. If the signing certificate is not self-signed or if there is no biometric data, the certificate must chain up to a trusted root certificate.
ccvp_accept_self_signed_with_rsa_bio	Accept self-signed certificates if asymmetrically encrypted biometric data is present. If the signing certificate is not self-signed or if there is no biometric data or if the biometric data is not encrypted with RSA, the certificate must chain up to a trusted root certificate. This value is equivalent to ccvp_require_trusted_root when verifying the certificate chain of a time stamp.
ccvp_require_trusted_root	Require a trusted root certificate. The signing certificate must chain up to a trusted root certificate.

enum de::softpro::doc::SignDocVerificationParameters::CertificateRevocationVerificationPolicy

Values for integer parameter "CertificateRevocationVerificationPolicy".

See also:

setInteger()

Enumerator:

crvp_dont_check	Don't verify revocation of certificates. Always pretend that certificates have not been revoked.
crvp_offline	Check revocation, assume that certificates are not revoked if the revocation server is offline.
crvp_online	Check revocation, assume that certificates are revoked if the revocation server is offline.

enum de::softpro::doc::SignDocVerificationParameters::ReturnCode

Return codes.

Enumerator:

rc_ok	Parameter set successfully.
rc_unknown	Unknown parameter.
rc_not_supported	Setting the parameter is not supported.
rc_invalid_value	The value for the parameter is invalid.

enum de::softpro::doc::SignDocVerificationParameters::VerificationFlags

Flags for certificate verification.

See also:

verifyCertificateChain(), verifyTimeStampCertificateChain()

Enumerator:

vf_check_revocation	Check the revocation state of the certificates.
vf_use_crl_only	Use only certification revocation lists for checking the revocation state of the certificates. This flag is ignored unless vf_check_revocation is set. vf_use_ocsp_only must not be set if this flag is set.
vf_use_ocsp_only	Use only OCSP for checking the revocation state of the certificates. This flag is ignored unless vf_check_revocation is set. vf_use_crl_only must not be set if this flag is set.
vf_offline	Use only CRLs and OCSP responses stored in the document, do not connect to any server for getting CRLs and OCSP responses. This flag is ignored unless vf_check_revocation is set. vf_online must not be set if this flag is set.
vf_enforce_next_update	Enforce nextUpdate of CRLs and OCSP responses. If this flag is set, CRLs and OCSP responses whose nextUpdate time is before the signing time or verification time (depending on the verification model) will be ignored. See also integer parameter "ComputeOfflineNextUpdate". This flag is ignored unless vf_check_revocation is set. If this flag is set, there are more cases in which an OCSP or CRL server needs to be contacted.
vf_enforce_ocsp_signer	Enforce correct OCSP signer. If this flag is set, an OCSP response must be signed by the issuer certificate or a delegate issued by the issuer certificate. This flag flag is not set, any trusted signer will be accepted as OCSP signer. This flag is ignored unless vf_check_revocation is set.
vf_online	Do not use CRLs and OCSP responses stored in the document, always use server for getting CRLs and OCSP responses. This flag is ignored unless vf_check_revocation is set. vf_offline must not be set if this flag is set.
vf_no_ocsp_nonce	Do not use a nonce in OCSP requests. If this flag is set, OCSP requests won't use a nonce, enabling OCSP responders to cache responses and enabling attackers to mount replay attacks. If this flag is not set, a nonce is used in OCSP requests (and is therefore required in OCSP responses).
vf_crl_first	Try CRL before OCSP for certificates that specify both CRL distribution points and OCSP distribution points. If this flag is set, CRLs will be tried first which has the advantage of CRLs being cacheable. If this flag is not set, OCSP will be tried first which has the advantage of OCSP responses being usually smaller than CRLs.
vf_ignore_no_revocation	Ignore for revocation checking certificates that don't have CRL and OCSP distribution points. If this flag is set, certificates that have neither CRL distribution points nor OCSP distribution points will be ignored during revocation checking. If this flag is not set, certificates that have neither CRL distribution points nor OCSP distribution points cause revocation checking to fail (result SignDocVerificationResult::crs_not_checked for SignDocVerificationResult::getCertificateRevocationState()) unless there is a revoked certificate (result SignDocVerificationResult::crs_revoked for SignDocVerificationResult::getCertificateRevocationState()).

enum de::softpro::doc::SignDocVerificationParameters::VerificationModel

Values for integer parameter "VerificationModel".

See also:

setInteger()

Enumerator:

vm_minimal	Minimal. The signing certificate must be valid at signing time. Apparently, this is what Adobe Reader does.
vm_chain	Chain model. Each certificate in the chain (except for the root certificate) must have been issued during the validity time period of its issuer certificate. The signing certificate must be valid at signing time.
vm_modified_shell	Modified shell model (also known as hybrid model). All certificates in the chain must be valid at signing time.
vm_shell	Shell model. All certificates in the chain must be valid at verification time and the signing certificate must be valid at signing time. The shell model is not really suitable for digital signatures as it allows for repudiation of signatures. An exception is LTV (long term validity) validation as signatures are validated at times in the past established by document time stamps.

---

Constructor & Destructor Documentation

de::softpro::doc::SignDocVerificationParameters::SignDocVerificationParameters

(

)

[inline]

Constructor.

See SignDocVerificationParameters for the default values.

See also:

setForUpdateDSS()

de::softpro::doc::SignDocVerificationParameters::SignDocVerificationParameters

(

const SignDocVerificationParameters &

aSource )

[inline]

Copy constructor.

Parameters:

[in]

aSource

The object to be copied.

de::softpro::doc::SignDocVerificationParameters::~SignDocVerificationParameters

(

)

[inline]

Destructor.

de::softpro::doc::SignDocVerificationParameters::SignDocVerificationParameters

(

SIGNDOC_VerificationParameters *

aP )

[inline]

Internal function.

---

Member Function Documentation

const char* de::softpro::doc::SignDocVerificationParameters::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::SignDocVerificationParameters::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_VerificationParameters* de::softpro::doc::SignDocVerificationParameters::getImpl

(

)

[inline]

Internal function.

const SIGNDOC_VerificationParameters* de::softpro::doc::SignDocVerificationParameters::getImpl

(

)

const [inline]

Internal function.

SignDocVerificationParameters& de::softpro::doc::SignDocVerificationParameters::operator=

(

const SignDocVerificationParameters &

aSource )

[inline]

Assignment operator.

Parameters:

[in]

aSource

The source object.

bool de::softpro::doc::SignDocVerificationParameters::operator==

(

const SignDocVerificationParameters &

aRHS )

const [inline]

Compare against another SignDocVerificationParameters object.

Parameters:

[in]

aRHS

The object to compare against.

Returns:

true iff this object compares equal to aRHS.

ReturnCode de::softpro::doc::SignDocVerificationParameters::setBlob	(	const std::string &	aName,
		const unsigned char *	aData,
		size_t	aSize
	)		[inline]

Set a blob parameter.

Available blob parameters are:

• IntermediateCertificate Add an intermediate certificate which might help building the certificate chain. The blob must contain a serialized X.509 certificate (DER or PEM).
• TrustedCertificate Add a trusted root certificate. The blob must contain a serialized X.509 certificate (DER or PEM).

Parameters:

[in]	aName	The name of the parameter (case-sensitive).
[in]	aData	A pointer to the first octet of the value.
[in]	aSize	Size of the blob (number of octets).

Returns:

rc_ok iff successful.

void de::softpro::doc::SignDocVerificationParameters::setForUpdateDSS

(

)

[inline]

Set suitable values for using this object with SignDocDocument::updateDSS() and SignDocDocument::updateDSS2().

See SignDocVerificationParameters for the values set by this function.

void de::softpro::doc::SignDocVerificationParameters::setImpl

(

SIGNDOC_VerificationParameters *

aP )

[inline]

Internal function.

ReturnCode de::softpro::doc::SignDocVerificationParameters::setInteger	(	const std::string &	aName,
		int	aValue
	)		[inline]

Set an integer parameter.

Available integer parameters are:

• CertificateChainVerificationPolicy Policy for simplified verification of the certificate chain, see enum CertificateRevocationVerificationPolicy. The default value is ccvp_accept_self_signed_with_rsa_bio. This parameter is used by SignDocDocument::renderPageAsImage(), SignDocDocument::updateDSS(), SignDocDocument::updateDSS2(), SignDocVerificationResult::verifyCertificateSimplified(), and SignDocVerificationResult::verifyTimeStampCertificateSimplified() only.
• CertificateRevocationVerificationPolicy Policy for simplified verification of the revocation status of the certificates, see enum CertificateRevocationVerificationPolicy. The default value is crvp_dont_check. This parameter is used by SignDocDocument::renderPageAsImage(), SignDocDocument::updateDSS(), SignDocDocument::updateDSS2(), SignDocVerificationResult::verifyCertificateSimplified(), and SignDocVerificationResult::verifyTimeStampCertificateSimplified() only.
• ChainPolicy Abbreviation for "CertificateChainVerificationPolicy".
• ComputeOfflineNextUpdate Number of hours embedded CRLs and OCSP responses that do not have a nextUpdate value will be assumed to be valid after their thisUpdate value. That is, nextUpdate will be computed from thisUpdate by adding the specified number of hours. The value -1 is special and means that those CRLs and OCSP responses will be assumed to be valid indefinitely. The default value is -1. See also flag vf_enforce_next_update of integer parameter "VerificationFlags".
• Flags Abbreviation for "VerificationFlags".
• Model Abbreviation for "VerificationModel".
• RevocationPolicy Abbreviation for "CertificateRevocationVerificationPolicy".
• Timeout The timeout (in millisconds) for HTTP connections used for checking the revocation state of certificates. This value is ignored unless vf_check_revocation is set for integer parameter "VerificationFlags". The default value is 10000.
• VerificationFlags Flags modifying the verification. This is a combination of flags from enum VerificationFlags. If you pass 0, the revocation state of the certificates won't be checked. The default value is 0. SignDocDocument::renderPageAsImage(), SignDocDocument::updateDSS(), SignDocDocument::updateDSS2(), SignDocVerificationResult::verifyCertificateSimplified(), and SignDocVerificationResult::verifyTimeStampCertificateSimplified() use integer parameter CertificateRevocationVerificationPolicy instead of the vf_check_revocation flag. vf_offline should not be set for SignDocDocument::addSignature().
• VerificationModel Model to be used for verifying the certificate chain, see enum VerificationModel. The default value is vm_minimal. SignDocDocument::addSignature() ignores this parameter and uses vm_chain if revocation data is to be included in the signature.

Parameters:

[in]	aName	The name of the parameter (case-sensitive).
[in]	aValue	The value of the parameter.

Returns:

rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocVerificationParameters::setString	(	Encoding	aEncoding,
		const std::string &	aName,
		const std::string &	aValue
	)		[inline]

Set a string parameter.

Available string parameters are:

• UserAgent The value of the User-Agent header field sent to CRL and OCSP servers. The default value is "SignDoc".
• VerificationTime Empty (for the current date and time) or a string in ISO 8601 format ("yyyy-mm-ddThh:mm:ss", with optional timezone) specifying the verification date and time. The default value is empty. Used only if integer parameter "VerificationModel" is vm_shell. This parameteter is not used by SignDocDocument::addSignature(); that function always use the signing time as verification time.

Parameters:

[in]	aEncoding	The encoding used for aValue.
[in]	aName	The name of the parameter (case-sensitive).
[in]	aValue	The value of the parameter. The encoding is specified by aEncoding.

Returns:

rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocVerificationParameters::setString	(	const std::string &	aName,
		const wchar_t *	aValue
	)		[inline]

Set a string parameter.

See the other setString() function for a list of available string parameters.

Parameters:

[in]	aName	The name of the parameter (case-sensitive).
[in]	aValue	The value of the parameter.

Returns:

rc_ok iff successful.

---

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

• SignDocSDK-cpp.h