From 07c689b5564e5c7252d904dd8c993fe1b0894c03 Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Mon, 2 Jul 2018 20:28:23 +0200
Subject: [PATCH] Add javadoc

---
 .../pgpainless/key/KeyRingReader.java         | 15 ++++++++
 .../SymmetricEncryptorDecryptor.java          | 36 +++++++++++++++++--
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/pgpainless/pgpainless/key/KeyRingReader.java b/src/main/java/org/pgpainless/pgpainless/key/KeyRingReader.java
index 44847dc2..af601905 100644
--- a/src/main/java/org/pgpainless/pgpainless/key/KeyRingReader.java
+++ b/src/main/java/org/pgpainless/pgpainless/key/KeyRingReader.java
@@ -1,3 +1,18 @@
+/*
+ * Copyright 2018 Paul Schaub.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.pgpainless.pgpainless.key;
 
 import java.io.ByteArrayInputStream;
diff --git a/src/main/java/org/pgpainless/pgpainless/symmetric_encryption/SymmetricEncryptorDecryptor.java b/src/main/java/org/pgpainless/pgpainless/symmetric_encryption/SymmetricEncryptorDecryptor.java
index 22f355de..ce34ac5d 100644
--- a/src/main/java/org/pgpainless/pgpainless/symmetric_encryption/SymmetricEncryptorDecryptor.java
+++ b/src/main/java/org/pgpainless/pgpainless/symmetric_encryption/SymmetricEncryptorDecryptor.java
@@ -48,9 +48,22 @@ import org.pgpainless.pgpainless.algorithm.SymmetricKeyAlgorithm;
  */
 public class SymmetricEncryptorDecryptor {
 
+    /**
+     * Encrypt some {@code data} symmetrically using an {@code encryptionAlgorithm} and a given {@code password}.
+     * The input data will be compressed using the given {@code compressionAlgorithm} and packed in a modification
+     * detection package, which is then encrypted.
+     *
+     * @param data bytes that will be encrypted
+     * @param password password that will be used to encrypt the data
+     * @param encryptionAlgorithm symmetric algorithm that will be used to encrypt the data
+     * @param compressionAlgorithm compression algorithm that will be used to compress the data
+     * @return encrypted data
+     * @throws IOException IO is dangerous
+     * @throws PGPException OpenPGP is brittle
+     */
     public static byte[] symmetricallyEncrypt(byte[] data,
                                               char[] password,
-                                              SymmetricKeyAlgorithm algorithm,
+                                              SymmetricKeyAlgorithm encryptionAlgorithm,
                                               CompressionAlgorithm compressionAlgorithm)
             throws IOException, PGPException {
 
@@ -59,7 +72,7 @@ public class SymmetricEncryptorDecryptor {
         ByteArrayOutputStream bOut = new ByteArrayOutputStream();
 
         PGPEncryptedDataGenerator encGen = new PGPEncryptedDataGenerator(
-                new JcePGPDataEncryptorBuilder(algorithm.getAlgorithmId())
+                new JcePGPDataEncryptorBuilder(encryptionAlgorithm.getAlgorithmId())
                         .setWithIntegrityPacket(true)
                         .setSecureRandom(new SecureRandom())
                         .setProvider("BC"));
@@ -74,6 +87,17 @@ public class SymmetricEncryptorDecryptor {
         return bOut.toByteArray();
     }
 
+    /**
+     * Decrypt and decompress some symmetrically encrypted data using a password.
+     * Note, that decryption will fail if the given data is not integrity protected with a modification detection
+     * package.
+     *
+     * @param data encrypted data
+     * @param password password to decrypt the data
+     * @return decrypted data
+     * @throws IOException IO is dangerous
+     * @throws PGPException OpenPGP is brittle
+     */
     public static byte[] symmetricallyDecrypt(byte[] data, char[] password) throws IOException, PGPException {
         InputStream in = new BufferedInputStream(new ByteArrayInputStream(data));
         in = PGPUtil.getDecoderStream(in);
@@ -123,6 +147,14 @@ public class SymmetricEncryptorDecryptor {
         return outputStream.toByteArray();
     }
 
+    /**
+     * Wrap some data in an OpenPGP compressed data package.
+     *
+     * @param clearData uncompressed data
+     * @param algorithm compression algorithm
+     * @return compressed data
+     * @throws IOException IO is dangerous
+     */
     private static byte[] compress(byte[] clearData, int algorithm) throws IOException
     {
         ByteArrayOutputStream bOut = new ByteArrayOutputStream();