PGPainless/pgpainless
PGPainless/pgpainless
1
0
Fork 0
mirror of https://github.com/pgpainless/pgpainless.git synced 2024-12-27 05:17:59 +01:00
Code Issues Releases Wiki Activity

Add missing javadoc to ConsumerOptions

Browse source
This commit is contained in:
Paul Schaub 2023-01-04 18:50:10 +01:00
parent abf723cc6c
commit 41cc71c274
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
1 changed files with 87 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

99
pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java
View file

@ -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<SubkeyIdentifier, PublicKeyDataDecryptorFactory> customPublicKeyDataDecryptorFactories = new HashMap<>();
private final Map<SubkeyIdentifier, PublicKeyDataDecryptorFactory> customPublicKeyDataDecryptorFactories =
new HashMap<>();
private final Map<PGPSecretKeyRing, SecretKeyRingProtector> decryptionKeys = new HashMap<>();
private final Set<Passphrase> 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<PGPSignature> signatures = SignatureUtils.readSignatures(signatureInputStream);
return addVerificationOfDetachedSignatures(signatures);
}
/**
* Add some detached signatures for verification.
*
* @param detachedSignatures detached signatures
* @return options
*/
public ConsumerOptions addVerificationOfDetachedSignatures(List<PGPSignature> 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<SubkeyIdentifier, PublicKeyDataDecryptorFactory> getCustomDecryptorFactories() {
return new HashMap<>(customPublicKeyDataDecryptorFactories);
}
/**
* Return the set of available decryption keys.
*
* @return decryption keys
*/
public @Nonnull Set<PGPSecretKeyRing> getDecryptionKeys() {
return Collections.unmodifiableSet(decryptionKeys.keySet());
}
/**
* Return the set of available message decryption passphrases.
*
* @return decryption passphrases
*/
public @Nonnull Set<Passphrase> 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 <pre>null</pre> 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<PGPSignature> 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 <pre>ignoreMDCErrors</pre> is set to true, PGPainless will
* <ul>
* <li>not throw exceptions for SEIP packets with tampered ciphertext</li>
@ -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 <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.13">Sym. Encrypted Integrity Protected Data Packet</a>
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.13">
* Sym. Encrypted Integrity Protected Data Packet</a>
* @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<PGPCertificateStore> stores = new ArrayList<>();