From a678ff1b6e648180f1406e660ca73cd0b2c7f03f Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Sat, 14 Aug 2021 11:39:13 +0200
Subject: [PATCH] Add documentation to classes related to verification of
 cleartext signed data

---
 .../InMemoryMultiPassStrategy.java                     | 10 +++++++++-
 .../cleartext_signatures/MultiPassStrategy.java        |  6 +++++-
 .../VerifyCleartextSignatures.java                     |  3 +++
 .../WriteToFileMultiPassStrategy.java                  |  7 +++++--
 4 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/InMemoryMultiPassStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/InMemoryMultiPassStrategy.java
index 49dfa005..e9de8454 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/InMemoryMultiPassStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/InMemoryMultiPassStrategy.java
@@ -18,6 +18,14 @@ package org.pgpainless.signature.cleartext_signatures;
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
+/**
+ * Implementation of the {@link MultiPassStrategy}.
+ * This class keeps the read data in memory by caching the data inside a {@link ByteArrayOutputStream}.
+ *
+ * Note, that this class is suitable and efficient for processing small amounts of data.
+ * For larger data like encrypted files, use of the {@link WriteToFileMultiPassStrategy} is recommended to
+ * prevent {@link OutOfMemoryError OutOfMemoryErrors} and other issues.
+ */
 public class InMemoryMultiPassStrategy implements MultiPassStrategy {
 
     private final ByteArrayOutputStream cache = new ByteArrayOutputStream();
@@ -29,7 +37,7 @@ public class InMemoryMultiPassStrategy implements MultiPassStrategy {
 
     @Override
     public ByteArrayInputStream getMessageInputStream() {
-        return new ByteArrayInputStream(cache.toByteArray());
+        return new ByteArrayInputStream(getBytes());
     }
 
     public byte[] getBytes() {
diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/MultiPassStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/MultiPassStrategy.java
index af6cc2cb..5f7c76ba 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/MultiPassStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/MultiPassStrategy.java
@@ -22,7 +22,11 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
- * Interface that describes a strategy to deal with the fact that detached signatures require multiple passes
+ * Since the {@link CleartextSignatureProcessor} needs to read the whole data twice in order to verify signatures,
+ * a strategy for how to cache the read data is required.
+ * Otherwise large data kept in memory could cause {@link OutOfMemoryError OutOfMemoryErrors} or other issues.
+ *
+ * This is an Interface that describes a strategy to deal with the fact that detached signatures require multiple passes
  * to do verification.
  *
  * This interface can be used to write the signed data stream out via {@link #getMessageOutputStream()} and later
diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/VerifyCleartextSignatures.java b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/VerifyCleartextSignatures.java
index 9078d361..f214a689 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/VerifyCleartextSignatures.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/VerifyCleartextSignatures.java
@@ -23,6 +23,9 @@ import org.bouncycastle.openpgp.PGPException;
 import org.bouncycastle.openpgp.PGPPublicKeyRing;
 import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
 
+/**
+ * Interface defining the API for verification of cleartext signed documents.
+ */
 public interface VerifyCleartextSignatures {
 
     /**
diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/WriteToFileMultiPassStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/WriteToFileMultiPassStrategy.java
index 25b1e878..16de077e 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/WriteToFileMultiPassStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/WriteToFileMultiPassStrategy.java
@@ -23,9 +23,12 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
- * File-based multi-pass strategy.
- * When processing the signed data the first time, the data is being written out into a file.
+ * Implementation of the {@link MultiPassStrategy}.
+ * When processing signed data the first time, the data is being written out into a file.
  * For the second pass, that file is being read again.
+ *
+ * This strategy is recommended when larger amounts of data need to be processed.
+ * For smaller files, {@link InMemoryMultiPassStrategy} yields higher efficiency.
  */
 public class WriteToFileMultiPassStrategy implements MultiPassStrategy {