Add documentation to Policy

pgpainless-core/src/main/java/org/pgpainless/policy/Policy.java

@@ -24,6 +24,9 @@ import org.pgpainless.algorithm.HashAlgorithm;
 import org.pgpainless.algorithm.SymmetricKeyAlgorithm;
 import org.pgpainless.util.NotationRegistry;
 
+/**
+ * Policy class used to configure acceptable algorithm suites etc.
+ */
 public final class Policy {
 
     private static Policy INSTANCE;
@@ -40,6 +43,11 @@ public final class Policy {
     private Policy() {
     }
 
+    /**
+     * Return the singleton instance of PGPainless' policy.
+     *
+     * @return singleton instance
+     */
     public static Policy getInstance() {
         if (INSTANCE == null) {
             INSTANCE = new Policy();
@@ -47,10 +55,19 @@ public final class Policy {
         return INSTANCE;
     }
 
+    /**
+     * Return the hash algorithm policy for signatures.
+     * @return hash algorithm policy
+     */
     public HashAlgorithmPolicy getSignatureHashAlgorithmPolicy() {
         return signatureHashAlgorithmPolicy;
     }
 
+    /**
+     * Set a custom hash algorithm policy for signatures.
+     *
+     * @param policy custom policy
+     */
     public void setSignatureHashAlgorithmPolicy(HashAlgorithmPolicy policy) {
         if (policy == null) {
             throw new NullPointerException("Policy cannot be null.");
@@ -58,10 +75,22 @@ public final class Policy {
         this.signatureHashAlgorithmPolicy = policy;
     }
 
+    /**
+     * Return the hash algorithm policy for revocations.
+     * This policy is separate from {@link #getSignatureHashAlgorithmPolicy()}, as PGPainless by default uses a
+     * less strict policy when it comes to acceptable algorithms.
+     *
+     * @return revocation signature hash algorithm policy
+     */
     public HashAlgorithmPolicy getRevocationSignatureHashAlgorithmPolicy() {
         return revocationSignatureHashAlgorithmPolicy;
     }
 
+    /**
+     * Set a custom hash algorithm policy for revocations.
+     *
+     * @param policy custom policy
+     */
     public void setRevocationSignatureHashAlgorithmPolicy(HashAlgorithmPolicy policy) {
         if (policy == null) {
             throw new NullPointerException("Policy cannot be null.");
@@ -69,10 +98,21 @@ public final class Policy {
         this.revocationSignatureHashAlgorithmPolicy = policy;
     }
 
+    /**
+     * Return the symmetric encryption algorithm policy.
+     * This policy defines which symmetric algorithms are acceptable.
+     *
+     * @return symmetric algorithm policy
+     */
     public SymmetricKeyAlgorithmPolicy getSymmetricKeyAlgorithmPolicy() {
         return symmetricKeyAlgorithmPolicy;
     }
 
+    /**
+     * Set a custom symmetric encryption algorithm policy.
+     *
+     * @param policy custom policy
+     */
     public void setSymmetricKeyAlgorithmPolicy(SymmetricKeyAlgorithmPolicy policy) {
         if (policy == null) {
             throw new NullPointerException("Policy cannot be null.");
@@ -90,19 +130,42 @@ public final class Policy {
             this.acceptableSymmetricKeyAlgorithms = Collections.unmodifiableList(acceptableSymmetricKeyAlgorithms);
         }
 
+        /**
+         * Return the default symmetric key algorithm.
+         * This algorithm is used as a fallback when no consensus about symmetric algorithms can be reached.
+         *
+         * @return default symmetric encryption algorithm
+         */
         public SymmetricKeyAlgorithm getDefaultSymmetricKeyAlgorithm() {
             return defaultSymmetricKeyAlgorithm;
         }
 
+        /**
+         * Return true if the given symmetric encryption algorithm is acceptable by this policy.
+         *
+         * @param algorithm algorithm
+         * @return true if algorithm is acceptable, false otherwise
+         */
         public boolean isAcceptable(SymmetricKeyAlgorithm algorithm) {
             return acceptableSymmetricKeyAlgorithms.contains(algorithm);
         }
 
+        /**
+         * Return true if the given symmetric encryption algorithm is acceptable by this policy.
+         *
+         * @param algorithmId algorithm
+         * @return true if algorithm is acceptable, false otherwise
+         */
         public boolean isAcceptable(int algorithmId) {
             SymmetricKeyAlgorithm algorithm = SymmetricKeyAlgorithm.fromId(algorithmId);
             return isAcceptable(algorithm);
         }
 
+        /**
+         * The default symmetric encryption algorithm policy of PGPainless.
+         *
+         * @return default symmetric encryption algorithm policy
+         */
         public static SymmetricKeyAlgorithmPolicy defaultSymmetricKeyAlgorithmPolicy() {
             return new SymmetricKeyAlgorithmPolicy(SymmetricKeyAlgorithm.AES_256, Arrays.asList(
                     SymmetricKeyAlgorithm.IDEA,
@@ -129,19 +192,44 @@ public final class Policy {
             this.acceptableHashAlgorithms = Collections.unmodifiableList(acceptableHashAlgorithms);
         }
 
+        /**
+         * Return the default hash algorithm.
+         * This algorithm is used as a fallback when no consensus about hash algorithms can be reached.
+         *
+         * @return default hash algorithm
+         */
         public HashAlgorithm defaultHashAlgorithm() {
             return defaultHashAlgorithm;
         }
 
+        /**
+         * Return true if the the given hash algorithm is acceptable by this policy.
+         *
+         * @param hashAlgorithm hash algorithm
+         * @return true if the hash algorithm is acceptable, false otherwise
+         */
         public boolean isAcceptable(HashAlgorithm hashAlgorithm) {
             return acceptableHashAlgorithms.contains(hashAlgorithm);
         }
 
+        /**
+         * Return true if the the given hash algorithm is acceptable by this policy.
+         *
+         * @param algorithmId hash algorithm
+         * @return true if the hash algorithm is acceptable, false otherwise
+         */
         public boolean isAcceptable(int algorithmId) {
             HashAlgorithm algorithm = HashAlgorithm.fromId(algorithmId);
             return isAcceptable(algorithm);
         }
 
+        /**
+         * The default signature hash algorithm policy of PGPainless.
+         * Note that this policy is only used for non-revocation signatures.
+         * For revocation signatures {@link #defaultRevocationSignatureHashAlgorithmPolicy()} is used instead.
+         *
+         * @return default signature hash algorithm policy
+         */
         public static HashAlgorithmPolicy defaultSignatureAlgorithmPolicy() {
             return new HashAlgorithmPolicy(HashAlgorithm.SHA512, Arrays.asList(
                     HashAlgorithm.SHA224,
@@ -151,6 +239,11 @@ public final class Policy {
             ));
         }
 
+        /**
+         * The default revocation signature hash algorithm policy of PGPainless.
+         *
+         * @return default revocation signature hash algorithm policy
+         */
         public static HashAlgorithmPolicy defaultRevocationSignatureHashAlgorithmPolicy() {
             return new HashAlgorithmPolicy(HashAlgorithm.SHA512, Arrays.asList(
                     HashAlgorithm.RIPEMD160,
@@ -191,6 +284,13 @@ public final class Policy {
         Date getValidationDate();
     }
 
+    /**
+     * Return the {@link NotationRegistry} of PGPainless.
+     * The notation registry is used to decide, whether or not a Notation is known or not.
+     * Background: Critical unknown notations render signatures invalid.
+     *
+     * @return Notation registry
+     */
     public NotationRegistry getNotationRegistry() {
         return notationRegistry;
     }