From 6ad6974452be3a338c429678c69738c2870553eb Mon Sep 17 00:00:00 2001
From: zzz <zzz@mail.i2p>
Date: Sun, 24 Aug 2014 23:11:56 +0000
Subject: [PATCH] javadoc warnings about EdDSA raw sigs

---
 core/java/src/net/i2p/crypto/DSAEngine.java | 37 +++++++++++++++++----
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/core/java/src/net/i2p/crypto/DSAEngine.java b/core/java/src/net/i2p/crypto/DSAEngine.java
index 7a7dfa104..8b0383b37 100644
--- a/core/java/src/net/i2p/crypto/DSAEngine.java
+++ b/core/java/src/net/i2p/crypto/DSAEngine.java
@@ -52,8 +52,8 @@ import net.i2p.util.Log;
 import net.i2p.util.NativeBigInteger;
 
 /**
- *  Sign and verify using DSA-SHA1.
- *  Also contains methods to sign and verify using a SHA-256 Hash, used by Syndie only.
+ *  Sign and verify using DSA-SHA1 and other signature algorithms.
+ *  Also contains methods to sign and verify using a SHA-256 Hash.
  *
  *  The primary implementation is code from TheCryto.
  *  As of 0.8.7, also included is an alternate implementation using java.security libraries, which
@@ -68,6 +68,8 @@ import net.i2p.util.NativeBigInteger;
  *  Signature, SigningPublicKey, and SigningPrivateKey. See Javadocs for individual
  *  methods for the supported types. Methods encountering an unsupported type
  *  will throw an IllegalArgumentException.
+ *
+ *  EdDSA support added in 0.9.15
  */
 public class DSAEngine {
     private final Log _log;
@@ -86,7 +88,7 @@ public class DSAEngine {
     }
 
     /**
-     *  Verify using DSA-SHA1 or ECDSA.
+     *  Verify using any sig type.
      *  Uses TheCrypto code for DSA-SHA1 unless configured to use the java.security libraries.
      */
     public boolean verifySignature(Signature signature, byte signedData[], SigningPublicKey verifyingKey) {
@@ -158,6 +160,8 @@ public class DSAEngine {
     /**
      *  Generic signature type.
      *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @param hash SHA1Hash, Hash, Hash384, or Hash512
      *  @since 0.9.9
      */
@@ -184,6 +188,8 @@ public class DSAEngine {
      *  If you have a Java pubkey, use this, so you don't lose the key parameters,
      *  which may be different than the ones defined in SigType.
      *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @param hash SHA1Hash, Hash, Hash384, or Hash512
      *  @param pubKey Java key
      *  @since 0.9.9
@@ -332,6 +338,8 @@ public class DSAEngine {
     /**
      *  Generic signature type.
      *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @param hash SHA1Hash, Hash, Hash384, or Hash512
      *  @return null on error
      *  @since 0.9.9
@@ -357,6 +365,8 @@ public class DSAEngine {
      *  If you have a Java privkey, use this, so you don't lose the key parameters,
      *  which may be different than the ones defined in SigType.
      *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @param hash SHA1Hash, Hash, Hash384, or Hash512
      *  @param privKey Java key
      *  @param type returns a Signature of this type
@@ -492,7 +502,8 @@ public class DSAEngine {
     }
 
     /**
-     *  Generic verify DSA_SHA1, ECDSA, or RSA
+     *  Generic verify any type.
+     *
      *  @throws GeneralSecurityException if algorithm unvailable or on other errors
      *  @since 0.9.9 added off/len 0.9.12
      */
@@ -518,6 +529,9 @@ public class DSAEngine {
 
     /**
      *  Generic raw verify any type
+     *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @throws GeneralSecurityException if algorithm unvailable or on other errors
      *  @since 0.9.9
      */
@@ -536,6 +550,8 @@ public class DSAEngine {
      *  If you have a Java pubkey, use this, so you don't lose the key parameters,
      *  which may be different than the ones defined in SigType.
      *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @throws GeneralSecurityException if algorithm unvailable or on other errors
      *  @param verifyingKey Java key
      *  @since 0.9.9
@@ -579,7 +595,8 @@ public class DSAEngine {
     }
 
     /**
-     *  Generic sign DSA_SHA1, ECDSA, or RSA
+     *  Generic sign any type.
+     *
      *  @throws GeneralSecurityException if algorithm unvailable or on other errors
      *  @since 0.9.9 added off/len 0.9.12
      */
@@ -601,7 +618,10 @@ public class DSAEngine {
     }
 
     /**
-     *  Generic raw verify any type
+     *  Generic raw sign any type.
+     *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @param hash SHA1Hash, Hash, Hash384, or Hash512
      *  @throws GeneralSecurityException if algorithm unvailable or on other errors
      *  @since 0.9.9
@@ -614,7 +634,10 @@ public class DSAEngine {
     }
 
     /**
-     *  Generic raw verify any type
+     *  Generic raw sign any type.
+     *
+     *  Warning, nonstandard for EdDSA, double-hashes, not recommended.
+     *
      *  @param hash SHA1Hash, Hash, Hash384, or Hash512
      *  @param type returns a Signature of this type
      *  @throws GeneralSecurityException if algorithm unvailable or on other errors