{"id":23131220,"url":"https://github.com/emartech/node-easy-crypto","last_synced_at":"2025-08-17T08:31:11.207Z","repository":{"id":56900084,"uuid":"58127382","full_name":"emartech/node-easy-crypto","owner":"emartech","description":"Provides a thin secure-by-default wrapper around Node's crypto functionality.","archived":false,"fork":false,"pushed_at":"2022-10-14T08:18:03.000Z","size":206,"stargazers_count":2,"open_issues_count":5,"forks_count":2,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-04-14T07:41:05.711Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emartech.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}},"created_at":"2016-05-05T11:51:06.000Z","updated_at":"2022-04-26T08:24:58.000Z","dependencies_parsed_at":"2023-01-19T23:33:33.975Z","dependency_job_id":null,"html_url":"https://github.com/emartech/node-easy-crypto","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emartech%2Fnode-easy-crypto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emartech%2Fnode-easy-crypto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emartech%2Fnode-easy-crypto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emartech%2Fnode-easy-crypto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emartech","download_url":"https://codeload.github.com/emartech/node-easy-crypto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230105996,"owners_count":18173954,"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":[],"created_at":"2024-12-17T11:12:20.945Z","updated_at":"2024-12-17T11:12:21.760Z","avatar_url":"https://github.com/emartech.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-easy-crypto [ ![Codeship Status for emartech/node-easy-crypto](https://codeship.com/projects/0baf8660-f4ea-0133-b502-5ef57cbd419a/status?branch=master)](https://codeship.com/projects/150193) [![Depedencies](https://david-dm.org/emartech/node-easy-crypto.svg)](https://david-dm.org/emartech/node-easy-crypto) [![Dev depedencies](https://david-dm.org/emartech/node-easy-crypto/dev-status.svg)](https://david-dm.org/emartech/node-easy-crypto#info=devDependencies\u0026view=table)\nProvides simple wrappers around Node's crypto implementation. The library provides two interfaces: simple and advanced. Simple mode is designed for ease-of-use and advanced mode provides some performance benefits in certain use-cases. See below for more details.\n\nAll the underlying crypto operations are the same.\n\n## Simple usage (Recommended)\nTo get started just require the lib and create an instance right away. \n\n```js\nconst crypto = require('crypto');\nconst easyCrypto = require('@emartech/easy-crypto');\n\nconst password = crypto.randomBytes(24).toString('hex');\nconst randomData = crypto.randomBytes(1024).toString('hex');\n\nconst ecrypto = easyCrypto(password);\n\nasync function exampleAsyncFunction() {\n    const encrypted = await ecrypto.encrypt(randomData);\n    const decrypted = await ecrypto.decrypt(encrypted);\n    randomData === decrypted; //true\n}\n```\n\n## Advanced usage (Use for performance)\n[Key derivation](https://en.wikipedia.org/wiki/Key_derivation_function) is a resource heavy process. The default settings recompute the key before each encryption/decryption process. \n\nThese options allow you to cache the result of the key derivation. This is required if you need to encrypt/decrypt multiple times with the same derived key. Caching the keys with [node-cache](https://github.com/node-cache/node-cache) saves you the time to have to recompute it before every encryption/decryption.\n\nTo get started just require the lib and create an instance right away.\n\n```js\nconst crypto = require('crypto');\nconst easyCrypto = require('@emartech/easy-crypto');\n\nconst password = crypto.randomBytes(24).toString('hex');\nconst randomData = [\n    crypto.randomBytes(1024).toString('hex'),\n    crypto.randomBytes(1024).toString('hex'),\n    crypto.randomBytes(1024).toString('hex')\n];\n\nconst ecrypto = easyCrypto(password, {\n  encryptCacheTtl: 3600,\n  decryptCachePoolSize: 100,\n});\n\nasync function exampleAsyncFunction() {\n    const encrypted = await Promise.all(\n        randomData.map(item =\u003e ecrypto.encrypt(item))\n    );\n\n    const decrypted = await Promise.all(\n        encrypted.map(item =\u003e ecrypto.decrypt(item))\n    );\n    \n    return data.reduce((allValid, item, index) =\u003e {\n        return allValid \u0026\u0026 item === decrypted[index];\n    }, true);\n}\n```\n\n## Interface\n\n### Initialization\nThere aren't too many options you can change and that is on purpose. This small wrapper library is secure by default. You can change two configurations: `encryptCacheTtl`, `decryptCachePoolSize` by passing them to the initialization function as follows:\n```js\nlet ecrypto = require('@emartech/easy-crypto')('password', {\n  encryptCacheTtl: 3600,\n  decryptCachePoolSize: 100,\n});\n```\n\n#### `password`\n`password` should be any normal string. It will be used to generate the encryption key.\n\n#### `encryptCacheTtl`\nTime in seconds while the same key is reused during encryption. Must be an integer.\n\n#### `decryptCachePoolSize`\nMaximum number of keys kept in the cache during decryption. Must be an integer.\n\n### encrypt(`plaintext`) -\u003e `ciphertext`\n`plaintext` must be `utf-8` encoded string. It will be \"converted\" to `bytes` and those will be used for the cryptographic operations. The output of this operations is `base64` encoded buffers. This will be used as the input of the `decrypt` operation. This return value is a `Promise`.\n\n### decrypt(`ciphertext`) -\u003e `plaintext`\n`ciphertext` must be the output of the `encrypt` method. The library is not compatible with any other encryption library out of the box! The output of this operation is the original `utf-8` encoded string. This return value is a `Promise`.\n\n## The crypto parts\nThe library is only a thin wrapper of node's own `crypto` module. It uses well known and battle tested encryption techniques. It provides a convenient wrapper around these functions, taking away the details of using encryption correctly. Feel free to explore the source!\n\n### Encryption process\n1. It generates random bytes for later operations\n2. `passwordSaltSize` random `bytes` are used to create the `256 bit` long encryption key from the `password` using `pbkdf2` and the given `iteration count`\n3. The `plaintext` is encrypted using `aes-256-gcm` with the generated key and a `12 bytes` long random `initialization vector`, this operation also yields a `16 bytes` long `authentication tag`, which can be used to verify the encrypted data's integrity\n4. It concatenates the following data to into a buffer: `passwordSalt bytes`, `initialization vector bytes`, `ciphertext bytes`, `authentication tag bytes`\n5. It encodes the whole buffer using `base64` and returns it\n\n### Decryption process\n1. It decodes the `base64` input to bytes\n2. It slices this data into: `passwordSalt bytes`, `initialization vector bytes`, `ciphertext bytes`, `authentication tag bytes`\n3. The `passwordSalt bytes` and the `password` are used to generate the `256 bit` long encryption key using `pbkdf2` and the given `iteration count`\n4. The `ciphertext bytes` are decrypted using `aes-256-gcm` with the generated key the `initialization vector bytes`. During encryption the integrity of the date is also verified using the `authentication tag bytes`\n5. It encodes the decrypted buffer using `utf-8` and returns it\n\n## Found a bug? Have a comment?\nPlease find us, we would love your feedback!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femartech%2Fnode-easy-crypto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femartech%2Fnode-easy-crypto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femartech%2Fnode-easy-crypto/lists"}