README touchups

README.md

@@ -2,7 +2,11 @@
 
 The official distributions of [Java](https://openjdk.java.net/) include cryptographic functions in a framework called the [Java Cryptography Extension (JCE)](https://en.wikipedia.org/wiki/Java_Cryptography_Extension).  JCE provides the API layer and corresponding implementations of cryptographic functions like key generation, key storage/retrieval, and cipher encryption/decryption.  The JCE API supports those basic functions along with Java I/O based capabilities using `InputStream` and `OutputStream` implementations.
 
-Since the introduction of JCE, Java has introduced the ["Non-blocking I/O" (NIO)](https://en.wikipedia.org/wiki/Non-blocking_I/O_%28Java%29) framework as a complement to the Java (blocking) I/O framework.  It has huge advantages in performance for many applications.  For instance, it is recommended that Apache Tomcat configurations use NIO connectors for clients due to its performance advantages.
+JCE is part of the [Java Cryptography Architecture (JCA)](https://en.wikipedia.org/wiki/Java_Cryptography_Architecture), which has been around even longer.  It is also in scope of this library.  In addition to the JCE cryptographic functions, JCA includes hashing functions.  It has the same reliance on Java I/O based capabilities.
+
+Since the introduction of JCA/JCE, Java has introduced the ["New I/O" (NIO)](https://en.wikipedia.org/wiki/Non-blocking_I/O_%28Java%29) framework as a complement to the Java (blocking) I/O (BIO) framework.  NIO originally meant "Non-blocking I/O", but it also provides blocking as well, so "New I/O" is a better representation.
+
+Non-blocking I/O has huge advantages in performance over blocking I/O for many applications.  For instance, it is recommended that Apache Tomcat configurations use NIO connectors for clients due to its performance advantages.  Since NIO also supports blocking mode, it effectively depreciated the legacy I/O (but not officially).
 
 ## Using
 
@@ -27,8 +31,12 @@ To use this library, you must include it as a dependency to your project.  An ex
 
 ### Developing
 
-There are many different algorithms that are available for encrypting and decrypting content.  This project does not care about those details.  It does not care about key generation, storage, or retrieval.  It only cares about the streaming of content through a cipher.  The default set of algorithms come from the JVM default JCE provider.  You can include other JCE providers that provide the same, similar, and completely new algorithms.  Some of those providers interface directly with hardware or the network for enhanced security or performance.
+There are many different algorithms that are available for encrypting, decrypting, and hashing content.  This project does not care about those details.  It does not care about key generation, storage, or retrieval.  It only cares about the streaming of content through a cipher or digest.  The most primal I/O operations.  There is a default set of algorithms come from the JVM default JCA/JCE providers.  You can include other JCA/JCE providers to expand the supported algorithms, cipher modes, and padding options.  Some of those providers interface directly with hardware or the network for enhanced security or performance.
 
-A [cipher](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/javax/crypto/Cipher.html) is defined by an algorithm, cipher mode, and padding.  These are married together into a single parameter in JCE called a *transformation*.  That same parameter is used in this library.  You will also need an appropriate key and your content.
+A [cipher](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/javax/crypto/Cipher.html) is defined by an algorithm, cipher mode, and padding.  These are married together into a single parameter in JCE called a *transformation*.  That same parameter is used in this library.  You will also need an appropriate key and your content.  In Java 8 and earlier, you will need another provider or an extension to the default provider to support high stength crypto.  You can [download the Oracle Java extension here](https://www.oracle.com/java/technologies/javase-jce-all-downloads.html).
+
+A [digest](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/security/MessageDigest.html) is defined by a just an algorithm name.
+
+You can find a list of supported cipher transformations and digest algorithms in the official Java documentation linked in the paragraphs above.
 
 You can find [sample code for common algorithms in the source](/inteligr8/nio-crypto/src/stable/src/test/java/com/inteligr8/nio/CommonSamples.java).

src/test/java/com/inteligr8/nio/CommonSamples.java

@@ -1,9 +1,15 @@
 package com.inteligr8.nio;
 
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.Reader;
 import java.io.Writer;
 import java.nio.channels.Channels;
-import java.nio.channels.Pipe;
+import java.nio.channels.FileChannel;
 import java.nio.charset.Charset;
+import java.nio.file.StandardOpenOption;
+import java.security.KeyPair;
+import java.security.KeyPairGenerator;
 
 import javax.crypto.KeyGenerator;
 import javax.crypto.SecretKey;
@@ -20,11 +26,72 @@ public class CommonSamples {
 		keygen.init(keysize);
 		SecretKey key = keygen.generateKey();
 		
-		// pipe data
-		Pipe pipe = Pipe.open();
-		IVEncryptingWritableByteChannel cryptochannel = new IVEncryptingWritableByteChannel(pipe.sink(), key, "AES/CBC/NoPadding");
-		Writer writer = Channels.newWriter(cryptochannel, Charset.defaultCharset());
-		writer.append("some plain text to encrypt");
+		// prepare file (channel) to receive encrypted conten
+		FileChannel fchannel = FileChannel.open(new File("target/test.aes").toPath(),
+				StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.WRITE);
+		try {
+			// wrap channel with encrypting channel and convenient string writer
+			IVEncryptingWritableByteChannel cryptochannel = new IVEncryptingWritableByteChannel(fchannel, key, "AES/CBC/PKCS5Padding");
+			Writer writer = Channels.newWriter(cryptochannel, Charset.defaultCharset());
+			try {
+				writer.append("some plain text to encrypt");
+			} finally {
+				writer.close();
+			}
+		} finally {
+			fchannel.close();
+		}
+		
+		// prepare file (channel) to deliver encrypted content
+		fchannel = FileChannel.open(new File("target/test.aes").toPath(), StandardOpenOption.READ);
+		try {
+			// wrap channel with decrypting channel and convenient string reader
+			IVDecryptingReadableByteChannel cryptochannel = new IVDecryptingReadableByteChannel(fchannel, key, "AES/CBC/PKCS5Padding");
+			Reader reader = Channels.newReader(cryptochannel, Charset.defaultCharset());
+			
+			System.out.println(new BufferedReader(reader).readLine());
+		} finally {
+			fchannel.close();
+		}
+	}
+	
+	@Test
+	public void rsa() throws Exception {
+		// generate random key using JCE
+		int keysize = 4096;
+		KeyPairGenerator keygen = KeyPairGenerator.getInstance("RSA");
+		keygen.initialize(keysize);
+		KeyPair keys = keygen.generateKeyPair();
+		
+		// prepare file (channel) to receive encrypted content
+		FileChannel fchannel = FileChannel.open(new File("target/test.rsa").toPath(),
+				StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.WRITE);
+		try {
+			// wrap channel with encrypting channel and convenient string writer
+			EncryptingCipherParameters ecparams = new EncryptingCipherParameters(keys.getPrivate(), "RSA/ECB/PKCS1Padding");
+			EncryptingWritableByteChannel cryptochannel = new EncryptingWritableByteChannel(fchannel, ecparams);
+			Writer writer = Channels.newWriter(cryptochannel, Charset.defaultCharset());
+			try {
+				writer.append("some plain text to encrypt");
+			} finally {
+				writer.close();
+			}
+		} finally {
+			fchannel.close();
+		}
+		
+		// prepare file (channel) to deliver encrypted content
+		fchannel = FileChannel.open(new File("target/test.rsa").toPath(), StandardOpenOption.READ);
+		try {
+			// wrap channel with decrypting channel and convenient string reader
+			DecryptingCipherParameters edparams = new DecryptingCipherParameters(keys.getPublic(), "RSA/ECB/PKCS1Padding");
+			DecryptingReadableByteChannel cryptochannel = new DecryptingReadableByteChannel(fchannel, edparams);
+			Reader reader = Channels.newReader(cryptochannel, Charset.defaultCharset());
+			
+			System.out.println(new BufferedReader(reader).readLine());
+		} finally {
+			fchannel.close();
+		}
 	}
 
 }