Package org.pgpainless.decryption_verification

# Class ConsumerOptions

java.lang.Object
org.pgpainless.decryption_verification.ConsumerOptions

public class ConsumerOptions extends Object
Options for decryption and signature verification.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`ConsumerOptions.CertificateSource`
Source for OpenPGP certificates.

## Constructor Summary

Constructors
Constructor
Description
`ConsumerOptions()`

## Method Summary

Modifier and Type
Method
Description
`ConsumerOptions`
`addCustomDecryptorFactory(CustomPublicKeyDataDecryptorFactory factory)`
Add a custom `PublicKeyDataDecryptorFactory` which enable decryption of messages, e.g.
`ConsumerOptions`
`addDecryptionKey(org.bouncycastle.openpgp.PGPSecretKeyRing key)`
Add a key for message decryption.
`ConsumerOptions`
`addDecryptionKey(org.bouncycastle.openpgp.PGPSecretKeyRing key, SecretKeyRingProtector keyRingProtector)`
Add a key for message decryption.
`ConsumerOptions`
`addDecryptionKeys(org.bouncycastle.openpgp.PGPSecretKeyRingCollection keys, SecretKeyRingProtector keyRingProtector)`
Add the keys in the provided key collection for message decryption.
`ConsumerOptions`
`addDecryptionPassphrase(Passphrase passphrase)`
Add a passphrase for message decryption.
`ConsumerOptions`
`addVerificationCert(org.bouncycastle.openpgp.PGPPublicKeyRing verificationCert)`
Add a certificate (public key ring) for signature verification.
`ConsumerOptions`
`addVerificationCerts(org.bouncycastle.openpgp.PGPPublicKeyRingCollection verificationCerts)`
Add a set of certificates (public key rings) for signature verification.
`ConsumerOptions`
`addVerificationOfDetachedSignature(org.bouncycastle.openpgp.PGPSignature detachedSignature)`
Add a detached signature for the signature verification process.
`ConsumerOptions`
`addVerificationOfDetachedSignatures(InputStream signatureInputStream)`
Add some detached signatures from the given `InputStream` for verification.
`ConsumerOptions`
`addVerificationOfDetachedSignatures(List<org.bouncycastle.openpgp.PGPSignature> detachedSignatures)`
Add some detached signatures for verification.
`ConsumerOptions`
`forceNonOpenPgpData()`
Force PGPainless to handle the data provided by the `InputStream` as non-OpenPGP data.
`static ConsumerOptions`
`get()`
`Set<org.bouncycastle.openpgp.PGPPublicKeyRing>`
`getCertificates()`
Deprecated.
use `getCertificateSource()` instead.
`ConsumerOptions.CertificateSource`
`getCertificateSource()`
Return an object holding available certificates for signature verification.
`Set<org.bouncycastle.openpgp.PGPSecretKeyRing>`
`getDecryptionKeys()`
Return the set of available decryption keys.
`Set<Passphrase>`
`getDecryptionPassphrases()`
Return the set of available message decryption passphrases.
`Set<org.bouncycastle.openpgp.PGPSignature>`
`getDetachedSignatures()`
Return the set of detached signatures the user provided.
`MissingPublicKeyCallback`
`getMissingCertificateCallback()`
Return the callback that gets called when a certificate for signature verification is missing.
`MultiPassStrategy`
`getMultiPassStrategy()`
Return the currently configured `MultiPassStrategy`.
`SecretKeyRingProtector`
`getSecretKeyProtector(org.bouncycastle.openpgp.PGPSecretKeyRing decryptionKeyRing)`
Return the `SecretKeyRingProtector` for the given `PGPSecretKeyRing`.
`SessionKey`
`getSessionKey()`
Return the session key.
`Date`
`getVerifyNotAfter()`
Return the latest possible creation date on which signatures made on the message are considered valid.
`Date`
`getVerifyNotBefore()`
Return the earliest creation date on which signatures on the message are considered valid.
`ConsumerOptions`
`setIgnoreMDCErrors(boolean ignoreMDCErrors)`
Deprecated.
`ConsumerOptions`
`setMissingCertificateCallback(MissingPublicKeyCallback callback)`
Set a callback that's used when a certificate (public key) is missing for signature verification.
`ConsumerOptions`
`setMissingKeyPassphraseStrategy(MissingKeyPassphraseStrategy strategy)`
Specify the `MissingKeyPassphraseStrategy`.
`ConsumerOptions`
`setMultiPassStrategy(MultiPassStrategy multiPassStrategy)`
Set a custom multi-pass strategy for processing cleartext-signed messages.
`ConsumerOptions`
`setSessionKey(SessionKey sessionKey)`
Attempt decryption using a session key.
`ConsumerOptions`
`verifyNotAfter(Date timestamp)`
Consider signatures on the message made after the given timestamp invalid.
`ConsumerOptions`
`verifyNotBefore(Date timestamp)`
Consider signatures on the message made before the given timestamp invalid.

### Methods inherited from class java.lang.Object

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

## Constructor Details

### ConsumerOptions

public ConsumerOptions()

## Method Details

### get

public static ConsumerOptions get()

### verifyNotBefore

public ConsumerOptions verifyNotBefore(Date timestamp)
Consider signatures on the message made before the given timestamp invalid. Null means no limitation.

Parameters:
  `timestamp` - timestamp
Returns:
  options

### getVerifyNotBefore

@Nullable public Date getVerifyNotBefore()
Return the earliest creation date on which signatures on the message are considered valid. Signatures made earlier than this date are considered invalid.

Returns:
  earliest allowed signature creation date or null

### verifyNotAfter

public ConsumerOptions verifyNotAfter(Date timestamp)
Consider signatures on the message made after the given timestamp invalid. Null means no limitation.

Parameters:
  `timestamp` - timestamp
Returns:
  options

### getVerifyNotAfter

public Date getVerifyNotAfter()
Return the latest possible creation date on which signatures made on the message are considered valid. Signatures made later than this date are considered invalid.

Returns:
  Latest possible creation date or null.

### addVerificationCert

public ConsumerOptions addVerificationCert(org.bouncycastle.openpgp.PGPPublicKeyRing verificationCert)
Add a certificate (public key ring) for signature verification.

Parameters:
  `verificationCert` - certificate for signature verification
Returns:
  options

### addVerificationCerts

public ConsumerOptions addVerificationCerts(org.bouncycastle.openpgp.PGPPublicKeyRingCollection verificationCerts)
Add a set of certificates (public key rings) for signature verification.

Parameters:
  `verificationCerts` - certificates for signature verification
Returns:
  options

### addVerificationOfDetachedSignatures

public ConsumerOptions addVerificationOfDetachedSignatures(InputStream signatureInputStream) throws IOException, org.bouncycastle.openpgp.PGPException
Add some detached signatures from the given `InputStream` for verification.

Parameters:
  `signatureInputStream` - input stream of detached signatures
Returns:
  options
Throws:
  `IOException` - in case of an IO error
  `org.bouncycastle.openpgp.PGPException` - in case of an OpenPGP error

### addVerificationOfDetachedSignatures

public ConsumerOptions addVerificationOfDetachedSignatures(List<org.bouncycastle.openpgp.PGPSignature> detachedSignatures)
Add some detached signatures for verification.

Parameters:
  `detachedSignatures` - detached signatures
Returns:
  options

### addVerificationOfDetachedSignature

public ConsumerOptions addVerificationOfDetachedSignature(org.bouncycastle.openpgp.PGPSignature detachedSignature)
Add a detached signature for the signature verification process.

Parameters:
  `detachedSignature` - detached signature
Returns:
  options

### setMissingCertificateCallback

public ConsumerOptions setMissingCertificateCallback(MissingPublicKeyCallback callback)
Set a callback that's used when a certificate (public key) is missing for signature verification.

Parameters:
  `callback` - callback
Returns:
  options

### setSessionKey

public ConsumerOptions setSessionKey(@Nonnull SessionKey sessionKey)
Attempt decryption using a session key. Note: PGPainless does not yet support decryption with session keys.

Parameters:
  `sessionKey` - session key
Returns:
  options
See Also:
  - RFC4880 on Session Keys

### getSessionKey

@Nullable public SessionKey getSessionKey()
Return the session key.

Returns:
  session key or null

### addDecryptionKey

public ConsumerOptions addDecryptionKey(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing key)
Add a key for message decryption. The key is expected to be unencrypted.

Parameters:
  `key` - unencrypted key
Returns:
  options

### addDecryptionKey

public ConsumerOptions addDecryptionKey(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing key, @Nonnull SecretKeyRingProtector keyRingProtector)
Add a key for message decryption. If the key is encrypted, the `SecretKeyRingProtector` is used to decrypt it when needed.

Parameters:
  `key` - key
  `keyRingProtector` - protector for the secret key
Returns:
  options

### addDecryptionKeys

public ConsumerOptions addDecryptionKeys(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRingCollection keys, @Nonnull SecretKeyRingProtector keyRingProtector)
Add the keys in the provided key collection for message decryption.

Parameters:
  `keys` - key collection
  `keyRingProtector` - protector for encrypted secret keys
Returns:
  options

### addDecryptionPassphrase

public ConsumerOptions addDecryptionPassphrase(@Nonnull Passphrase passphrase)
Add a passphrase for message decryption. This passphrase will be used to try to decrypt messages which were symmetrically encrypted for a passphrase.

Parameters:
  `passphrase` - passphrase
Returns:
  options
See Also:
  - Symmetrically Encrypted Data Packet

### addCustomDecryptorFactory

public ConsumerOptions addCustomDecryptorFactory(@Nonnull CustomPublicKeyDataDecryptorFactory factory)
Add a custom `PublicKeyDataDecryptorFactory` which enable decryption of messages, e.g. using hardware-backed secret keys. (See e.g. `HardwareSecurity.HardwareDataDecryptorFactory`).

Parameters:
  `factory` - decryptor factory
Returns:
  options

### getDecryptionKeys

@Nonnull public Set<org.bouncycastle.openpgp.PGPSecretKeyRing> getDecryptionKeys()
Return the set of available decryption keys.

Returns:
  decryption keys

### getDecryptionPassphrases

@Nonnull public Set<Passphrase> getDecryptionPassphrases()
Return the set of available message decryption passphrases.

Returns:
  decryption passphrases

### getCertificates

@Deprecated @Nonnull public Set<org.bouncycastle.openpgp.PGPPublicKeyRing> getCertificates()
Deprecated.
use `getCertificateSource()` instead.
Return the explicitly set verification certificates.

Returns:
  verification certs

### getCertificateSource

@Nonnull public ConsumerOptions.CertificateSource getCertificateSource()
Return an object holding available certificates for signature verification.

Returns:
  certificate source

### getMissingCertificateCallback

@Nullable public MissingPublicKeyCallback getMissingCertificateCallback()
Return the callback that gets called when a certificate for signature verification is missing. This method might return

    null

if the users hasn't set a callback.

Returns:
  missing public key callback

### getSecretKeyProtector

@Nonnull public SecretKeyRingProtector getSecretKeyProtector(org.bouncycastle.openpgp.PGPSecretKeyRing decryptionKeyRing)
Return the `SecretKeyRingProtector` for the given `PGPSecretKeyRing`.

Parameters:
  `decryptionKeyRing` - secret key
Returns:
  protector for that particular secret key

### getDetachedSignatures

@Nonnull public Set<org.bouncycastle.openpgp.PGPSignature> getDetachedSignatures()
Return the set of detached signatures the user provided.

Returns:
  detached signatures

### setIgnoreMDCErrors

@Deprecated public ConsumerOptions setIgnoreMDCErrors(boolean ignoreMDCErrors)
Deprecated.
By default, PGPainless will require encrypted messages to make use of SEIP data packets. Those are Symmetrically Encrypted Integrity Protected Data packets. Symmetrically Encrypted Data Packets without integrity protection are rejected by default. Furthermore, PGPainless will throw an exception if verification of the MDC error detection code of the SEIP packet fails. Failure of MDC verification indicates a tampered ciphertext, which might be the cause of an attack or data corruption. This method can be used to ignore MDC errors and allow PGPainless to consume encrypted data without integrity protection. If the flag

    ignoreMDCErrors

is set to true, PGPainless will

- not throw exceptions for SEIP packets with tampered ciphertext
- not throw exceptions for SEIP packets with tampered MDC
- not throw exceptions for MDCs with bad CTB
- not throw exceptions for MDCs with bad length

It will however still throw an exception if it encounters a SEIP packet with missing or truncated MDC

Parameters:
  `ignoreMDCErrors` - true if MDC errors or missing MDCs shall be ignored, false otherwise.
Returns:
  options
See Also:
  - Sym. Encrypted Integrity Protected Data Packet

### forceNonOpenPgpData

public ConsumerOptions forceNonOpenPgpData()
Force PGPainless to handle the data provided by the `InputStream` as non-OpenPGP data. This workaround might come in handy if PGPainless accidentally mistakes the data for binary OpenPGP data.

Returns:
  options

### setMissingKeyPassphraseStrategy

public ConsumerOptions setMissingKeyPassphraseStrategy(MissingKeyPassphraseStrategy strategy)
Specify the `MissingKeyPassphraseStrategy`. This strategy defines, how missing passphrases for unlocking secret keys are handled. In interactive mode (`MissingKeyPassphraseStrategy.INTERACTIVE`) PGPainless will try to obtain missing passphrases for secret keys via the `SecretKeyRingProtectors` `SecretKeyPassphraseProvider` callback. In non-interactice mode (`MissingKeyPassphraseStrategy.THROW_EXCEPTION`, PGPainless will instead throw a `MissingPassphraseException` containing the ids of all keys for which there are missing passphrases.

Parameters:
  `strategy` - strategy
Returns:
  options

### setMultiPassStrategy

public ConsumerOptions setMultiPassStrategy(@Nonnull MultiPassStrategy multiPassStrategy)
Set a custom multi-pass strategy for processing cleartext-signed messages. Uses `InMemoryMultiPassStrategy` by default.

Parameters:
  `multiPassStrategy` - multi-pass caching strategy
Returns:
  builder

### getMultiPassStrategy

public MultiPassStrategy getMultiPassStrategy()
Return the currently configured `MultiPassStrategy`. Defaults to `InMemoryMultiPassStrategy`.

Returns:
  multi-pass strategy