iaik.hlapi
Class DecrypterVerifier

java.lang.Object
  iaik.hlapi.DecrypterVerifier

Direct Known Subclasses:

CMSDecrypterVerifier, SMimeDecrypterVerifier, XMLDecrypterVerifier

public abstract class DecrypterVerifier
extends Object

Objects of this class decrypt encrypted data and/or verify signatures.

First, the application instantiates a DecrypterVerifier and registers a decryption key or multiple of them.

  DecrypterVerifier decrypterVerifier = new CMSDecrypterVerifier();
  
  decrypterVerifier.registerDecryptionKey(decryptionKey);
 

Second, the application processes the encrypted and/or signed data. Either as a single byte array using

  byte[] data = decrypterVerifier.process(encEnvData_);
 

or via an InputStream

  InputStream encryptedAndSignedData = ...
  InputStream dataStream = decrypterVerifier.process(encryptedAndSignedData);
  // ... read the dataStream
 

Please note that the application should fully read the data stream before verifying the signature. Otherwise, the object may need to buffer large amounts of data internally.

After reading the data, the application can finally verify the signature and get the signing time

  CertValidator certValidator = new PkixCertValidator();
  certValidator.addTrustedCertificate(trustedRootCert1);
  certValidator.addTrustedCertificate(trustedRootCert2);

  X509Certificate[] signerCertChain = decrypterVerifier.verify(certValidator);
  Date signingTime = decrypterVerifier.getSigningTime();
 

Method Summary

abstract void	dropDecryptionKeys() Release all references to any previously set decryption keys.
abstract Date	getSigningTime() Get the signing time which was encoded as a signed property in the signature object.
byte[]	process(byte[] data) Decrypt and/or verify the given data.
abstract InputStream	process(InputStream data) Decrypt and/or verify the given data.
abstract void	registerDecryptionKey(KeyAndCertificate decryptionKey) Register a key to be a decryption key for the associated certificate.
X509Certificate[]	verify(CertValidator validator) Verify the signature value of the signed data that was recently parsed using process(byte[]) or process(InputStream).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

registerDecryptionKey

public abstract void registerDecryptionKey(KeyAndCertificate decryptionKey)
                                    throws HlApiException

Register a key to be a decryption key for the associated certificate. The application may call this method more than once to register multiple decryption keys. The decryption operation will select one of them automatically.

The certificate in the decryptionKey may be null. In this case, the decryption method will try to use this key for decrypting the data. However, it is recommended to provide the certificate that belongs to the private key.

Parameters:

decryptionKey - The decryption key and the certificate.

Throws:

HlApiException - If handling the certificate fails.

Preconditions

decryptionKey != null

dropDecryptionKeys

public abstract void dropDecryptionKeys()

Release all references to any previously set decryption keys.

process

public byte[] process(byte[] data)
               throws NoKeyException,
                      HlApiException

Decrypt and/or verify the given data.

If the data is encrypted, a suitable decryption keys must have been registered before using registerDecryptionKey(KeyAndCertificate).

Parameters:

data - The encrypted and/or signed data.

Returns:

The decrypted/verified content data.

Throws:

NoKeyException - If there is no suitable key available for decryption.

HlApiException - If decryption or verification fails.

Preconditions

(envData != null)

Postconditions

(result != null)

process

public abstract InputStream process(InputStream data)
                             throws IOException,
                                    NoKeyException,
                                    HlApiException

Decrypt and/or verify the given data.

If the data is encrypted, a suitable decryption keys must have been registered before using registerDecryptionKey(KeyAndCertificate).

Parameters:

data - The stream that provides the encrypted and/or signed data.

Returns:

The decrypted/verified content data.

Throws:

IOException - If reading from the given stream fails.

NoKeyException - If there is no suitable key available for decryption.

HlApiException - If decryption or verification fails.

Preconditions

(data != null)

Postconditions

(result != null)

verify

public X509Certificate[] verify(CertValidator validator)
                         throws SignatureVerificationException,
                                CertificateValidationException,
                                HlApiException

Verify the signature value of the signed data that was recently parsed using process(byte[]) or process(InputStream). This method cryptographically verifies of the signature value and validates the signer certificate using the given validator. If the application does not specify a certificate validator, this method only performs a cryptographic verification but returns the certificate without any validation.

Parameters:

validator - The certificate validator.

Returns:

The certificate chain. It was successfully validated if a validator was specified. It is null, if there is no signature in the data structure or if no signed data has been parsed before.

Throws:

SignatureVerificationException - If the cryptographic signature verification fails.

CertificateValidationException - If the validation of the signing certificate fails.

HlApiException - If the verification fails for some other reason.

getSigningTime

public abstract Date getSigningTime()
                             throws HlApiException

Get the signing time which was encoded as a signed property in the signature object.

Returns:

The signing time or null if there was no signing time encoded in the signed data or if there was no signature.

Throws:

HlApiException - If parsing the signing time out of the signature structure fails.