updated javadoc

Author: DevCybran

src/de/ntcomputer/crypto/eddsa/Ed25519PrivateKey.java

@@ -88,7 +88,7 @@ static byte[] hash(byte[] data) throws NoSuchAlgorithmException {
 	 * @throws IllegalArgumentException if password is null
 	 * @throws NoSuchAlgorithmException if either of the encryption algorithms is not present on this machine
 	 * @throws NoSuchPaddingException if the PKCS5 padding is not present on this machine
-	 * @throws InvalidKeyException if the passed privatKeyString has an invalid format
+	 * @throws InvalidKeyException if the key file has an invalid format
 	 */
 	public static Ed25519PrivateKey loadFromFile(File privateKeyFile, char[] password) throws IllegalArgumentException, IOException, NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException {
 		String key = new String(Files.readAllBytes(privateKeyFile.toPath()), StandardCharsets.UTF_8);
@@ -306,7 +306,7 @@ public String sign(File source) throws IOException, IllegalArgumentException, No
 	 * 
 	 * @see #signToFile(File, File)
 	 * @param source
-	 * @throws IOException if an IO error occurs while reading the file
+	 * @throws IOException if an IO error occurs while reading or writing a file
 	 * @throws IllegalArgumentException if the file's size changes during computation
 	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
 	 */
@@ -320,7 +320,7 @@ public void signToFile(File source) throws IOException, IllegalArgumentException
 	 * @see #sign(File)
 	 * @param source
 	 * @param signatureFile the file to write the signature to
-	 * @throws IOException if an IO error occurs while reading the file
+	 * @throws IOException if an IO error occurs while reading or writing a file
 	 * @throws IllegalArgumentException if the file's size changes during computation
 	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
 	 */

src/de/ntcomputer/crypto/eddsa/Ed25519PublicKey.java

@@ -17,14 +17,40 @@
 import net.i2p.crypto.eddsa.Utils;
 import net.i2p.crypto.eddsa.spec.EdDSAPublicKeySpec;
 
+/**
+ * A wrapper class which makes it easy to use Ed25519 public keys.
+ * All verify methods are using the {@link HashCondenser} for efficiency.
+ * Obtain an instance by loading a key file or using {@link Ed25519PrivateKey#derivePublicKey()}
+ * 
+ * @author DevCybran
+ *
+ */
 public class Ed25519PublicKey {
 	private final EdDSAPublicKey key;
 
+	/**
+	 * Loads a private key from the specified file.
+	 * 
+	 * @see #loadFromString(String)
+	 * @param publicKeyFile the file to read the private key from
+	 * @return the read private key
+	 * @throws IOException if an IO error occurs while reading the file
+	 * @throws NoSuchAlgorithmException if SHA-512 is not present on this machine
+	 * @throws InvalidKeyException if the key file has an invalid format
+	 */
 	public static Ed25519PublicKey loadFromFile(File publicKeyFile) throws IOException, NoSuchAlgorithmException, InvalidKeyException {
 		String key = new String(Files.readAllBytes(publicKeyFile.toPath()), StandardCharsets.UTF_8);
 		return loadFromString(key);
 	}
 
+	/**
+	 * Decodes a public key from the specified string.
+	 * 
+	 * @param publicKeyString A hexadecimal encoded representation of the key, generated by {@link #saveAsString()}
+	 * @return the decoded public key
+	 * @throws InvalidKeyException if the passed publicKeyString has an invalid format
+	 * @throws NoSuchAlgorithmException if SHA-512 is not present on this machine
+	 */
 	public static Ed25519PublicKey loadFromString(String publicKeyString) throws InvalidKeyException, NoSuchAlgorithmException {
 		if(publicKeyString.length() != (256+512)/8*2) throw new InvalidKeyException("the supplied key is not a valid public key"); // key + hash
 		byte[] publicKey, publicKeyHashStored, publicKeyHash;
@@ -43,11 +69,25 @@ public static Ed25519PublicKey loadFromString(String publicKeyString) throws Inv
 		this.key = key;
 	}
 
+	/**
+	 * Encodes and saves this key to the specified file.
+	 * 
+	 * @see #saveAsString()
+	 * @param publicKeyFile the file to save the public key to
+	 * @throws IOException if an IO error occurs when writing the file
+	 * @throws NoSuchAlgorithmException if SHA-512 is not present on this machine
+	 */
 	public void saveAsFile(File publicKeyFile) throws IOException, NoSuchAlgorithmException {
 		String key = this.saveAsString();
 		Files.write(publicKeyFile.toPath(), key.getBytes(StandardCharsets.UTF_8));
 	}
 
+	/**
+	 * Encodes this key as a hexadecimal String.
+	 * 
+	 * @return a hexadecimal encoded representation of this public key
+	 * @throws NoSuchAlgorithmException if SHA-512 is not present on this machine
+	 */
 	public String saveAsString() throws NoSuchAlgorithmException {
 		byte[] publicKey = this.key.getAbyte();
 		if(publicKey.length!=256/8) throw new RuntimeException(new InvalidKeyException("unexpected public key length"));
@@ -72,18 +112,63 @@ private boolean verifyLow(byte[] data, String signature) throws SignatureExcepti
 		}
 	}
 
+	/**
+	 * Verifies the signature of the given byte array.
+	 * {@link HashCondenser#compute(byte[])} with default settings is preprocessing the array before verifying its signature.
+	 * 
+	 * @param data
+	 * @param signature a hexadecimal representation of the signature (generated by {@link Ed25519PrivateKey#sign(byte[])}
+	 * @return true if the signature is correct. False otherwise.
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 * @throws SignatureException if the given signature has an invalid format
+	 */
 	public boolean verify(byte[] data, String signature) throws NoSuchAlgorithmException, SignatureException {
 		return this.verifyLow(HashCondenser.getInstance().compute(data), signature);
 	}
 
+	/**
+	 * Verifies the signature of the given String by converting it to bytes using the UTF-8 charset.
+	 * 
+	 * @see #verify(byte[], String)
+	 * @param data
+	 * @param signature a hexadecimal representation of the signature (generated by {@link Ed25519PrivateKey#sign(String)}
+	 * @return true if the signature is correct. False otherwise.
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 * @throws SignatureException if the given signature has an invalid format
+	 */
 	public boolean verify(String data, String signature) throws NoSuchAlgorithmException, SignatureException {
 		return this.verify(data.getBytes(StandardCharsets.UTF_8), signature);
 	}
 
+	/**
+	 * Verifies that the signature for all data which can be read from the given InputStream is correct.
+	 * {@link HashCondenser#compute(byte[])} with default settings is preprocessing the stream before verifying its signature, which will allow processing huge files.
+	 * 
+	 * @param source the data source
+	 * @param sourceSize the exact size of all data which will pass through the InputStream
+	 * @param signature a hexadecimal representation of the signature (generated by {@link Ed25519PrivateKey#sign(InputStream, long)}
+	 * @return true if the signature is correct. False otherwise.
+	 * @throws IllegalArgumentException if sourceSize is not the correct size
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 * @throws IOException if an IO error occurs while reading the stream
+	 * @throws SignatureException if the given signature has an invalid format
+	 */
 	public boolean verify(InputStream source, long sourceSize, String signature) throws IllegalArgumentException, NoSuchAlgorithmException, IOException, SignatureException {
 		return this.verifyLow(HashCondenser.getInstance().compute(source, sourceSize), signature);
 	}
 
+	/**
+	 * Verifies the signature of the content of the given file.
+	 * 
+	 * @see #verify(InputStream, long, String)
+	 * @param source
+	 * @param signature a hexadecimal representation of the signature (generated by {@link Ed25519PrivateKey#sign(File)}
+	 * @return true if the signature is correct. False otherwise.
+	 * @throws IOException if an IO error occurs while reading the file
+	 * @throws IllegalArgumentException if the file's size changes during computation
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 * @throws SignatureException if the given signature has an invalid format
+	 */
 	public boolean verify(File source, String signature) throws IOException, IllegalArgumentException, NoSuchAlgorithmException, SignatureException {
 		if(!source.isFile()) throw new FileNotFoundException(source.getAbsolutePath());
 		long fileSize = source.length();
@@ -92,10 +177,34 @@ public boolean verify(File source, String signature) throws IOException, Illegal
 		}
 	}
 
+	/**
+	 * Verifies the content of the given file against its signature, stored in a file of the same name which has a ".sig" extension appended
+	 * Example: If you verify "MyFile.dat", the signature will be read from "MyFile.dat.sig"
+	 * 
+	 * @see #verifyFromFile(File, File)
+	 * @param source
+	 * @return true if the signature is correct. False otherwise.
+	 * @throws IOException if an IO error occurs while reading a file
+	 * @throws IllegalArgumentException if the file's size changes during computation
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 * @throws SignatureException if the signature in the .sig file has an invalid format
+	 */
 	public boolean verifyFromFile(File source) throws IOException, IllegalArgumentException, NoSuchAlgorithmException, SignatureException {
 		return this.verifyFromFile(source, new File(source, ".sig"));
 	}
 
+	/**
+	 * Verifies the content of the given source file against the signature in the given signature file.
+	 * 
+	 * @see #verify(File, String)
+	 * @param source
+	 * @param signatureFile the file to write the signature to
+	 * @return true if the signature is correct. False otherwise.
+	 * @throws IOException if an IO error occurs while reading a file
+	 * @throws IllegalArgumentException if the file's size changes during computation
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 * @throws SignatureException if the signature in the signature file has an invalid format
+	 */
 	public boolean verifyFromFile(File source, File signatureFile) throws IOException, IllegalArgumentException, NoSuchAlgorithmException, SignatureException {
 		String signature = new String(Files.readAllBytes(signatureFile.toPath()), StandardCharsets.UTF_8);
 		return this.verify(source, signature);