initial commit

Author: brainfoolong

.gitattributes

@@ -0,0 +1,19 @@
+*.js text eol=lf
+*.sh text eol=lf
+*.json text eol=lf
+*.ts text eol=lf
+*.html text eol=lf
+*.txt text eol=lf
+*.min.js binary
+vendor/* binary
+
+.github export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.npmignore export-ignore
+.npmrc export-ignore
+build export-ignore
+tests export-ignore
+playwright.config.ts export-ignore
+tsconfig.json export-ignore
+package-lock.json export-ignore

.gitignore

@@ -0,0 +1,7 @@
+.idea
+.npmrc
+node_modules
+package-lock.json
+/test-results/
+/playwright-report/
+/playwright/.cache/

.npmignore

@@ -0,0 +1,4 @@
+*
+!dist/*
+!src/*
+!CHANGELOG.md

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Roland Eigelsreiter
+Copyright (c) 2024 BrainFooLong (Roland Eigelsreiter)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +1,47 @@
-# js-aes-php
-Native AES (No CryptoJS required) encryption/decryption on client side with Javascript and on server side with PHP
+# Slim native AES encryption/decryption on client side with Javascript and on server side with PHP
+
+A tool to AES encrypt/decrypt data in javascript and/or PHP. You can use it for PHP only, for Javascript only or mix it together.
+
+It uses `aes-256-cbc` implementation with random salts and random initialization vector. This library does not support other ciphers or modes.
+
+This library is the successor to my previous [CryptoJs-Aea-Php](https://github.com/brainfoolong/cryptojs-aes-php) encryption library that required CryptoJS. This library does not require any third party dependency as modern browsers and Node now have proper crypto tools built in. Attention: This library does output different encryption values to my previous library, it cannot be a drop-in replacement.
+
+### Features
+* Encrypt any value in Javascript (objects/array/etc...) - Everything that can be passed to JSON.stringify
+* Encrypt any value in PHP (object/array/etc...) - Everything that can be passed to json_encode
+* Decrypt in PHP/Javascript, doesn't matter where you have encrypted the values
+* It is safe to store and transfer the encrypted values, as the encrypted output only contains hex characters (0-9 A-F)
+* Small footprint: 5kb unzipped Javascript file
+
+### Requirements
+* For Javascript: Any [recent Browser](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt#browser_compatibility) or Node environment (15+)
+* For Typescript: Use `src/ts/js-aes-php.ts`
+* For PHP: 8.0 or above with OpenSSL extension enabled
+
+
+### PHP - How to use
+```php
+$value = ['foobar' => 'l`î', 'emojiiii' => '😊'];
+$password = '😊Blub';
+$encrypted = JsAesPhp::encrypt($value, $password);
+$decrypted = JsAesPhp::decrypt($encrypted, $password);
+```
+
+### Javascript/Typescript - How to use
+```javascript
+const value = { 'foobar': 'l`î', 'emojiiii': '😊' }
+const password = '😊Blub'
+const encrypted = await JsAesPhp.encrypt(value, password)
+const decrypted = await JsAesPhp.decrypt(encrypted, password)
+```
+
+### Security Notes
+
+This library use AES-256-CBC encryption, which is still good and safe but there are (maybe) better alternatives for your use case. If you require really high security, you should invest more time for what is suitable for you.
+
+Also, there's a good article about PHP issues/info related to this
+library: https://stackoverflow.com/questions/16600708/how-do-you-encrypt-and-decrypt-a-php-string/30159120#30159120
+
+### Alternatives - ASCON
+
+You may wonder if there are alternatives to AES encryption that you can use in PHP/JS. ASCON is a newer, lightweight cipher that have been selected in 2023 by the [NIST](https://csrc.nist.gov/projects/lightweight-cryptography) as the new standard for lightweight cryptography, which may suite your needs. I have created libraries for both PHP and JS which you can find at https://github.com/brainfoolong/php-ascon and https://github.com/brainfoolong/js-ascon

SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+You can use GitHub to privately notify me about security issues.
+
+## Supported Versions
+
+Always just the latest release version.

build/dist.js

@@ -0,0 +1,17 @@
+// create all required dist files
+const fs = require('fs')
+
+const packageJson = require('../package.json')
+const srcFile = __dirname + '/../dist/js-aes-php.js'
+const srcFileModule = __dirname + '/../dist/js-aes-php.module.js'
+let contents = fs.readFileSync(srcFile).toString().replace('export default class JsAesPhp', 'class JsAesPhp')
+contents = '// JsAesPhp v' + packageJson.version + ' @ ' + packageJson.homepage + '\n' + contents
+contents += `
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = JsAesPhp
+}
+`
+let contentsCommonJs = contents
+fs.writeFileSync(srcFile, contentsCommonJs)
+let contentsModule = contents.replace(/^class JsAesPhp/m, 'export default class JsAesPhp')
+fs.writeFileSync(srcFileModule, contentsModule)

dist/js-aes-php.js

@@ -0,0 +1,104 @@
+// JsAesPhp v1.0.1 @ https://github.com/brainfoolong/js-aes-php
+class JsAesPhp {
+    /**
+     * Encrypt a given value which can be of any kind that can be JSON.stringify'd
+     * @param {any} value
+     * @param {string} password The raw password
+     * @param {number} hashIterations The number of iterations to use for the password hash
+     *    This can be subject to change in the future. The number of iterations will be contained
+     *    in the output, so changing the number doesn't break the decrypt function
+     * @return {Promise<string>}
+     */
+    static async encrypt(value, password, hashIterations = 100000) {
+        const crypto = this.getCrypto();
+        const iv = this.getCrypto().getRandomValues(new Uint8Array(16));
+        const salt = crypto.getRandomValues(new Uint8Array(16));
+        const key = await this.generateKey(password, salt, hashIterations);
+        const encoded = new TextEncoder().encode(JSON.stringify(value));
+        const encrypted = new Uint8Array(await crypto.subtle.encrypt({
+            name: 'AES-CBC',
+            iv: iv,
+        }, key, encoded));
+        return hashIterations.toString().padStart(10, '0') + this.byteArrayToHex(iv) + this.byteArrayToHex(salt) + this.byteArrayToHex(encrypted);
+    }
+    /**
+     * Decrypt any previously JsAesPhp.encrypt() value
+     * @param {string} encryptedValue
+     * @param {string} password The raw password
+     * @return {Promise<any>}
+     */
+    static async decrypt(encryptedValue, password) {
+        if (typeof encryptedValue !== 'string' || encryptedValue.length <= 74 || encryptedValue.match(/[^0-9a-f]/)) {
+            throw new Error('Invalid encryptedValue');
+        }
+        const crypto = this.getCrypto();
+        const key = await this.generateKey(password, this.hexToByteArray(encryptedValue.substring(42, 74)), parseInt(encryptedValue.substring(0, 10)));
+        return JSON.parse(new TextDecoder().decode(new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-CBC', iv: this.hexToByteArray(encryptedValue.substring(10, 42)) }, key, this.hexToByteArray(encryptedValue.substring(74))))));
+    }
+    /**
+     * Generate crypto key
+     * @param  {string} password The raw password
+     * @param {Uint8Array} salt
+     * @param {number} hashIterations
+     * @return {Promise<CryptoKey>}
+     * @private
+     */
+    static async generateKey(password, salt, hashIterations = 100000) {
+        if (hashIterations >= 10000000000) {
+            throw new Error('Hash iterations limit exceeded');
+        }
+        const crypto = this.getCrypto();
+        const passwordBytes = new TextEncoder().encode(password);
+        const initialKey = await crypto.subtle.importKey('raw', passwordBytes, { name: 'PBKDF2', hash: 'SHA-256' }, false, ['deriveKey']);
+        return crypto.subtle.deriveKey({ name: 'PBKDF2', salt, iterations: hashIterations, hash: 'SHA-256' }, initialKey, { name: 'AES-CBC', length: 256 }, true, ['encrypt', 'decrypt']);
+    }
+    /**
+     * Get crypto instance depending on the environment
+     * @return {Crypto}
+     * @private
+     */
+    static getCrypto() {
+        if (typeof this.crypto !== 'undefined') {
+            return this.crypto;
+        }
+        if (typeof Uint8Array === 'undefined') {
+            throw new Error('Unsupported environment, Uint8Array missing');
+        }
+        if (typeof TextEncoder === 'undefined') {
+            throw new Error('Unsupported environment, TextEncoder missing');
+        }
+        if (typeof window === 'undefined') {
+            // @ts-ignore
+            if (typeof module !== 'undefined' && module.exports) {
+                // @ts-ignore
+                this.crypto = require('node:crypto');
+                return this.crypto;
+            }
+        }
+        if (!window.crypto) {
+            throw new Error('Unsupported environment, window.crypto missing');
+        }
+        this.crypto = window.crypto;
+        return this.crypto;
+    }
+    /**
+     * Convert given byte array to visual hex representation with leading 0x
+     * @param {Uint8Array} byteArray
+     * @return {string}
+     */
+    static byteArrayToHex(byteArray) {
+        return Array.from(byteArray).map(x => x.toString(16).padStart(2, '0')).join('');
+    }
+    /**
+     * Convert a hex string into given byte array to visual hex representation
+     * @param {str} str
+     * @return {string}
+     */
+    static hexToByteArray(str) {
+        return Uint8Array.from((str.match(/.{1,2}/g) || []).map((byte) => parseInt(byte, 16)));
+    }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = JsAesPhp
+}

dist/js-aes-php.module.js

@@ -0,0 +1,104 @@
+// JsAesPhp v1.0.1 @ https://github.com/brainfoolong/js-aes-php
+export default class JsAesPhp {
+    /**
+     * Encrypt a given value which can be of any kind that can be JSON.stringify'd
+     * @param {any} value
+     * @param {string} password The raw password
+     * @param {number} hashIterations The number of iterations to use for the password hash
+     *    This can be subject to change in the future. The number of iterations will be contained
+     *    in the output, so changing the number doesn't break the decrypt function
+     * @return {Promise<string>}
+     */
+    static async encrypt(value, password, hashIterations = 100000) {
+        const crypto = this.getCrypto();
+        const iv = this.getCrypto().getRandomValues(new Uint8Array(16));
+        const salt = crypto.getRandomValues(new Uint8Array(16));
+        const key = await this.generateKey(password, salt, hashIterations);
+        const encoded = new TextEncoder().encode(JSON.stringify(value));
+        const encrypted = new Uint8Array(await crypto.subtle.encrypt({
+            name: 'AES-CBC',
+            iv: iv,
+        }, key, encoded));
+        return hashIterations.toString().padStart(10, '0') + this.byteArrayToHex(iv) + this.byteArrayToHex(salt) + this.byteArrayToHex(encrypted);
+    }
+    /**
+     * Decrypt any previously JsAesPhp.encrypt() value
+     * @param {string} encryptedValue
+     * @param {string} password The raw password
+     * @return {Promise<any>}
+     */
+    static async decrypt(encryptedValue, password) {
+        if (typeof encryptedValue !== 'string' || encryptedValue.length <= 74 || encryptedValue.match(/[^0-9a-f]/)) {
+            throw new Error('Invalid encryptedValue');
+        }
+        const crypto = this.getCrypto();
+        const key = await this.generateKey(password, this.hexToByteArray(encryptedValue.substring(42, 74)), parseInt(encryptedValue.substring(0, 10)));
+        return JSON.parse(new TextDecoder().decode(new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-CBC', iv: this.hexToByteArray(encryptedValue.substring(10, 42)) }, key, this.hexToByteArray(encryptedValue.substring(74))))));
+    }
+    /**
+     * Generate crypto key
+     * @param  {string} password The raw password
+     * @param {Uint8Array} salt
+     * @param {number} hashIterations
+     * @return {Promise<CryptoKey>}
+     * @private
+     */
+    static async generateKey(password, salt, hashIterations = 100000) {
+        if (hashIterations >= 10000000000) {
+            throw new Error('Hash iterations limit exceeded');
+        }
+        const crypto = this.getCrypto();
+        const passwordBytes = new TextEncoder().encode(password);
+        const initialKey = await crypto.subtle.importKey('raw', passwordBytes, { name: 'PBKDF2', hash: 'SHA-256' }, false, ['deriveKey']);
+        return crypto.subtle.deriveKey({ name: 'PBKDF2', salt, iterations: hashIterations, hash: 'SHA-256' }, initialKey, { name: 'AES-CBC', length: 256 }, true, ['encrypt', 'decrypt']);
+    }
+    /**
+     * Get crypto instance depending on the environment
+     * @return {Crypto}
+     * @private
+     */
+    static getCrypto() {
+        if (typeof this.crypto !== 'undefined') {
+            return this.crypto;
+        }
+        if (typeof Uint8Array === 'undefined') {
+            throw new Error('Unsupported environment, Uint8Array missing');
+        }
+        if (typeof TextEncoder === 'undefined') {
+            throw new Error('Unsupported environment, TextEncoder missing');
+        }
+        if (typeof window === 'undefined') {
+            // @ts-ignore
+            if (typeof module !== 'undefined' && module.exports) {
+                // @ts-ignore
+                this.crypto = require('node:crypto');
+                return this.crypto;
+            }
+        }
+        if (!window.crypto) {
+            throw new Error('Unsupported environment, window.crypto missing');
+        }
+        this.crypto = window.crypto;
+        return this.crypto;
+    }
+    /**
+     * Convert given byte array to visual hex representation with leading 0x
+     * @param {Uint8Array} byteArray
+     * @return {string}
+     */
+    static byteArrayToHex(byteArray) {
+        return Array.from(byteArray).map(x => x.toString(16).padStart(2, '0')).join('');
+    }
+    /**
+     * Convert a hex string into given byte array to visual hex representation
+     * @param {str} str
+     * @return {string}
+     */
+    static hexToByteArray(str) {
+        return Uint8Array.from((str.match(/.{1,2}/g) || []).map((byte) => parseInt(byte, 16)));
+    }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = JsAesPhp
+}

package.json

@@ -0,0 +1,25 @@
+{
+  "name": "js-aes-php",
+  "version": "1.0.1",
+  "description": "Slim native AES encryption/decryption on client side with Javascript and on server side with PHP",
+  "scripts": {
+    "dist": "node ./node_modules/typescript/bin/tsc --project tsconfig.json && node build/dist.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brainfoolong/js-aes-php.git"
+  },
+  "author": "BrainFooLong (Roland Eigelsreiter)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/brainfoolong/js-aes-php/issues"
+  },
+  "homepage": "https://github.com/brainfoolong/js-aes-php",
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=15.0.0"
+  },
+  "main": "dist/js-aes-php.js"
+}