added javadoc to private key

Author: DevCybran

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

@@ -40,6 +40,14 @@
 import net.i2p.crypto.eddsa.spec.EdDSAPrivateKeySpec;
 import net.i2p.crypto.eddsa.spec.EdDSAPublicKeySpec;
 
+/**
+ * A wrapper class which makes it easy to generate and use Ed25519 private keys.
+ * All methods are using java's {@link SecureRandom} PRNG, if a PRNG is needed.
+ * All sign methods are using the {@link HashCondenser} for efficiency.
+ * 
+ * @author DevCybran
+ *
+ */
 public class Ed25519PrivateKey implements Destroyable {
 	static final EdDSAParameterSpec P_SPEC = EdDSANamedCurveTable.getByName(EdDSANamedCurveTable.CURVE_ED25519_SHA512);
 	private static SecureRandom random = null;
@@ -70,11 +78,34 @@ static byte[] hash(byte[] data) throws NoSuchAlgorithmException {
 		return md.digest(data);
 	}
 
+	/**
+	 * Loads a private key from the specified file.
+	 * 
+	 * @param privateKeyFile the file to read the private key from
+	 * @param password the password which was passed to {@link #saveAsFile(File, char[])} upon saving the file
+	 * @return the read private key
+	 * @throws IOException if an IO error occurs while reading the file
+	 * @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
+	 */
 	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);
 		return loadFromString(key, password);
 	}
 
+	/**
+	 * Decodes a private key from the specified string.
+	 * 
+	 * @param privateKeyString A hexadecimal encoded representation of the key, generated by {@link #saveAsString(char[])}
+	 * @param password the password which was passed to {@link #saveAsString(char[])} upon generating the privateKeyString
+	 * @return the decoded private key
+	 * @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
+	 */
 	public static Ed25519PrivateKey loadFromString(String privateKeyString, char[] password) throws IllegalArgumentException, NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException {
 		if(privateKeyString.length() < (512+128+256+512)/8*2) throw new InvalidKeyException("the supplied key is not a valid private key"); // salt + iv + key + hash
 		byte[] salt, iv, encryptedKey;
@@ -110,6 +141,13 @@ public static Ed25519PrivateKey loadFromString(String privateKeyString, char[] p
 		}
 	}
 
+	/**
+	 * Generates a new private key.
+	 * {@link SecureRandom} is used as a source to seed this key.
+	 *  
+	 * 
+	 * @return A new private key
+	 */
 	public static Ed25519PrivateKey generate() {
 		KeyPairGenerator gen = new KeyPairGenerator();
 		try {
@@ -126,11 +164,33 @@ private Ed25519PrivateKey(EdDSAPrivateKey key, Ed25519PublicKey pubKey) {
 		this.pubKey = pubKey;
 	}
 
+	/**
+	 * Encrypts, encodes and saves this key to the specified file.
+	 * 
+	 * @see #saveAsString(char[])
+	 * @param privateKeyFile the file to save the private key to
+	 * @param password a password for encrypting the private key. The longer, the better.
+	 * @throws IllegalArgumentException if password is null
+	 * @throws IOException if an IO error occurs when writing the file
+	 * @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
+	 */
 	public void saveAsFile(File privateKeyFile, char[] password) throws IllegalArgumentException, IOException, NoSuchAlgorithmException, NoSuchPaddingException {
 		String key = this.saveAsString(password);
 		Files.write(privateKeyFile.toPath(), key.getBytes(StandardCharsets.UTF_8));
 	}
 
+	/**
+	 * Encodes this key as a hexadecimal String.
+	 * A password is used to encrypt this key. The password and a generated 512-bit long salt are fed to 1 million iterations of PBKDF2 with SHA-512 to generate a secret key.
+	 * The secret key is used to encrypt the private key using AES-256-CBC-PKCS5.
+	 * 
+	 * @param password a password for encrypting the private key. The longer, the better.
+	 * @return a hexadecimal encoded and encrypted representation of this private key
+	 * @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
+	 */
 	public String saveAsString(char[] password) throws IllegalArgumentException, NoSuchAlgorithmException, NoSuchPaddingException {
 		byte[] salt = new byte[512/8];
 		random().nextBytes(salt);
@@ -158,6 +218,11 @@ public String saveAsString(char[] password) throws IllegalArgumentException, NoS
 		}
 	}
 
+	/**
+	 * Creates (if necessary) and returns the public key for this private key.
+	 * 
+	 * @return the public key for this private key
+	 */
 	public Ed25519PublicKey derivePublicKey() {
 		if(this.pubKey==null) {
 			this.pubKey = new Ed25519PublicKey(new EdDSAPublicKey(new EdDSAPublicKeySpec(this.key.getA(), this.key.getParams())));
@@ -178,18 +243,55 @@ private String signLow(byte[] data) {
 		}
 	}
 
+	/**
+	 * Signs the given byte array.
+	 * {@link HashCondenser#compute(byte[])} with default settings is preprocessing the array before signing it.
+	 * 
+	 * @param data
+	 * @return a hexadecimal representation of the signature
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 */
 	public String sign(byte[] data) throws NoSuchAlgorithmException {
 		return signLow(HashCondenser.getInstance().compute(data));
 	}
 
+	/**
+	 * Signs the given String by converting it to bytes using the UTF-8 charset.
+	 * 
+	 * @see #sign(byte[])
+	 * @param data
+	 * @return a hexadecimal representation of the signature
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 */
 	public String sign(String data) throws NoSuchAlgorithmException {
 		return this.sign(data.getBytes(StandardCharsets.UTF_8));
 	}
 
+	/**
+	 * Signs all data which can be read from the given InputStream.
+	 * {@link HashCondenser#compute(byte[])} with default settings is preprocessing the stream before signing it, which will allow signing huge files.
+	 * 
+	 * @param source the data source
+	 * @param sourceSize the exact size of all data which will pass through the InputStream
+	 * @return a hexadecimal representation of the signature
+	 * @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
+	 */
 	public String sign(InputStream source, long sourceSize) throws IllegalArgumentException, NoSuchAlgorithmException, IOException {
 		return signLow(HashCondenser.getInstance().compute(source, sourceSize));
 	}
 
+	/**
+	 * Signs the content of the given file.
+	 * 
+	 * @see #sign(InputStream, long)
+	 * @param source
+	 * @return a hexadecimal representation of the signature
+	 * @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
+	 */
 	public String sign(File source) throws IOException, IllegalArgumentException, NoSuchAlgorithmException {
 		if(!source.isFile()) throw new FileNotFoundException(source.getAbsolutePath());
 		long fileSize = source.length();
@@ -198,10 +300,30 @@ public String sign(File source) throws IOException, IllegalArgumentException, No
 		}
 	}
 
+	/**
+	 * Signs the content of the given file and writes the signature to a file of the same name which has a ".sig" extension appended
+	 * Example: If you sign "MyFile.dat", the signature will be written to "MyFile.dat.sig"
+	 * 
+	 * @see #signToFile(File, File)
+	 * @param source
+	 * @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
+	 */
 	public void signToFile(File source) throws IOException, IllegalArgumentException, NoSuchAlgorithmException {
 		this.signToFile(source, new File(source, ".sig"));
 	}
 
+	/**
+	 * Signs the content of the given source file and writes the signature to the given signature file. 
+	 * 
+	 * @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 IllegalArgumentException if the file's size changes during computation
+	 * @throws NoSuchAlgorithmException if the hash algorithm is not present on this machine
+	 */
 	public void signToFile(File source, File signatureFile) throws IOException, IllegalArgumentException, NoSuchAlgorithmException {
 		String signature = this.sign(source);
 		Files.write(signatureFile.toPath(), signature.getBytes(StandardCharsets.UTF_8));