SignDoc SDK (.NET with exceptions)  5.0.0
SignDocVerificationResult Class Reference

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

Public Member Functions

 ~SignDocVerificationResult ()
 Destructor. More...
 
 !SignDocVerificationResult ()
 Finalizer. More...
 
SignatureState getState ()
 Get the signature state. More...
 
ModificationState getModificationState ()
 Get the modification state of a PDF document. More...
 
SigningMethod getMethod ()
 Get the signing method. More...
 
int getDocMDP ()
 Get the DocMDP P value of a certification signature. More...
 
int getLockMDP ()
 Get the lock MDP value of the signature. More...
 
string getDigestAlgorithm ()
 Get the message digest algorithm of the signature. More...
 
Blobs getCertificates ()
 Get the certificates of the signature. More...
 
CertificateChainState verifyCertificateChain (SignDocVerificationParameters aParameters)
 Verify the certificate chain of the signature's certificate. More...
 
CertificateRevocationState getCertificateRevocationState ()
 Get the revocation state of the certificate chain of the signature's certificate. More...
 
VerificationResultReturnCode verifyCertificateSimplified (SignDocVerificationParameters aParameters)
 Simplified verification of the certificate chain and revocation status of the signature's certificate. More...
 
int getCertificateChainLength ()
 Get the certificate chain length. More...
 
string getSignatureString (string aName)
 Get a string parameter from the signature field. More...
 
byte[] getSignatureBlob (string aName)
 Get a blob property from the signature field. More...
 
byte[] getBiometricData (byte[] aKey, string aKeyPath, byte[] aPassphrase)
 Get the biometric data of the field. More...
 
byte[] getEncryptedBiometricData ()
 Get the encrypted biometric data of the field. More...
 
BiometricEncryption getBiometricEncryption ()
 Get the encryption method used for biometric data of the signature field. More...
 
bool checkBiometricHash (byte[] aBio)
 Check the hash of the biometric data. More...
 
TimeStampState getTimeStampState ()
 Get the state of the RFC 3161 time stamp. More...
 
string getTimeStampDigestAlgorithm ()
 Get the message digest algorithm of the RFC 3161 timestamp. More...
 
CertificateChainState verifyTimeStampCertificateChain (SignDocVerificationParameters aParameters)
 Verify the certificate chain of the RFC 3161 time stamp. More...
 
CertificateRevocationState getTimeStampCertificateRevocationState ()
 Get the revocation state of the certificate chain of the RFC 3161 time stamp. More...
 
VerificationResultReturnCode verifyTimeStampCertificateSimplified (SignDocVerificationParameters aParameters)
 Simplified verification of the certificate chain and revocation status of the RFC 3161 time stamp. More...
 
string getTimeStamp ()
 Get the value of the RFC 3161 time stamp. More...
 
Blobs getTimeStampCertificates ()
 Get the certificates of the RFC 3161 time stamp. More...
 
string getErrorMessage ()
 Get an error message for the last function call. More...
 

Detailed Description

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

Constructor & Destructor Documentation

Destructor.

Finalizer.

Member Function Documentation

bool checkBiometricHash ( byte[]  aBio)

Check the hash of the biometric data.

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

Parameters
[in]aBioUnencrypted biometric data, typically retrieved by getBiometricData().
Returns
true if the hash is OK, false if the hash doesn't match (the document has been tampered with).
See also
getBiometricData(), getEncryptedBiometricData(), getMethod()
byte [] getBiometricData ( byte[]  aKey,
string  aKeyPath,
byte[]  aPassphrase 
)

Get the biometric data of the field.

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

Parameters
[in]aKeyThe key (must be empty if aKeyPath is non-empty).
[in]aKeyPathPathname of the file containing the key (must be an empty string if aKey is non-empty).
[in]aPassphrasePassphrase for decrypting the key contained in the file named by aKeyPath. If this argument an 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 BiometricEncryption.RSA. The passphrase should contain ASCII characters only.
Returns
The decrypted biometric data.
Note
The WinRT component returns null instead of an empty blob.
See also
checkBiometricHash(), getBiometricEncryption(), getEncryptedBiometricData(), getMethod()
BiometricEncryption getBiometricEncryption ( )

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

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

Returns
The encryption method.
See also
getBiometricData(), getEncryptedBiometricData(), getMethod()
int getCertificateChainLength ( )

Get the certificate chain length.

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

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

Returns
The chain length. If the signature was performed with a self-signed certificate, the chain length will be 1.
See also
getCertificates(), getMethod(), getTimeStampCertificates(), verifyCertificateChain(), verifyCertificateSimplified()
CertificateRevocationState getCertificateRevocationState ( )

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 the verification result returned is not CertificateRevocationState.OK.

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

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

Returns
The result of the certificate revocation check.
See also
getCertificateChainLength(), getMethod(), getTimeStampCertificateRevocationState(), verifyCertificateChain(), verifyCertificateSimplified()
Blobs getCertificates ( )

Get the certificates of the signature.

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

Returns
The ASN.1-encoded X.509 certificates. If there are multiple certificates, the first one (at index 0) is the signing certificate.
See also
getMethod(), getTimeStampCertificates(), verifyCertificateChain()
string getDigestAlgorithm ( )

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:

DigestMethodgetDigestAlgorithm()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"
Returns
The message digest algorithm (such as "SHA-1"). If the message digest is unsupported, an empty string will be returned.
int getDocMDP ( )

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()
byte [] getEncryptedBiometricData ( )

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 (howver, 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 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 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 getMethod().

Returns
The encrypted biometric data. See above for the format.
Note
The WinRT component returns null instead of an empty blob.
See also
checkBiometricHash(), getBiometricData(), getBiometricEncryption(), getMethod()
string getErrorMessage ( )

Get an error message for the last function call.

Returns
A string describing the reason for the failure of the last function call. The string is empty if the last call succeeded.
int getLockMDP ( )

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()
SigningMethod getMethod ( )

Get the signing method.

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

Returns
The signing method, see enum SigningMethod. SigningMethod.Default is never returned.
ModificationState getModificationState ( )

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.
Returns
The modification state.
See also
getDocMDP(), getErrorMessage(), getLockMDP(), getState(), SignDocDocument.verifySignature()
byte [] getSignatureBlob ( string  aName)

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.

Additional, 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 SignDocSignatureParameters.setBlob().

Parameters
[in]aNameThe name of the property.
Returns
The blob retrieved from the signature field or null if the property does not exist.
Note
The WinRT component returns null instead of an empty blob.
See also
getSignatureString(), SignDocSignatureParameters.setBlob()
string getSignatureString ( string  aName)

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_Build", and any name starting with "Prop_BiometricData" (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]aNameThe name of the parameter.
Returns
The string retrieved from the signature field or null if the parameter does not exist. If flag DocumentFlags.KeepEscapeSequences is set, the string may contain escape sequences for selecting natural languages.
See also
getMethod(), getSignatureBlob(), getTimeStamp(), SignDocDocument.getLastTimestamp(), SignDocSignatureParameters.setString()
SignatureState getState ( )

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 SignatureState.UnsupportedSignature or SignatureState.InvalidCertificate, getErrorMessage() will provide additional information.

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

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

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

Returns
The signature state.
See also
getErrorMessage(), getModificationState(), verifyCertificateChain(), SignDocDocument.verifySignature()
string getTimeStamp ( )

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

Returns
The RFC 3161 time stamp in ISO 8601 format: "YYYY-MM-DDThh:mm:ssZ" (without milliseconds).
See also
getSignatureString(), getTimeStampCertificateRevocationState(), verifyTimeStampCertificateChain()
CertificateRevocationState getTimeStampCertificateRevocationState ( )

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 or the verification result returned is not CertificateRevocationState.OK.

If VerificationFlags.CheckRevocation was not set in integer parameter "VerificationFlags" of the most recent call to verifyTimeStampCertificateChain(), this function will return CertificateRevocationState.NotChecked.

Returns
The result of the certificate revocation check.
See also
verifyTimeStampCertificateChain(), verifyTimeStampCertificateSimplified()
Blobs getTimeStampCertificates ( )

Get the certificates of the RFC 3161 time stamp.

Returns
The ASN.1-encoded X.509 certificates. If there are multiple certificates, the first one (at index 0) is the signing certificate.
string getTimeStampDigestAlgorithm ( )

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"
Returns
The message digest algorithm (such as "SHA-1"). If the message digest is unsupported, an empty string will be returned.
TimeStampState getTimeStampState ( )

Get the state of the RFC 3161 time stamp.

Returns
The state of the RFC 3161 time stamp.
CertificateChainState verifyCertificateChain ( SignDocVerificationParameters  aParameters)

Verify the certificate chain of the signature's certificate.

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

getErrorMessage() will return an error message if this function fails or the verification result returned is not CertificateChainState.OK or getCertificateRevocationState() won't return CertificateRevocationState.OK.

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

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

Parameters
[in]aParametersVerification parameters or null for default parameters.
Returns
The result of the certificate chain verification.
See also
getCertificateChainLength(), getCertificateRevocationState(), getMethod(), verifyCertificateSimplified(), verifyTimeStampCertificateChain()
VerificationResultReturnCode verifyCertificateSimplified ( SignDocVerificationParameters  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, 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]aParametersVerification parameters or null for default parameters.
Returns
VerificationResultReturnCode.OK if successful, VerificationResultReturnCode.NotVerified if verification has failed, VerificationResultReturnCode.InvalidArgument if the arguments are invalid.
See also
getCertificateChainLength(), getMethod(), verifyCertificateChain(), verifyTimeStampCertificateSimplified()
CertificateChainState verifyTimeStampCertificateChain ( SignDocVerificationParameters  aParameters)

Verify the certificate chain of the RFC 3161 time stamp.

getErrorMessage() will return an error message if this function fails or the verification result returned is not CertificateChainState.OK.

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

Parameters
[in]aParametersverification parameters or null for default parameters.
Returns
The result of the certificate chain verification.
See also
getTimeStampCertificateRevocationState(), verifyTimeStampCertificateSimplified()
VerificationResultReturnCode verifyTimeStampCertificateSimplified ( SignDocVerificationParameters  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 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.

For integer parameter "CertificateChainVerificationPolicy", CertificateChainVerificationPolicy.AcceptSelfSignedWithBio and CertificateChainVerificationPolicy.AcceptSelfSignedWithRSABio are treated like CertificateChainVerificationPolicy.AcceptSelfSigned.

Parameters
[in]aParametersVerification parameters or null for default parameters.
Returns
VerificationResultReturnCode.OK if successful, VerificationResultReturnCode.NotVerified if verification has failed, VerificationResultReturnCode.InvalidArgument if the arguments are invalid, VerificationResultReturnCode.NotSupported if there is no RFC 3161 time stamp.
See also
getTimeStampCertificateRevocationState(), verifyTimeStampCertificateChain()

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