Skip to content

Convert, compress and share text in base64 format, for web, mobile, and web applications

License

Notifications You must be signed in to change notification settings

ggoodkey/base64

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

31 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

About

Convert, compress and share text in base64 format, for web, mobile, and web applications

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published