From 41cc71c274a3560019010de300a56a035aabb6d4 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Wed, 4 Jan 2023 18:50:10 +0100 Subject: [PATCH] Add missing javadoc to ConsumerOptions --- .../ConsumerOptions.java | 99 ++++++++++++++++--- 1 file changed, 87 insertions(+), 12 deletions(-) diff --git a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java index f7b3c020..33404c48 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java +++ b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java @@ -42,7 +42,6 @@ import pgp.certificate_store.exception.BadDataException; */ public class ConsumerOptions { - private boolean ignoreMDCErrors = false; private boolean forceNonOpenPgpData = false; @@ -55,7 +54,8 @@ public class ConsumerOptions { // Session key for decryption without passphrase/key private SessionKey sessionKey = null; - private final Map customPublicKeyDataDecryptorFactories = new HashMap<>(); + private final Map customPublicKeyDataDecryptorFactories = + new HashMap<>(); private final Map decryptionKeys = new HashMap<>(); private final Set decryptionPassphrases = new HashSet<>(); @@ -135,16 +135,38 @@ public class ConsumerOptions { return this; } + /** + * Pass in a {@link PGPCertificateStore} from which certificates can be sourced for signature verification. + * + * @param certificateStore certificate store + * @return options + */ public ConsumerOptions addVerificationCerts(PGPCertificateStore certificateStore) { this.certificates.addStore(certificateStore); return this; } - public ConsumerOptions addVerificationOfDetachedSignatures(InputStream signatureInputStream) throws IOException, PGPException { + /** + * Add some detached signatures from the given {@link InputStream} for verification. + * + * @param signatureInputStream input stream of detached signatures + * @return options + * + * @throws IOException in case of an IO error + * @throws PGPException in case of an OpenPGP error + */ + public ConsumerOptions addVerificationOfDetachedSignatures(InputStream signatureInputStream) + throws IOException, PGPException { List signatures = SignatureUtils.readSignatures(signatureInputStream); return addVerificationOfDetachedSignatures(signatures); } + /** + * Add some detached signatures for verification. + * + * @param detachedSignatures detached signatures + * @return options + */ public ConsumerOptions addVerificationOfDetachedSignatures(List detachedSignatures) { for (PGPSignature signature : detachedSignatures) { addVerificationOfDetachedSignature(signature); @@ -211,14 +233,15 @@ public class ConsumerOptions { } /** - * Add a key for message decryption. If the key is encrypted, the {@link SecretKeyRingProtector} is used to decrypt it - * when needed. + * Add a key for message decryption. If the key is encrypted, the {@link SecretKeyRingProtector} + * is used to decrypt it when needed. * * @param key key * @param keyRingProtector protector for the secret key * @return options */ - public ConsumerOptions addDecryptionKey(@Nonnull PGPSecretKeyRing key, @Nonnull SecretKeyRingProtector keyRingProtector) { + public ConsumerOptions addDecryptionKey(@Nonnull PGPSecretKeyRing key, + @Nonnull SecretKeyRingProtector keyRingProtector) { decryptionKeys.put(key, keyRingProtector); return this; } @@ -230,7 +253,8 @@ public class ConsumerOptions { * @param keyRingProtector protector for encrypted secret keys * @return options */ - public ConsumerOptions addDecryptionKeys(@Nonnull PGPSecretKeyRingCollection keys, @Nonnull SecretKeyRingProtector keyRingProtector) { + public ConsumerOptions addDecryptionKeys(@Nonnull PGPSecretKeyRingCollection keys, + @Nonnull SecretKeyRingProtector keyRingProtector) { for (PGPSecretKeyRing key : keys) { addDecryptionKey(key, keyRingProtector); } @@ -264,14 +288,31 @@ public class ConsumerOptions { return this; } + /** + * Return the custom {@link PublicKeyDataDecryptorFactory PublicKeyDataDecryptorFactories} that were + * set by the user. + * These factories can be used to decrypt session keys using a custom logic. + * + * @return custom decryptor factories + */ Map getCustomDecryptorFactories() { return new HashMap<>(customPublicKeyDataDecryptorFactories); } + /** + * Return the set of available decryption keys. + * + * @return decryption keys + */ public @Nonnull Set getDecryptionKeys() { return Collections.unmodifiableSet(decryptionKeys.keySet()); } + /** + * Return the set of available message decryption passphrases. + * + * @return decryption passphrases + */ public @Nonnull Set getDecryptionPassphrases() { return Collections.unmodifiableSet(decryptionPassphrases); } @@ -287,18 +328,40 @@ public class ConsumerOptions { return certificates.getExplicitCertificates(); } + /** + * Return an object holding available certificates for signature verification. + * + * @return certificate source + */ public @Nonnull CertificateSource getCertificateSource() { return certificates; } + /** + * 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. + * + * @return missing public key callback + */ public @Nullable MissingPublicKeyCallback getMissingCertificateCallback() { return missingCertificateCallback; } + /** + * Return the {@link SecretKeyRingProtector} for the given {@link PGPSecretKeyRing}. + * + * @param decryptionKeyRing secret key + * @return protector for that particular secret key + */ public @Nonnull SecretKeyRingProtector getSecretKeyProtector(PGPSecretKeyRing decryptionKeyRing) { return decryptionKeys.get(decryptionKeyRing); } + /** + * Return the set of detached signatures the user provided. + * + * @return detached signatures + */ public @Nonnull Set getDetachedSignatures() { return Collections.unmodifiableSet(detachedSignatures); } @@ -307,12 +370,14 @@ public class ConsumerOptions { * 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. + * 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. + * 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. + * 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
    • @@ -323,7 +388,8 @@ public class ConsumerOptions { * * It will however still throw an exception if it encounters a SEIP packet with missing or truncated MDC * - * @see Sym. Encrypted Integrity Protected Data Packet + * @see + * Sym. Encrypted Integrity Protected Data Packet * @param ignoreMDCErrors true if MDC errors or missing MDCs shall be ignored, false otherwise. * @return options */ @@ -353,6 +419,11 @@ public class ConsumerOptions { return this; } + /** + * Return true, if the ciphertext should be handled as binary non-OpenPGP data. + * + * @return true if non-OpenPGP data is forced + */ boolean isForceNonOpenPgpData() { return forceNonOpenPgpData; } @@ -407,6 +478,10 @@ public class ConsumerOptions { return multiPassStrategy; } + /** + * Source for OpenPGP certificates. + * When verifying signatures on a message, this object holds available signer certificates. + */ public static class CertificateSource { private List stores = new ArrayList<>();