{"id":13483814,"url":"https://github.com/entronad/crypto-es","last_synced_at":"2025-05-16T07:07:01.176Z","repository":{"id":33555775,"uuid":"159462232","full_name":"entronad/crypto-es","owner":"entronad","description":"A cryptography algorithms library","archived":false,"fork":false,"pushed_at":"2024-06-18T05:54:16.000Z","size":711,"stargazers_count":285,"open_issues_count":7,"forks_count":32,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-09T11:51:22.714Z","etag":null,"topics":["3des","aes","base64","blowfish","cipher","crypto","encryption","es6","frontend","hash","javascript","js","md5","nodejs","rabbit","rc4","sha1","sha256","typescript","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/entronad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2018-11-28T07:34:17.000Z","updated_at":"2025-04-27T04:17:24.000Z","dependencies_parsed_at":"2024-11-29T02:10:46.368Z","dependency_job_id":"31121720-9f0d-41e0-ac45-1a26554bbff4","html_url":"https://github.com/entronad/crypto-es","commit_stats":{"total_commits":66,"total_committers":5,"mean_commits":13.2,"dds":"0.10606060606060608","last_synced_commit":"d506677fae3d03a454b37ad126e0c119d416b757"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entronad%2Fcrypto-es","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entronad%2Fcrypto-es/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entronad%2Fcrypto-es/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entronad%2Fcrypto-es/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/entronad","download_url":"https://codeload.github.com/entronad/crypto-es/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485065,"owners_count":22078767,"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":["3des","aes","base64","blowfish","cipher","crypto","encryption","es6","frontend","hash","javascript","js","md5","nodejs","rabbit","rc4","sha1","sha256","typescript","web"],"created_at":"2024-07-31T17:01:15.538Z","updated_at":"2025-05-16T07:06:59.915Z","avatar_url":"https://github.com/entronad.png","language":"JavaScript","readme":"# CryptoES\n\n*A cryptography algorithms library compatible with ES6 and TypeScript*\n\n- Inspired by and has the same API with [CryptoJS](https://code.google.com/archive/p/crypto-js/) \n- With types for TypeScript usage\n- Witten in latest ECMAScript Standard\n- Support ES6 module import and partially import\n\n## Usage\n\nInstallation:\n\n```\nyarn add crypto-es\n```\n\n---\n\nIn Node.js projects, we recommend you to use ECMAScript Modules insead of CommonJS:\n\n```\n// package.json\n{\n  \"type\": \"module\"\n}\n```\n\n---\n\nThen you can import CryptoES:\n\n```\nimport CryptoES from 'crypto-es';\nconst rst = CryptoES.MD5(\"Message\").toString();\n```\n\nOr partially import the function to reduce the package weight:\n\n```\nimport { MD5 } from 'crypto-es/lib/md5.js';\nconst rst = MD5(\"Message\").toString();\n```\n\n## TypeScript Usage\n\nEvery file in this library has its own .d.ts file now, so it is available to partially import single algorithm files in TypeScript projects.\n\n## Guide\n\n\u003e Just the same as [CryptoJS](https://code.google.com/archive/p/crypto-js/)\n\n---\n\n- [Hashers](###Hashers)\n- [HMAC](#HMAC)\n- [Ciphers](#Ciphers)\n- [Encoders](#Encoders)\n- [ArrayBuffer and TypedArray](#ArrayBuffer-and-TypedArray)\n\n---\n\n### Hashers\n\n#### The Hasher Algorithms\n\n**MD5**\n\nMD5 is a widely used hash function. It's been used in a variety of security applications and is also commonly used to check the integrity of files. Though, MD5 is not collision resistant, and it isn't suitable for applications like SSL certificates or digital signatures that rely on this property.\n\n```\nconst hash = CryptoES.MD5(\"Message\");\n```\n\n**SHA-1**\n\nThe SHA hash functions were designed by the National Security Agency (NSA). SHA-1 is the most established of the existing SHA hash functions, and it's used in a variety of security applications and protocols. Though, SHA-1's collision resistance has been weakening as new attacks are discovered or improved.\n\n```\nconst hash = CryptoES.SHA1(\"Message\");\n```\n\n**SHA-2**\n\nSHA-256 is one of the four variants in the SHA-2 set. It isn't as widely used as SHA-1, though it appears to provide much better security.\n\n```\nconst hash = CryptoES.SHA256(\"Message\");\n```\n\nSHA-512 is largely identical to SHA-256 but operates on 64-bit words rather than 32.\n\n```\nconst hash = CryptoES.SHA512(\"Message\");\n```\n\nCryptoES also supports SHA-224 and SHA-384, which are largely identical but truncated versions of SHA-256 and SHA-512 respectively.\n\n**SHA-3**\n\nSHA-3 is the winner of a five-year competition to select a new cryptographic hash algorithm where 64 competing designs were evaluated.\n\n**NOTE:** I made a mistake when I named this implementation SHA-3. It should be named Keccak[c=2d]. Each of the SHA-3 functions is based on an instance of the Keccak algorithm, which NIST selected as the winner of the SHA-3 competition, but those SHA-3 functions won't produce hashes identical to Keccak.\n\n```\nconst hash = CryptoES.SHA3(\"Message\");\n```\n\nSHA-3 can be configured to output hash lengths of one of 224, 256, 384, or 512 bits. The default is 512 bits.\n\n```\nconst hash = CryptoES.SHA3(\"Message\", { outputLength: 512 });\nconst hash = CryptoES.SHA3(\"Message\", { outputLength: 384 });\nconst hash = CryptoES.SHA3(\"Message\", { outputLength: 256 });\nconst hash = CryptoES.SHA3(\"Message\", { outputLength: 224 });\n```\n\n**RIPEMD-160**\n\n```\nconst hash = CryptoES.RIPEMD160(\"Message\");\n```\n\n#### The Hasher Input\n\nThe hash algorithms accept either strings or instances of CryptoES.lib.WordArray. A WordArray object represents an array of 32-bit words. When you pass a string, it's automatically converted to a WordArray encoded as UTF-8.\n\n#### The Hasher Output\n\nThe hash you get back isn't a string yet. It's a WordArray object. When you use a WordArray object in a string context, it's automatically converted to a hex string.\n\n```\nconst hash = CryptoES.SHA256(\"Message\");\nalert(typeof hash); // object\nalert(hash); // 2f77668a9dfbf8d5848b9eeb4a7145ca94c6ed9236e4a773f6dcafa5132b2f91\n```\n\nYou can convert a WordArray object to other formats by explicitly calling the toString method and passing an encoder.\n\n```\nconst hash = CryptoES.SHA256(\"Message\");\nalert(hash.toString(CryptoES.enc.Base64)); // L3dmip37+NWEi57rSnFFypTG7ZI25Kdz9tyvpRMrL5E= alert(hash.toString(CryptoES.enc.Latin1)); // /wf��ûøÕ���ëJqEÊ�Æí�6ä§söܯ¥\u0013+/�\nalert(hash.toString(CryptoES.enc.Hex)); // 2f77668a9dfbf8d5848b9eeb4a7145ca94c6ed9236e4a773f6dcafa5132b2f91\n```\n\n#### Progressive Hashing\n\n```\nconst sha256 = CryptoES.algo.SHA256.create();\nsha256.update(\"Message Part 1\");\nsha256.update(\"Message Part 2\");\nsha256.update(\"Message Part 3\");\nconst hash = sha256.finalize();\n```\n\n### HMAC\n\nKeyed-hash message authentication codes (HMAC) is a mechanism for message authentication using cryptographic hash functions.\n\nHMAC can be used in combination with any iterated cryptographic hash function.\n\n```\nconst hash = CryptoES.HmacMD5(\"Message\", \"Secret Passphrase\");\nconst hash = CryptoES.HmacSHA1(\"Message\", \"Secret Passphrase\");\nconst hash = CryptoES.HmacSHA256(\"Message\", \"Secret Passphrase\");\nconst hash = CryptoES.HmacSHA512(\"Message\", \"Secret Passphrase\");\n```\n\n#### Progressive HMAC Hashing\n\n```\nconst hmac = CryptoES.algo.HMAC.create(CryptoES.algo.SHA256, \"Secret Passphrase\");\nhmac.update(\"Message Part 1\");\nhmac.update(\"Message Part 2\");\nhmac.update(\"Message Part 3\");\nconst hash = hmac.finalize();\n```\n\n### PBKDF2\n\nPBKDF2 is a password-based key derivation function. In many applications of cryptography, user security is ultimately dependent on a password, and because a password usually can't be used directly as a cryptographic key, some processing is required.\n\nA salt provides a large set of keys for any given password, and an iteration count increases the cost of producing keys from a password, thereby also increasing the difficulty of attack.\n\n```\nconst salt = CryptoES.lib.WordArray.random(128/8);\nconst key128Bits = CryptoES.PBKDF2(\"Secret Passphrase\", salt, { keySize: 128/32 });\nconst key256Bits = CryptoES.PBKDF2(\"Secret Passphrase\", salt, { keySize: 256/32 });\nconst key512Bits = CryptoES.PBKDF2(\"Secret Passphrase\", salt, { keySize: 512/32 });\nconst key512Bits1000Iterations = CryptoES.PBKDF2(\"Secret Passphrase\", salt, { keySize: 512/32, iterations: 1000 });\n```\n\n### Ciphers\n\n#### The Cipher Algorithms\n\n**AES**\n\nThe Advanced Encryption Standard (AES) is a U.S. Federal Information Processing Standard (FIPS). It was selected after a 5-year process where 15 competing designs were evaluated.\n\n```\nconst encrypted = CryptoES.AES.encrypt(\"Message\", \"Secret Passphrase\");\nconst decrypted = CryptoES.AES.decrypt(encrypted, \"Secret Passphrase\");\n```\n\nCryptoES supports AES-128, AES-192, and AES-256. It will pick the variant by the size of the key you pass in. If you use a passphrase, then it will generate a 256-bit key.\n\n**DES, Triple DES**\n\nDES is a previously dominant algorithm for encryption, and was published as an official Federal Information Processing Standard (FIPS). DES is now considered to be insecure due to the small key size.\n\n```\nconst encrypted = CryptoES.DES.encrypt(\"Message\", \"Secret Passphrase\");\nconst decrypted = CryptoES.DES.decrypt(encrypted, \"Secret Passphrase\");\n```\n\nTriple DES applies DES three times to each block to increase the key size. The algorithm is believed to be secure in this form.\n\n```\nconst encrypted = CryptoES.TripleDES.encrypt(\"Message\", \"Secret Passphrase\");\nconst decrypted = CryptoES.TripleDES.decrypt(encrypted, \"Secret Passphrase\");\n```\n\n**Rabbit**\n\nRabbit is a high-performance stream cipher and a finalist in the eSTREAM Portfolio. It is one of the four designs selected after a 3 1/2-year process where 22 designs were evaluated.\n\n```\nconst encrypted = CryptoES.Rabbit.encrypt(\"Message\", \"Secret Passphrase\");\nconst decrypted = CryptoES.Rabbit.decrypt(encrypted, \"Secret Passphrase\");\n```\n\n**RC4, RC4Drop**\n\nRC4 is a widely-used stream cipher. It's used in popular protocols such as SSL and WEP. Although remarkable for its simplicity and speed, the algorithm's history doesn't inspire confidence in its security.\n\n```\nconst encrypted = CryptoES.RC4.encrypt(\"Message\", \"Secret Passphrase\");\nconst decrypted = CryptoES.RC4.decrypt(encrypted, \"Secret Passphrase\");\n```\n\nIt was discovered that the first few bytes of keystream are strongly non-random and leak information about the key. We can defend against this attack by discarding the initial portion of the keystream. This modified algorithm is traditionally called RC4-drop.\n\nBy default, 192 words (768 bytes) are dropped, but you can configure the algorithm to drop any number of words.\n\n```\nconst encrypted = CryptoES.RC4Drop.encrypt(\"Message\", \"Secret Passphrase\");\nconst encrypted = CryptoES.RC4Drop.encrypt(\"Message\", \"Secret Passphrase\", { drop: 3072/4 });\nconst decrypted = CryptoES.RC4Drop.decrypt(encrypted, \"Secret Passphrase\", { drop: 3072/4 });\n```\n\n**Blowfish**\n\nBlowfish is a symmetric-key block cipher, designed in 1993 by Bruce Schneier and included in many cipher suites and encryption products. Blowfish provides a good encryption rate in software, and no effective cryptanalysis of it has been found to date. However, the Advanced Encryption Standard (AES) now receives more attention, and Schneier recommends Twofish for modern applications.\n\nSchneier designed Blowfish as a general-purpose algorithm, intended as an alternative to the aging DES and free of the problems and constraints associated with other algorithms. At the time Blowfish was released, many other designs were proprietary, encumbered by patents, or were commercial or government secrets. Schneier has stated that \"Blowfish is unpatented, and will remain so in all countries. The algorithm is hereby placed in the public domain, and can be freely used by anyone.\"\n\nNotable features of the design include key-dependent S-boxes and a highly complex key schedule.\n\n```\nconst ciphertext = CryptoJS.Blowfish.encrypt(message, key, cfg);\nconst plaintext  = CryptoJS.Blowfish.decrypt(ciphertext, key, cfg);\n```\n\n#### Custom Key and IV\n\n```\nconst key = CryptoES.enc.Hex.parse('000102030405060708090a0b0c0d0e0f');\nconst iv = CryptoES.enc.Hex.parse('101112131415161718191a1b1c1d1e1f');\nconst encrypted = CryptoES.AES.encrypt(\"Message\", key, { iv: iv });\n```\n\n#### Block Modes and Padding\n\n```\nconst encrypted = CryptoES.AES.encrypt(\"Message\", \"Secret Passphrase\", { mode: CryptoES.mode.CFB, padding: CryptoES.pad.AnsiX923 });\n```\n\nCryptoES supports the following modes:\n\n- CBC (the default)\n- CFB\n- CTR\n- OFB\n- ECB\n\nAnd CryptoES supports the following padding schemes:\n\n- Pkcs7 (the default)\n- Iso97971\n- AnsiX923\n- Iso10126\n- ZeroPadding\n- NoPadding\n\n#### The Cipher Input\n\nFor the plaintext message, the cipher algorithms accept either strings or instances of CryptoES.lib.WordArray.\n\nFor the key, when you pass a string, it's treated as a passphrase and used to derive an actual key and IV. Or you can pass a WordArray that represents the actual key. If you pass the actual key, you must also pass the actual IV.\n\nFor the ciphertext, the cipher algorithms accept either strings or instances of CryptoES.lib.CipherParams. A CipherParams object represents a collection of parameters such as the IV, a salt, and the raw ciphertext itself. When you pass a string, it's automatically converted to a CipherParams object according to a configurable format strategy.\n\n#### The Cipher Output\n\nThe plaintext you get back after decryption is a WordArray object. See Hashers' Output for more detail.\n\nThe ciphertext you get back after encryption isn't a string yet. It's a CipherParams object. A CipherParams object gives you access to all the parameters used during encryption. When you use a CipherParams object in a string context, it's automatically converted to a string according to a format strategy. The default is an OpenSSL-compatible format.\n\n```\nconst encrypted = CryptoES.AES.encrypt(\"Message\", \"Secret Passphrase\"); alert(encrypted.key); // 74eb593087a982e2a6f5dded54ecd96d1fd0f3d44a58728cdcd40c55227522223\nalert(encrypted.iv); // 7781157e2629b094f0e3dd48c4d786115\nalert(encrypted.salt); // 7a25f9132ec6a8b34\nalert(encrypted.ciphertext); // 73e54154a15d1beeb509d9e12f1e462a0\nalert(encrypted); // U2FsdGVkX1+iX5Ey7GqLND5UFUoV0b7rUJ2eEvHkYqA=\n```\n\nYou can define your own formats in order to be compatible with other crypto implementations. A format is an object with two methods—stringify and parse—that converts between CipherParams objects and ciphertext strings.\n\nHere's how you might write a JSON formatter:\n\n```\nconst JsonFormatter = { \n  stringify: function (cipherParams) { // create json object with ciphertext\n    const jsonObj = { ct: cipherParams.ciphertext.toString(CryptoES.enc.Base64) }; // optionally add iv and salt\n    if (cipherParams.iv) {\n      jsonObj.iv = cipherParams.iv.toString();\n    }\n    if (cipherParams.salt) {\n      jsonObj.s = cipherParams.salt.toString();\n    }\n    // stringify json object\n    return JSON.stringify(jsonObj);\n  },\n  parse: function (jsonStr) { // parse json string\n    const jsonObj = JSON.parse(jsonStr); // extract ciphertext from json object, and create cipher params object\n    const cipherParams = CryptoES.lib.CipherParams.create(\n      { ciphertext: CryptoES.enc.Base64.parse(jsonObj.ct) },\n    ); // optionally extract iv and salt\n    if (jsonObj.iv) {\n      cipherParams.iv = CryptoES.enc.Hex.parse(jsonObj.iv)\n    }\n    if (jsonObj.s) {\n      cipherParams.salt = CryptoES.enc.Hex.parse(jsonObj.s)\n    }\n    return cipherParams;\n  },\n};\nconst encrypted = CryptoES.AES.encrypt(\n  \"Message\",\n  \"Secret Passphrase\",\n  { format: JsonFormatter },\n);\nalert(encrypted); // {\"ct\":\"tZ4MsEnfbcDOwqau68aOrQ==\",\"iv\":\"8a8c8fd8fe33743d3638737ea4a00698\",\"s\":\"ba06373c8f57179c\"}\nconst decrypted = CryptoES.AES.decrypt(\n  encrypted,\n  \"Secret Passphrase\",\n  { format: JsonFormatter },\n);\nalert(decrypted.toString(CryptoES.enc.Utf8)); // Message\n```\n\n#### Progressive Ciphering\n\n```\nconst key = CryptoES.enc.Hex.parse('000102030405060708090a0b0c0d0e0f');\nconst iv = CryptoES.enc.Hex.parse('101112131415161718191a1b1c1d1e1f');\nconst aesEncryptor = CryptoES.algo.AES.createEncryptor(key, { iv: iv });\nconst ciphertextPart1 = aesEncryptor.process(\"Message Part 1\");\nconst ciphertextPart2 = aesEncryptor.process(\"Message Part 2\");\nconst ciphertextPart3 = aesEncryptor.process(\"Message Part 3\");\nconst ciphertextPart4 = aesEncryptor.finalize();\nconst aesDecryptor = CryptoES.algo.AES.createDecryptor(key, { iv: iv });\nconst plaintextPart1 = aesDecryptor.process(ciphertextPart1);\nconst plaintextPart2 = aesDecryptor.process(ciphertextPart2);\nconst plaintextPart3 = aesDecryptor.process(ciphertextPart3);\nconst plaintextPart4 = aesDecryptor.process(ciphertextPart4);\nconst plaintextPart5 = aesDecryptor.finalize();\n```\n\n#### Interoperability\n\nWith OpenSSL\n\nEncrypt with OpenSSL:\n\n```\nopenssl enc -aes-256-cbc -in infile -out outfile -pass pass:\"Secret Passphrase\" -e -base64\n```\n\nDecrypt with CryptoES:\n\n```\nconst decrypted = CryptoES.AES.decrypt(openSSLEncrypted, \"Secret Passphrase\");\n```\n\n### Encoders\n\nCryptoES can convert from encoding formats such as Base64, Latin1 or Hex to WordArray objects and vica versa.\n\n```\nconst words = CryptoES.enc.Base64.parse('SGVsbG8sIFdvcmxkIQ==');\nconst base64 = CryptoES.enc.Base64.stringify(words);\nconst words = CryptoES.enc.Base64url.parse('SGVsbG8sIFdvcmxkIQ==');\nconst base64url = CryptoES.enc.Base64.stringify(words);\nconst words = CryptoES.enc.Latin1.parse('Hello, World!');\nconst latin1 = CryptoES.enc.Latin1.stringify(words);\nconst words = CryptoES.enc.Hex.parse('48656c6c6f2c20576f726c6421');\nconst hex = CryptoES.enc.Hex.stringify(words);\nconst words = CryptoES.enc.Utf8.parse('𤭢');\nconst utf8 = CryptoES.enc.Utf8.stringify(words);\nconst words = CryptoES.enc.Utf16.parse('Hello, World!');\nconst utf16 = CryptoES.enc.Utf16.stringify(words);\nconst words = CryptoES.enc.Utf16LE.parse('Hello, World!');\nconst utf16 = CryptoES.enc.Utf16LE.stringify(words);\n```\n\n### ArrayBuffer and TypedArray\n\nWordArray creator could recive an ArrayBuffer or TypedArray so that CryptoES algorisms could apply to them:\n\n```\nconst words = CryptoES.lib.WordArray.create(new ArrayBuffer(8));\nconst rst = CryptoES.AES.encrypt(words, 'Secret Passphrase')\n```\n\n**NOTE**: ArrayBuffer could not directly passed to algorisms, you should change them to WordArray first.\n\nWith this, encrypting files would be easier:\n\n```\nconst fileInput = document.getElementById('fileInput');\nconst file = fileInput.files[0];\nconst reader = new FileReader();\nreader.readAsArrayBuffer(file);\nreader.onload = function () {\n  const arrayBuffer = reader.result;\n  const words = CryptoES.lib.WordArray.create(arrayBuffer);\n  const rst = CryptoES.AES.encrypt(words, 'Secret Passphrase')\n  ...\n};\n```\n\n## Change Log\n\n[Change Log](https://github.com/entronad/crypto-es/blob/master/CHANGELOG.md)\n\n## Blogs\n\n[Refactoring CryptoJS in Modern ECMAScript](https://medium.com/front-end-weekly/refactoring-cryptojs-in-modern-ecmascript-1d4e1837c272) ","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fentronad%2Fcrypto-es","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fentronad%2Fcrypto-es","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fentronad%2Fcrypto-es/lists"}