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

Public Member Functions
int	getState () throws SignDocException
	Get the signature state.
int	getModificationState () throws SignDocException
	Get the modification state of a PDF document.
int	getMethod () throws SignDocException
	Get the signing method.
synchronized int	getDocMDP () throws SignDocException
	Get the DocMDP P value of a certification signature.
synchronized int	getLockMDP () throws SignDocException
	Get the lock MDP value of the signature.
String	getDigestAlgorithm () throws SignDocException
	Get the message digest algorithm of the signature.
byte[][]	getCertificates () throws SignDocException
	Get the certificates of the signature.
int	verifyCertificateChain (SignDocVerificationParameters aParameters) throws SignDocException
	Verify the certificate chain of the signature's certificate.
int	getCertificateRevocationState () throws SignDocException
	Get the revocation state of the certificate chain of the signature's certificate.
int	verifyCertificateSimplified (SignDocVerificationParameters aParameters) throws SignDocException
	Simplified verification of the certificate chain and revocation status of the signature's certificate.
int	getCertificateChainLength () throws SignDocException
	Get the certificate chain length.
String	getSignatureString (String aName) throws SignDocException
	Get a string parameter from the signature field.
byte[]	getSignatureBlob (String aName) throws SignDocException
	Get a blob property from the signature field.
byte[]	getBiometricData (byte[] aKey, String aKeyPath, byte[] aPassphrase) throws SignDocException
	Get the biometric data of the field.
byte[]	getEncryptedBiometricData () throws SignDocException
	Get the encrypted biometric data of the field.
int	getBiometricEncryption () throws SignDocException
	Get the encryption method used for biometric data of the signature field.
boolean	checkBiometricHash (byte[] aBio) throws SignDocException
	Check the hash of the biometric data.
int	getTimeStampState () throws SignDocException
	Get the state of the RFC 3161 time stamp.
String	getTimeStampDigestAlgorithm () throws SignDocException
	Get the message digest algorithm of the RFC 3161 timestamp.
int	verifyTimeStampCertificateChain (SignDocVerificationParameters aParameters) throws SignDocException
	Verify the certificate chain of the RFC 3161 time stamp.
int	getTimeStampCertificateRevocationState () throws SignDocException
	Get the revocation state of the certificate chain of the RFC 3161 time stamp.
int	verifyTimeStampCertificateSimplified (SignDocVerificationParameters aParameters) throws SignDocException
	Simplified verification of the certificate chain and revocation status of the RFC 3161 time stamp.
String	getTimeStamp () throws SignDocException
	Get the value of the RFC 3161 time stamp.
byte[][]	getTimeStampCertificates () throws SignDocException
	Get the certificates of the RFC 3161 time stamp.
String	getErrorMessage () throws SignDocException
	Get an error message for the last function call.
Static Public Attributes
static final int	rc_ok = 0
	Return value: OK.
static final int	rc_invalid_argument = SignDocException.rc_invalid_argument
	Return value: invalid argument.
static final int	rc_not_supported = SignDocException.rc_not_supported
	Return value: not supported.
static final int	rc_not_verified = SignDocException.rc_not_verified
	Return value: not verified.
static final int	ss_unmodified = 0
	Signature state: No error, signature and document verified.
static final int	ss_document_extended = 1
	Signature state: No error, signature and document verified, document modified by adding data to the signed document.
static final int	ss_document_modified = 2
	Signature state: Document modified (possibly forged).
static final int	ss_unsupported_signature = 3
	Signature state: Unsupported signature method.
static final int	ss_invalid_certificate = 4
	Signature state: Invalid certificate.
static final int	ss_empty = 5
	Signature state: Signature field without signature.
static final int	ms_unmodified = 0
	Modification state of the document for a certain signature: The document has not been modified since the signature was added.
static final int	ms_allowed = 1
	Modification state of the document for a certain signature: All the modifications are allowed by the signature.
static final int	ms_prohibited = 2
	Modification state of the document for a certain signature: There are modifications that are not allowed by the signature.
static final int	tss_valid = 0
	State of the RFC 3161 time stamp: No error.
static final int	tss_missing = 1
	State of the RFC 3161 time stamp: There is no RFC 3161 time stamp.
static final int	tss_invalid = 2
	State of the RFC 3161 time stamp: Invalid.
static final int	ccs_ok = 0
	Certificate chain state: Chain OK.
static final int	ccs_broken_chain = 1
	Certificate chain state: Chain broken.
static final int	ccs_untrusted_root = 2
	Certificate chain state: Untrusted root certificate.
static final int	ccs_critical_extension = 3
	Certificate chain state: A certificate has an unknown critical extension.
static final int	ccs_not_time_valid = 4
	Certificate chain state: A certificate is not yet valid or is expired.
static final int	ccs_path_length = 5
	Certificate chain state: Path length constraint not satisfied.
static final int	ccs_invalid = 6
	Certificate chain state: Invalid certificate or chain.
static final int	ccs_error = 7
	Certificate chain state: Other error.
static final int	crs_ok = 0
	Certificate revocation state: No certificate revoked.
static final int	crs_not_checked = 1
	Certificate revocation state: Revocation not checked.
static final int	crs_offline = 2
	Certificate revocation state: Revocation server is offline.
static final int	crs_revoked = 3
	Certificate revocation state: At least one certificate has been revoked.
static final int	crs_error = 4
	Certificate revocation state: Error.
Protected Member Functions
void	finalize () throws Throwable
	Finalize this object.

Detailed Description

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

Member Function Documentation

boolean de.softpro.doc.SignDocVerificationResult.checkBiometricHash ( byte[] aBio ) throws SignDocException

Check the hash of the biometric data.

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

Parameters:

[in] aBio Unencrypted 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()

void de.softpro.doc.SignDocVerificationResult.finalize ( ) throws Throwable [protected]

Finalize this object.

Do not call this method unless you know what you are doing.

byte [] de.softpro.doc.SignDocVerificationResult.getBiometricData	(	byte[]	aKey,
		String	aKeyPath,
		byte[]	aPassphrase
	)		throws SignDocException

Get the biometric data of the field.

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

be_rsa Either aKey or aKeyPath must be non-null, aPassphrase is required if the key file is encrypted
be_fixed aKey, aKeyPath, and aPassphrase must be null
be_binary aKey must be non-null and contain 32 octets, aPassphrase must be null
be_passphrase aKey must contain 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]	aKey	The key (must be null if aKeyPath is not null).
[in]	aKeyPath	Pathname of the file containing the key (must be null if aKey is not null).
[in]	aPassphrase	Passphrase for decrypting the key contained in the file named by aKeyPath. If this argument is null or 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 should contain ASCII characters only.

Returns:: The decrypted biometric data.

See also:: checkBiometricHash(), getBiometricEncryption(), getEncryptedBiometricData(), getMethod()

int de.softpro.doc.SignDocVerificationResult.getBiometricEncryption ( ) throws SignDocException

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: SignDocSignatureParameters.be_rsa, SignDocSignatureParameters.be_fixed, SignDocSignatureParameters.be_binary, or SignDocSignatureParameters.be_passphrase.

See also:: getBiometricData(), getEncryptedBiometricData(), getMethod()

int de.softpro.doc.SignDocVerificationResult.getCertificateChainLength ( ) throws SignDocException

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

int de.softpro.doc.SignDocVerificationResult.getCertificateRevocationState ( ) throws SignDocException

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

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

Returns:: The result of the certificate revocation check (crs_ok etc.)

See also:: getCertificateChainLength(), getMethod(), getTimeStampCertificateRevocationState(), verifyCertificateChain(), verifyCertificateSimplified()

byte [][] de.softpro.doc.SignDocVerificationResult.getCertificates ( ) throws SignDocException

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 de.softpro.doc.SignDocVerificationResult.getDigestAlgorithm ( ) throws SignDocException

Get the message digest algorithm of the signature.

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

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

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

synchronized int de.softpro.doc.SignDocVerificationResult.getDocMDP ( ) throws SignDocException

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 [] de.softpro.doc.SignDocVerificationResult.getEncryptedBiometricData ( ) throws SignDocException

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 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 (be_fixed, be_binary, 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 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().

Returns:: The encrypted biometric data. See above for the format.

See also:: checkBiometricHash(), getBiometricData(), getBiometricEncryption(), getMethod()

String de.softpro.doc.SignDocVerificationResult.getErrorMessage ( ) throws SignDocException

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.

synchronized int de.softpro.doc.SignDocVerificationResult.getLockMDP ( ) throws SignDocException

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

int de.softpro.doc.SignDocVerificationResult.getMethod ( ) throws SignDocException

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.

Returns:: The signing method (SignDocSignatureParameters.m_digsig_pkcs7_detached etc., including SignDocSignatureParameters.m_digsig_cades_rfc3161, excluding SignDocSignatureParameters.m_default).

int de.softpro.doc.SignDocVerificationResult.getModificationState ( ) throws SignDocException

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: ms_unmodified, ms_allowed, or ms_prohibited.

See also:: getDocMDP(), getErrorMessage(), getLockMDP(), getState(), SignDocDocument.verifySignature(),

byte [] de.softpro.doc.SignDocVerificationResult.getSignatureBlob ( String aName ) throws SignDocException

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

Parameters:

[in] aName The name of the property.

Returns:: The blob retrieved from the signature field or null if the property does not exist.

See also:: getSignatureString(), SignDocSignatureParameters.setBlob()

String de.softpro.doc.SignDocVerificationResult.getSignatureString ( String aName ) throws SignDocException

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 de.softpro.doc.SignDocSignatureParameters.setString().

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

Parameters:

[in] aName The name of the parameter.

Returns:: The string retrieved from the signature field or null if the parameter does not exist. If flag SignDocDocument.f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: getMethod(), getSignatureBlob(), getTimeStamp(), SignDocDocument.getLastTimestamp(), SignDocSignatureParameters.setString()

Todo:: document which parameters are available for which methods

int de.softpro.doc.SignDocVerificationResult.getState ( ) throws SignDocException

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.

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

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

Returns:: The signature state (ss_document_extended etc.)

See also:: getErrorMessage(), getModificationState(), verifyCertificateChain(), SignDocDocument.verifySignature()

String de.softpro.doc.SignDocVerificationResult.getTimeStamp ( ) throws SignDocException

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

int de.softpro.doc.SignDocVerificationResult.getTimeStampCertificateRevocationState ( ) throws SignDocException

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 is not crs_ok.

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

Returns:: The result of the certificate revocation check (crs_ok etc.)

See also:: verifyTimeStampCertificateChain(), verifyTimeStampCertificateSimplified()

byte [][] de.softpro.doc.SignDocVerificationResult.getTimeStampCertificates ( ) throws SignDocException

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 de.softpro.doc.SignDocVerificationResult.getTimeStampDigestAlgorithm ( ) throws SignDocException

Get the message digest algorithm of the RFC 3161 timestamp.

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"	tsha_sha1
"SHA-256"	tsha_sha256
"SHA-384"	tsha_sha384
"SHA-512"	tsha_sha512

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

int de.softpro.doc.SignDocVerificationResult.getTimeStampState ( ) throws SignDocException

Get the state of the RFC 3161 time stamp.

Returns:: The state of the RFC 3161 time stamp (tss_valid etc.)

int de.softpro.doc.SignDocVerificationResult.verifyCertificateChain ( SignDocVerificationParameters aParameters ) throws SignDocException

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 (return value not rc_ok) or the verification result returned is not ccs_ok or getCertificateRevocationState() won't return crs_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 Verification parameters or null for default parameters.

Returns:: The result of the certificate chain verification (ccs_ok etc.)

See also:: getCertificateChainLength(), getCertificateRevocationState(), getMethod(), verifyCertificateSimplified(), verifyTimeStampCertificateChain()

int de.softpro.doc.SignDocVerificationResult.verifyCertificateSimplified ( SignDocVerificationParameters aParameters ) throws SignDocException

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

int de.softpro.doc.SignDocVerificationResult.verifyTimeStampCertificateChain ( SignDocVerificationParameters aParameters ) throws SignDocException

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 is not ccs_ok.

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

Parameters:

[in] aParameters verification parameters or null for default parameters.

Returns:: The result of the certificate chain verification (ccs_ok etc.)

See also:: getTimeStampCertificateRevocationState(), verifyTimeStampCertificateSimplified()

int de.softpro.doc.SignDocVerificationResult.verifyTimeStampCertificateSimplified ( SignDocVerificationParameters aParameters ) throws SignDocException

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", 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.