one-time-pad-es6/README.md

One-time-pad implementation using ES6. Encrypts both String and Array Buffer.

## One-time-pad using modern ES6 implementation [![Build Status](https://travis-ci.com/Randy341/one-time-pad-es6.svg?branch=master)](https://travis-ci.com/Randy341/one-time-pad-es6)
JavaScript Library to encrypt both Array Buffer and String using one-time-pad encryption 
technique.  
At the time of writing, this is the only one-time-pad implementation on NPM that supports encryption of both string and Array Buffer.  
Codebase prioritize on ease of use and ease of understanding.  

One-time-pad is cryptographically MOST SECURE encryption.  It is mathematically and theoretically unbreakable if used correctly.

The following rules must be followed to ensure One-Time-Pad is secure: 
* The key is at least as long as the message or data that must be encrypted.
* The key is truly random (not generated by a simple computer function or such)
* Key and plaintext are calculated modulo 10 (digits), modulo 26 (letters) or modulo 2 (binary)
* Each key is used only once, and both sender and receiver must destroy their key after use.
* There should only be two copies of the key: one for the sender and one for the receiver (some exceptions exist for multiple receivers)


## Node.js (Install)  
Requirements:
- Node.js (version 8 or above.  Need ES6 async/await and typed array)
- NPM
```bash
npm install one-time-pad-es6
````

## Usage
```javascript
    const otp = require("one-time-pad-es6");
    const fs = require("fs");
    
    //Encrypt String
    const HarryPotterBook1 = fs.readFileSync("./Harry_Potter_Philosopher_Stone", {encoding: "utf8"})
    const Agent007_otp = new otp(HarryPotterBook1);
    const ciphertext = await Agent007_otp.encryptString("I have the Golden Eye!", offset=100,step=5)
    
    //NOTE: - offset is the starting location of the key for padding
    //      - step is the number of character(s) in the key to skip for every plaintext character get padded

    //Decrypt String
    const plaintext = await Agent007_otp.decryptString(ciphertext, offset=100, step=5);
    
    //Pad Array Buffer
    const data = JSON.stringify({name: "Rick Sanchez", job: "Mad Scientist", weapon: "Portal Gun"});
    const buffer = new ArrayBuffer(data.length * 2);
    const view = new Uint16Array(buffer);
    data.split("").forEach((char, index) => { view[index] = char.charCodeAt(0); });
    const cipher = await Agent007_otp.pad(buffer, offset=3, step=2);
    //cipher is of type ArrayBuffer
```

## Q&A
#### Q: Why this library needs node version 8 or above?
A: Specifically, this library requires async/await and typed array feature from ES2015.  Any node or browser version supporting
these two will suffice.  Async/await is much less important as it only served as wrapper for 
async call.  You can fork your own on github and rewrite the async/await portion.  
However, the typed array feature is a must as typed array is used heavily.  

#### Q: Why not just use one of more established library?
A: As of the writing of this library, I can't find One-Time-Pad implementation on NPM that uses modern ES2015 

#### Q: Your library is garbage!  I don't like it!
A: Then you open PR and improve it! Or don't use it! Nobody is begging you here...   
Look, I get it.  This library isn't super optimized.  It is optimized enough for
my project, and I published this on NPM so others may take advantage of my works.  
I know some people (like those working in G-Company) 
love writing highly optimized but long and cryptic codes without documentation.   
I prefer codes that can be easily 
and quickly understood by teammate of different experience levels so they can contribute quickly.