Class ConsumerOptions

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

public class ConsumerOptions extends Object
Options for decryption and signature verification.
  • 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:
    • 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:
    • 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.
      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:
    • 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