{"id":19503471,"url":"https://github.com/exonum/pwbox","last_synced_at":"2025-04-26T00:33:11.364Z","repository":{"id":86827640,"uuid":"89079495","full_name":"exonum/pwbox","owner":"exonum","description":"Password-based encryption for Node and browsers","archived":false,"fork":false,"pushed_at":"2018-07-20T09:09:08.000Z","size":132,"stargazers_count":4,"open_issues_count":6,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T05:41:42.186Z","etag":null,"topics":["crypto","cryptography","encryption","libsodium","pwhash","scrypt"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exonum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-22T15:25:01.000Z","updated_at":"2019-08-30T20:59:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"25fad6e4-c5e5-448f-aa49-0b20f9f4daec","html_url":"https://github.com/exonum/pwbox","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonum%2Fpwbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonum%2Fpwbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonum%2Fpwbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonum%2Fpwbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exonum","download_url":"https://codeload.github.com/exonum/pwbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250917285,"owners_count":21507561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crypto","cryptography","encryption","libsodium","pwhash","scrypt"],"created_at":"2024-11-10T22:21:34.364Z","updated_at":"2025-04-26T00:33:11.358Z","avatar_url":"https://github.com/exonum.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Password-Based Encryption for Node and Browsers\n\n[![Build status][travis-image]][travis-url]\n[![Code coverage][coveralls-image]][coveralls-url]\n[![Code style][code-style-image]][code-style-url]\n[![License][license-image]][license-url]\n\n[travis-image]: https://img.shields.io/travis/exonum/pwbox.svg?style=flat-square\n[travis-url]: https://travis-ci.org/exonum/pwbox\n[coveralls-image]: https://img.shields.io/coveralls/exonum/pwbox.svg?style=flat-square\n[coveralls-url]: https://coveralls.io/github/exonum/pwbox\n[code-style-image]: https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square\n[code-style-url]: https://github.com/Flet/semistandard\n[license-image]: https://img.shields.io/github/license/exonum/pwbox.svg?style=flat-square\n[license-url]: https://opensource.org/licenses/Apache-2.0\n\n**pwbox** is a JS library for password-based encryption. It is similar to\nNaCl/libsodium's built-in `secretbox`, only it implements\nencryption based on passwords rather on secret keys.\n\nBehind the scenes, pwbox uses crypto-primitves from NaCl/libsodium:\n- `pwhash_scryptsalsa208sha256` for key derivation\n- `secretbox` routines for key-based symmetric encryption\n\n**Security Notice.** Use this software at your own risk. You should think carefully\nbefore using this (or any other) software to ensure browser-based client-side\nsecurity; browser environments are somewhat unsecure.\n\n## Getting Started\n\nImport pwbox to your project:\n\n```javascript\nvar pwbox = require('pwbox');\n```\n\n...and use it similarly to `secretbox` in [TweetNaCl.js](http://tweetnacl.js.org/):\n\n```javascript\nvar password = 'pleaseletmein';\nvar message = new Uint8Array([ 65, 66, 67 ]);\n\npwbox(message, password).then(box =\u003e {\n  console.log(box);\n  return pwbox.open(box, password);\n}).then(opened =\u003e {\n  console.log(opened);\n});\n```\n\n`pwbox` (encryption routine) and `pwbox.open` (decryption routine) are asynchronous;\nthey support either callbacks or promises.\nSee [the API docs](doc/API.md) for more details.\n\nThe same example as above, with callbacks.\n\n```javascript\nvar password = 'pleaseletmein';\nvar message = new Uint8Array([ 65, 66, 67 ]);\n\npwbox(message, password, function (err, box) {\n  console.log(box);\n  pwbox.open(box, password, function (err, opened) {\n    console.log(opened);\n  });\n});\n```\n\nYou may also invoke `pwbox` and `pwbox.open` with a single-argument callback.\nJust use `.orFalse` after the call:\n\n```javascript\nvar box = // ...\npwbox.open.orFalse(box, password, function (opened) {\n  if (!opened) {\n    // do error handling\n    return;\n  }\n  // use opened\n});\n```\n\nIn this case, the callback will be called with `false` if an error occurs during the call.\n\n### Encoding Messages\n\n**pwbox** requires for a message to be a `Uint8Array` instance. This means you can\nencrypt binary data (e.g., private keys) without any conversion. If you want\nto encrypt *string* data, you need to convert it to `Uint8Array`. This can be\naccomplished in several ways.\n\n#### Using `Buffer`\n\nNode has [`Buffer.from(str, encoding)`][node-bufferfrom] method\nand its older version, [`new Buffer(str, encoding)`][node-newbuffer] to\nconvert from strings to byte buffers.\nFor the complementary operation, you may use [`buffer.toString(encoding)`][node-buffertostring].\nThese methods are also available\nvia [the `buffer` package][npm-buffer] in browser environments. As `Buffer`s\ninherit from `Uint8Array`, you may freely pass them as messages.\n\n#### Using `enodeURIComponent`\n\nBrowsers [can also use][so-str-to-buffer]\nbuilt-in `enodeURIComponent` and `decodeURIComponent` methods for the conversion:\n\n```javascript\nfunction toUint8Array (str) {\n  str = unescape(encodeURIComponent(str));\n  var buffer = new Uint8Array(str.length);\n  for (var i = 0; i \u003c buffer.length; i++) {\n    buffer[i] = str[i].charCodeAt(0);\n  }\n  return buffer;\n}\n\nfunction fromUint8Array (buffer) {\n  var encodedString = String.fromCharCode.apply(null, buffer);\n  var decodedString = decodeURIComponent(escape(encodedString));\n  return decodedString;\n}\n```\n\n\u003e **Tip.** Although it's not strictly necessary, you may convert the password\n\u003e into a `Uint8Array` in the same way as the message.\n\n## Options\n\n**pwbox** supports tuning the scrypt parameters using `opslimit` and `memlimit` from\nlibsodium. These parameters determine the amount of computations and\nthe RAM usage, respectively, for `pwbox` and `pwbox.open`.\n\n```javascript\npwbox(message, password, {\n  opslimit: 1 \u003c\u003c 20, // 1M\n  memlimit: 1 \u003c\u003c 25  // 32M\n}).then(box =\u003e console.log(box));\n```\n\nThe default values for `opslimit` and `memlimit` are also taken from libsodium\n(`524288` and `16777216`, respectively). With the default parameters, `pwbox`\nuses 16 MB of RAM and completes\nwith a comfortable 100ms delay in Node, several hundred ms in browsers\non desktops/laptops, and under a second on smartphones.\nYou may use increased parameter values for better security;\nsee the [crypto spec](doc/cryptography.md#parameter-validation) for more details.\n\n### Backends\n\n**pwbox** may use one of the following cryptographic backends:\n\n- [libsodium-wrappers-sumo][libsodium]\n- [tweetnacl][tweetnacl] + [scrypt-async][scrypt-async] (default)\n\nTo use a non-default backend, call `pwbox.withCrypto` with `'tweetnacl'`\nor `'libsodium'`; it will return the\nobject with the same interface as `pwbox` itself.\n\n```javascript\nvar sodiumPwbox = require('pwbox').withCrypto('libsodium');\nsodiumPwbox(message, password).then(/* ... */);\n```\n\nYou may even supply your own backend by passing an object to `withCrypto`!\n[See documentation](doc/API.md#withcrypto) for more details.\n\n## Lite Version and Use in Browsers\n\n`require('pwbox/lite')` loads a simplified version of **pwbox**, which\nuses a fixed backend (tweetnacl + scrypt-async) and has no `withCrypto` function.\nThis is the preferred way to use **pwbox** in browsers, as the full version\nof the librabry is quite bulky. You may use `'pwbox/lite'` together with\nyour favorite browserifier (say, `browserify` or `webpack`), or\nimport a readymade browserified and minified lite package directly\nfrom the **dist** directory of the package.\n\n[libsodium]: https://www.npmjs.com/package/libsodium-wrappers-sumo\n[tweetnacl]: https://www.npmjs.com/package/tweetnacl\n[scrypt-async]: https://www.npmjs.com/package/scrypt-async\n\n## License\n\nCopyright (c) 2017, Exonum Team\n\n**pwbox** is licensed under [Apache 2.0 license](LICENSE).\n\n[node-bufferfrom]: https://nodejs.org/dist/latest-v6.x/docs/api/buffer.html#buffer_class_method_buffer_from_string_encoding\n[node-newbuffer]: https://nodejs.org/dist/latest-v6.x/docs/api/buffer.html#buffer_new_buffer_string_encoding\n[node-buffertostring]: https://nodejs.org/dist/latest-v6.x/docs/api/buffer.html#buffer_buf_tostring_encoding_start_end\n[npm-buffer]: https://www.npmjs.com/package/buffer\n[so-str-to-buffer]: https://stackoverflow.com/questions/17191945/conversion-between-utf-8-arraybuffer-and-string\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexonum%2Fpwbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexonum%2Fpwbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexonum%2Fpwbox/lists"}