SignDoc SDK (C++)  5.0.0
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...
 

Public Member Functions

 SignDocVerificationParameters ()
 Constructor. More...
 
 SignDocVerificationParameters (const SignDocVerificationParameters &aSource)
 Copy constructor. More...
 
 ~SignDocVerificationParameters ()
 Destructor. More...
 
SignDocVerificationParametersoperator= (const SignDocVerificationParameters &aSource)
 Assignment operator. More...
 
bool operator== (const SignDocVerificationParameters &aRHS) const
 Compare against another SignDocVerificationParameters object. More...
 
void setForUpdateDSS ()
 Set suitable values for using this object with SignDocDocument::updateDSS() and SignDocDocument::updateDSS2(). More...
 
ReturnCode setString (Encoding aEncoding, const std::string &aName, const std::string &aValue)
 Set a string parameter. More...
 
ReturnCode setString (const std::string &aName, const wchar_t *aValue)
 Set a string parameter. More...
 
ReturnCode setInteger (const std::string &aName, int aValue)
 Set an integer parameter. More...
 
ReturnCode setBlob (const std::string &aName, const unsigned char *aData, size_t aSize)
 Set a blob parameter. More...
 
const char * getErrorMessage (Encoding aEncoding) const
 Get an error message for the last function call. More...
 
const wchar_t * getErrorMessageW () const
 Get an error message for the last function call. More...
 
 SignDocVerificationParameters (SIGNDOC_VerificationParameters *aP)
 Internal function. More...
 
SIGNDOC_VerificationParameters * getImpl ()
 Internal function. More...
 
const SIGNDOC_VerificationParameters * getImpl () const
 Internal function. More...
 
void setImpl (SIGNDOC_VerificationParameters *aP)
 Internal function. More...
 

Detailed Description

Parameters for verifying a certificate chain.

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

If you use nullptr 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 nullptr 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::renderPageAsSignDocImage(), SignDocDocument::updateDSS(), SignDocDocument::updateDSS2(), SignDocVerificationResult::verifyCertificateChain(), SignDocVerificationResult::verifyCertificateSimplified(), SignDocVerificationResult::verifyTimeStampCertificateChain(), SignDocVerificationResult::verifyTimeStampSimplified()

Member Enumeration Documentation

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.

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.

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()).

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

Constructor.

See SignDocVerificationParameters for the default values.

See also
setForUpdateDSS()

Copy constructor.

Parameters
[in]aSourceThe object to be copied.

Destructor.

SignDocVerificationParameters ( SIGNDOC_VerificationParameters *  aP)
inline

Internal function.

Member Function Documentation

const char * getErrorMessage ( Encoding  aEncoding) const
inline

Get an error message for the last function call.

Parameters
[in]aEncodingThe 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 * 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* getImpl ( )
inline

Internal function.

const SIGNDOC_VerificationParameters* getImpl ( ) const
inline

Internal function.

SignDocVerificationParameters & operator= ( const SignDocVerificationParameters aSource)
inline

Assignment operator.

Parameters
[in]aSourceThe source object.
Returns
This object.
bool operator== ( const SignDocVerificationParameters aRHS) const
inline

Compare against another SignDocVerificationParameters object.

Parameters
[in]aRHSThe object to compare against.
Returns
true iff this object compares equal to aRHS.
ReturnCode 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]aNameThe name of the parameter (case-sensitive).
[in]aDataA pointer to the first octet of the value.
[in]aSizeSize of the blob (number of octets).
Returns
ReturnCode::rc_ok iff successful.
void 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 setImpl ( SIGNDOC_VerificationParameters *  aP)
inline

Internal function.

ReturnCode setInteger ( const std::string &  aName,
int  aValue 
)
inline

Set an integer parameter.

Available integer parameters are:

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter.
Returns
ReturnCode::rc_ok iff successful.
ReturnCode 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]aEncodingThe encoding used for aValue.
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter. The encoding is specified by aEncoding.
Returns
ReturnCode::rc_ok iff successful.
ReturnCode setString ( const std::string &  aName,
const wchar_t *  aValue 
)
inline

Set a string parameter.

See setString(Encoding aEncoding, const std::string &aName, const std::string &aValue) for a list of available string parameters.

Parameters
[in]aNameThe name of the parameter (case-sensitive).
[in]aValueThe value of the parameter.
Returns
ReturnCode::rc_ok iff successful.

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