base64

Convert, compress and share text in base64 format, for web, mobile, and web applications. A JavaScript library for moving data around in a compact and compatible format. Includes a few handy helper functions.

Basic usage

Function	Description
Base64.write	Compress and convert text to base64
Base64.read	Decompress and revert base64 data back to text

Here is an example to get started:

var str = "my string of text";
var data = Base64.write(str);
//do something cool with data like saving it to localStorage or as a cookie
var str2 = Base64.read(data);

Sharing (is caring)

Function	Description
Base64.share	Share text as a JSON object with someone if you know their public key (as generated by base64.js)

Base64.share returns a JSON Object that can be shared with (an)other individual(s), or maybe you just want to share it with yourself, but on another device. Sharing applies a basic level of obfuscation to the base64 algorithm, by mixing in a key to the base64 conversion. This in no way should be considered to be encryption. The algorithm included in this package is haphazard at best and should not be trusted for any kind of sensitive data. Sharing uses a form of DH key exchange, but with the added functionality to share with multiple people at the same time. The key used to obfuscate the data is random and generated on the fly, so it will be different every time the share function is used. This random key is retreived using any one of the individuals who have been authorized to access the data's private keys, including the person who shared it.

share Parameters

Base64.share accepts 4 parameters: str, myPrivateKey, theirPublicKeys, and expires.

Parameter	Accepts	Description
str	String	is any text of type String that you would like to share with another individual.
myPrivateKey	String	can be anything you want it to be. Length not limited.
theirPublicKeys	Array	accepts an Array of publicKeys. publicKeys must be generated by calling Base64.createPublicKey, which accepts one parameter, a privateKey... which you likely don't know. Try asking really nice, or just arrange for a way to get theirPublicKeys.
expires	Number	accepts a Number in months until data is no longer valid (optional, can be easily bypassed if source code is known).

Sharing example

Bob and Anne want to share a database using a web app, and their own cloud solution.

var bobsPrivateKey = "whatWasMyKeyAgainIForgotItAlready",
  bobsPublicKey = Base64.createPublicKey(bobsPrivateKey);

var annesPrivateKey = "notTellingYouYoudBlabItAllOverTheCountry",
  annesPublicKey = Base64.createPublicKey(annesPrivateKey);

annesPublicKey looks like this:

251573354827053796259786446259
420716479426576557751869240890
583920900476252414535944950341
285306449636737380460864489372
984749791973331359102306223033
381167865088683119759760379947
177869447254412983729023967354
072359677541752574583929875463
184150782438573348579489894336
263475563711134591896530098397

Bob and Anne post their public keys on the cloud and download each other's public keys. Now they can begin sharing data.

var bobsdatabase = {a:['bunch', ['of', 'information']]};
var stringified = JSON.stringify(bobsdatabase); //in this case since we are sharing an object we need to stringify it
var expiresInMonths = 12;
var bobsShareableObj = Base64.share(stringified, bobsPrivateKey, [annesPublicKey], expiresInMonths);

bobsShareableObj looks something like this:

{
  "Version":1,
  "Expires":1538935195771,
  "Compressed":true,
  "Data":"dshjYh9clcnx7Y7ER7VB6ZHz3qE2quxb3tzz3n3E3Tza1QCBhv8Q0snHgC9X0np1NR",
  "PublicKey":"77188296934259847669163308489209470815671463565895356436076803547451605665533323690542981020534297711854732331844583209708636365911200893662032104671327017004482047586715717137000917197108417129883127822781859317013260983435085346317484209555712066772559226831417764532853735362749793114476480776850",
  "UserKeys":"bAGw2giAmASAeDMCqAbAbAOQFYEUDyAHAhgBZQDGOA7AKIBOAnAXAKYDiArAI4sBMALgCwBGAQQTEEGNAHUAZgGsA0gEkFANwB2FVQEsZAKSyaYABUEyyxGADFBAGQCavWykETuEvLYoEAKgE9VAV05VKwARBENbAHoyNlsAWxw4wTgLAhh+SIBeORQfMgBGTN4EAGFVfIAOSIB3KQUADQAtawAGLyYAZVsfXhlMmBw4BTgANQUQgGoqLGqWnxkAZyoOhQWpNAUafI6Kbmt+fwZOfMj3CglMpgAlHwBzCGsStBwQvoqaCQICMixubhRIigQmQGOkMBZblcRigLCgFB0pHIrg0pAB7PaCXhIOIQNCCDpXMA6CASZQSJh4ThQeoQTSNGAgAA04FRjSocUa/l4ygUDA6eDAAC8KIYYDRVFBBD4OpFIi0oIYcAwLFAmOTBFQWMpNCw5NR6n9MsQAEIdEo0HQAWTiIiYKG4xqYWC4+VRBD1MhoUBoPjQ1QYKGNLEyjWUnEFguqmgYJU0qkinBK3uUEG4YGqOBgFRaIyo3A6LRgLUyWCuCBQDC8bgoqLiZFuUjAcRoCkycAqKDgWAWnDwclRaCwNGsNHqghKkTkDBwPgsDEy1VJmjIcDg/gUKH8GGqV1u/AIEAoFk4Cls1ndEkaaAqI38C2U1SohjIV1sBEBxsMUBY/BKKBoYqiFccjVF4mj+CgUAtNYkRIIYLCRHA+TED43AQNUqIwMoIAALpAAAA=",
  "Signature":"6a7dc83efc55d83577c0348f2b27297fcd6be6d437832fbaaf6dfd2a19596eec"
 }

Reading a shared JSON Object

Function	Description
Base64.readShared	Read a shared JSON object

Base64.readShared returns a JSON Object as well.

readShared Parameters

Accepts 2 parameters: obj and myPrivateKey.

Parameter Name	Accepts	Description
obj	Object	is the JSON Object created by Base64.share.
myPrivateKey	String	is one of the private keys corresponding to a public key used in generating the JSON Object (see theirPublicKeys above).

Sharing example continued...

Bob and Anne have shared their pubic keys with each other and Bob sent Anne a JSON file containing his database. Now Anne wants to read it.

var downloadedDatabase = Base64.readShared(bobsShareableObj, annesPrivateKey);

downloadedDatabase looks like this:

{
  "type":"results",
  "message":"success",
  "data":"{\"a\":[\"bunch\",[\"of\",\"information\"]]}",
  "hmac":"6a7dc83efc55d83577c0348f2b27297fcd6be6d437832fbaaf6dfd2a19596eec"
}

Then obviously you need to extract the actual data from the JSON object

if(downloadedDatabase.type === "results" && downloadedDatabase.message === "success"){
  downloadedDatabase = JSON.parse(downloadedDatabase.data);
}
else if(downloadedDatabase.type === "error"){
  alert(downloadedDatabase.message);
}

A note on compression

Compression used is LZ compression. In the example above, converting to base64 and compressing actually lengthened the data. You will only start to see big savings if the original data is over 1kb for example. Results will vary based on how compressible the original data actually is.

Other functions

Base64 contains a few additional helper functions that are also accessable.

Helper Functions	Description
Base64.atob	Generic atob (A to B) function. Decodes (system created, non compressed) base64 encoded text
Base64.btoa	Generic btoa (B to A) function. Encodes text to utf-8 then to base64 encoding (without compressing it)
Base64.write_and_verify	Same as Base64.write, but does some error checking as well
Base64.hash	Salted SHA256 hash
Base64.number_hash	Converts any string to a positive integer of the requiredLength
Base64.rand	Generate a random number up to 300 digits long
Base64.hmac	Generate a Hashed Message Authentication Code
Base64.createPublicKey	Creates a Diffie Hellman Merkle public key from any string (usually from a secret password)
Base64.createUserKey	Create a secondary secret key to share with someone if you know their public key.
Base64.createUserKey_and_verify	Same as Base64.createUserKey, but needs the user's private key to verify
Base64.readUserKey	Read a secret key (userKey) that was shared with you, using your own secret key and the person who shared it with you's public key