OTPUS

Cipher and tools for Node and Browser.
( 범용 암호 구현 및 환경)

Features

Ready to development using Web Crypto API.
- Isomorphic Web Crypto Name Reference(Node and Browser)
- You can use isomorphic reference name of 'webCrypto' from otpus.
- Node.js and Browser use different namespace.
WebCrypto API based general purpose async style encryption functions
- algorithm: AES-GCM, PBKDF2.
- encrypt() : support any type of data and key.
- random data size
- secret buffer pack ( meta buffer pack )
- decrypt() : return origin data type.( thanks to the special feature of MBP)
pure otpus implements
- xotp()
  - cipher function. based XOR and Pseudo OTP.
- encryptMessage()
  - simple but strong enough text message encryption.( Use stong passphrase)
  - recersive hash sum with salt.(like PBKDF2)
  - random data size.(hide real message size.)
  - HMAC support. (detect corrupted message.)
  - output: base64 string.(simple handy universal data format)
- decryptMessage()
  - receive base64 encoded message.
  - return plain text.
  - return undefined. ( for corrupted message)
include essential tools:
- otpus.sha256 : fast-sha256 : sync type hash, hmac.
- otpus.base64js : base64js : transcoder( buffer <-> UTF8 string )
- otpus.MBP : meta buffer pack : buffer packer
- otpus.Buffer : buffer : Node.js Buffer for browser.

otpus
Features
Table of Contents
Support
Usage
- Installing
- Loading module
Sync functions
Async functions using WebCrypto API
Examples
Online demo
License

Support

You can use modern ESM style or Legacy CJS, IIFE style both.

NodeJS:
- ESM: src/index.js , dist/otpus.mjs (bundled version.)
- CommonJS: dist/otpus.cjs
Browser:
- ESM: dist/otpus.esm.js
- IIFE: dist/otpus.min.js

Usage

Installing

npm i otpus

Browser

IIFE: Use script tag in html
the otpus.min.js file is inside dist folder.

<script src="../dist/otpus.min.js"></script>

You can use global CDN url. jsDeliver

<script src="https://cdn.jsdelivr.net/npm/otpus@1/dist/otpus.min.js"></script>

ES Module.

// don't forget the fullpath and file extension.
import {encryptMessage, decryptMessage, xotp } from "../path/otpus.esm.js"

Node.js

// Node ESM
import {encryptMessage, decryptMessage, xotp } from "otpus"

// Node CJS
// tip. if your pacakage.json using "module" type, you should use *.cjs file extension.
const {encryptMessage, decryptMessage, xotp } = require("otpus")

Sync functions

encryptMessage()

encryptMessage( data: String , key: String , nPower: Number = 15 ) : String

General purpose text message encryption.

data: Any UTF8 string.
key: Any UTF8 string.
- please use long passPhrase.
nPower:
- factor for recursive hash sum counter
- counter = 2 ** nPower
- counter is the result of exponentiation with number two as the base and integer nPower as the exponent.
- default value is 15. ( 2 ** 15 => 32768 times)
- You can use high number for strong encryption( but it takes more cpu time. )
- example( on my device)
  - mobile: 15 => spent about one second.
  - desktop: 17 => spent about one second.
output: encrytped and encoded base64 string.

decryptMessage()

decryptMessage( data: String, key: String ) : String

data: base64 ecoded string data
key: same with encryptMessage()
output: plain text

Encoded data

encryptMessage() return base64 string data.
If you need buffer data. use Buffer.from( base64Msg, 'base64' ) method.
or reverse command: buffer.toString('base64')

import {  encryptMessage, decryptMessage , Buffer } from 'otpus'
   
const plainText = 'this is sercret message'
const keyStr =  'this is secret key'

let encPack = encryptMessage( plainText, keyStr  )

// now encPack is encrypted & base64 encoded string.
/*  random size.
sX7SStdL/pF7umBBEJ7EKXuv7QYLflCe3vy9F+XEayQVfAVa3PoZ1UasXl
... SxbIm5Qb3dlciIsIjgiLDE0OF1dAE8=
*/

// if you need buffer data.
const encBuffer = Buffer.from( encPack , 'base64' )
// or reverse transformation ( from buffer to base64) also avaiable. 
const base64Pack = encBuffer.toString('base64')

let decMsg = decryptMessage(encPack ,keyStr )

if( decMsg  ){ // success
    // decMsg === 'this is sercret message'
}else{ 
    // decMsg === undefined  when fail. 
}

decryptMessage()

corruption check

When encryption process is fail for any reason. it will return undefined.
The encryption data store HMAC ( hash of message and key) info inside.
If calculated hmac is dismatched with stored hmac then return undefined.
Try this example. See the result when modify one byte of encryption data.

import {  encryptMessage, decryptMessage } from 'otpus'
   
const plainText = 'this is sercret message'
const keyStr =  'this is secret key'

let encPack = encryptMessage( plainText, keyStr  )

encPack = messageModification( encPack) //try make corrupted message.

let decMsg = decryptMessage(encPack ,keyStr )

if( decMsg  ){ // success
    console.log( 'decMsg:', decMsg )
}else{ // return undefined  when fail. 
    console.log('wrong data')
}

function messageModification( dataOrg ){
    const data = Buffer.from(dataOrg, 'base64')
    data[10] ^= 0x01; // modify one byte
    return data.toString('base64')
}

xotp()

This function is base cipher algorithm for otpus.( using XOR and Pseudo OTP.) You can make other encryption function( like encyptMessage) using this function.

xotp( data: Uint8Array, otpKey32Bytes: Uint8Array, otpSartIndex: Number = 0, shareDataBuffer: boolean = false ) : Uint8Array

Using encryption and decryption both.
data: Uint8Array only.
key: 32bytes Uint8Array only.
otpStartIndex: Number( 0 ~ 2**32-1.) default. 0
shareDataBuff: important
- false: return new buffer. default.
  - recommended for small size data.
- true: modify input data buffer.
  - recommended for the large data.

import { MBP, sha256, xotp  } from 'otpus'
   
const msgStr = 'aaaaaaaaaaaa'   
const pwStr = 'passphrase'    
  
let otpKey = sha256.hash( pwStr)  
// return 32bytes Uint8Array from string data.
let data = MBP.U8( msgStr )  
// MBP.U8(): parse any type of data into Uint8Array 

// use case 1. shareDataBuffer is false. 
let enc = xotp( data ,otpKey, 0 )  // false default.
let dec = xotp( enc , otpKey, 0 ) 

// use case 2. shareDataBuffer is true.
let encShare = xotp( data ,otpKey, 0 , true)  
// encShare & data is reference of same arrayBuffer.

// when shareOption is true.
// no return value needed. ( same below.)

// data before encryption.
xotp( data , otpKey, 0, true)
// now input data is changed.  
xotp( data , otpKey, 0 , true)
// now data is decrypted.

Async functions using WebCrypto API

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers. MDN SubtleCrypto
Node.js: The Web Cryptography API implementation has landed as an experimental feature in Node.js 15.0.0.( current status: Stability: 1 - Experimental.) Implementing the Web Cryptography API for Node.js Core

encrypt()

otpus's general purpose encryption implement using Web Crypto API.

features:

any type of data.
any type of key( passPhrase). string passphrase or buffer
result of decryption data will be same data type of origin data.
randomize data size. (to hide real message size)
Using WebCrypto API
- encryption algorithm: AES-GCM of Webcrypto API.
  - support message authentication
- key generation: PBKDF2 of WebCrypto API.
- salt, iv: from getRandomValues
data packaging: MBP(meta-buffer-pack)

  encrypt( data: any , passPhrase: any ,iterations : Number = 32768 ) bufferPack: Promise

async version of otpus.encrytMessage()
- available: promise chaining, async await.
input
- data {Stinrg | Uint8Array | Number | Object }
- passPhrase {Stinrg | Uint8Array | Number | Object }
- iterations {Number} iterations for PBKDF2 ( default 32768.)
returns
- Promise ( will return bufferPack when fulfilled )
- bufferPack is Node.js Buffer( subclass of Uint8Array)

decrypt()

  decrypt(data:Uint8Array , passPhrase: any  ) decodeData: Promise

input
- bufferPack(MBP pack) {Uint8Array}
- passPhrase {String | Uint8Array | any }
returns
- Promise ( will return decodedData when fulfilled )

import { encrypt, decrypt ,Buffer } from "otpus"

// async await style
const plainText = 'this is a secret message.'
const encPack = await encrypt(plainText, 'passPhrase', 10000)
const decodeMessage = await decrypt(encPack, 'passPhrase')

console.log('decrypted:', decodeMessage)

const plainData = Buffer.alloc(100 * 2 ** 20)
const encData = await encrypt(plainData, 'passPhrase', 10000)
const decData = await decrypt(encData, 'passPhrase')

const some = decData.slice(0, 16)
console.log('decrypted: some:', some)
console.log('decrypted: byteLength:', decData.byteLength)

const key = 'key'
const strData = 'hello world'


// promise chaining

// string data will return string data. 
encrypt(strData, key)
  .then(secretPack => {
    console.log('secretPack', secretPack.byteLength)
    return decrypt(secretPack, key)
  })
  .then(data => {
    console.log( 'typeof data:', typeof data)  // string 
    console.log('decoded string message: ', data)
  })


// Uint8Array data will return Uint8Array data.
const binaryData = Uint8Array.from([1, 2, 3, 4])
encrypt(binaryData, key)
  .then(secretPack => {
    console.log('secretPack', secretPack.byteLength)
    return decrypt(secretPack, key)
  })
  .then(data => {
    console.log('instanceof Uint8Array:', data instanceof Uint8Array )  //true
    console.log('decoded binary data: ', data)
  })

Error catch

For many reason encryption process could be fail. You should use try, catch statements.

//  await style
try{
    const secretPack = await encrypt('plain text','key')
    const decoded = await decrypt( secretPack,'key')
    console.log('decoded:', decoded)
}catch(error){
    console.log(error)
}

// Promise style
encrypt('plain text','key')
    .then( secretPack => decrypt(secretPack, 'key' ) )
    .then( decoded => console.log( decoded ))
    .catch( error=>{
        console.log(error)
    })

Handling buffer

encrypt() function generate a buffer( meta-buffer-pack). You can transform data format.

import{ encrypt, decrypt, MBP } from 'otpus'

const secretPack = await encrypt('data','key')

// secretPack is Buffer ( subclass of Uint8Array)
console.log( secretPack instanceof Uint8Array ) //  true 

// case. If you need base64 string data. 
const base64Pack = secretPack.toString('base64')
console.log( 'base64 data:', base64Pack ) 

/*
base64 data: F59Pyfq8EOSVSprdvbI2U+46JGtpcQ0sa3W2YtGRBxdJTdT41GY6a+FfBIvT4byChSu1KTGP1PJXewTidfeN1dgQh2IAe+eB2f/Df64kBXdr7HcvMFbawu2tOuUzUsonluKK25J5ilUtpuF2qszf9DEwMDAwW1siZW5jRGF0YSIsIkIiLDAsODRdLFsiaXYiLCJCIiw4NCwxMl0sWyJzYWx0IiwiQiIsOTYsMTZdLFsiaXRlcmF0aW9ucyIsIk4iLDExMiw1XV0AUw==
*/

// secretPack is meta-buffer-pack of MBP.
// You can use  MBP.unpack() to check public information like iv , salt.
cosnt secretObject = MBP.unpack( secretPack )
console.log( 'salt:', sercretObject.salt ) // 16 bytes. random values.

// salt: <Buffer 96 e2 8a db 92 79 8a 55 2d a6 e1 76 aa cc df f4>

Examples

NodeJs: please check test, testing directory.
Browser: example directory.

Online demo

https://remocons.github.io/otpus/example/

license

MIT

remocons/otpus

OTPUS

Features

Table of Contents

Support

Usage

Installing

Browser

Node.js

Sync functions

encryptMessage()

decryptMessage()

Encoded data

decryptMessage()

corruption check

xotp()

Async functions using WebCrypto API

encrypt()

decrypt()

Error catch

Handling buffer

Examples

Online demo

license