Improve readme, update xml-crypto, fix ci, replace deprecated crypto methods and make add compatibility with NodeJS 22.

.github/workflows/CI.yml

@@ -11,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [ 18, 19, 20 ]
+        node: [ 18, 20, 22 ]
     name: Node.js ${{ matrix.node }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
       - run: npm ci

README.md

@@ -15,30 +15,55 @@
 <a href='https://coveralls.io/github/eCollect/node-ebics-client?branch=master' title="Coverage Status"><img src='https://coveralls.io/repos/github/eCollect/node-ebics-client/badge.svg?branch=master' alt='Coverage Status' /></a>
 </p>
 
-Pure node.js ( >=8 ) implementation of [EBICS](https://en.wikipedia.org/wiki/Electronic_Banking_Internet_Communication_Standard) ( Electronic Banking Internet Communication ).
+Pure Node.js (>= 16) implementation of [EBICS](https://en.wikipedia.org/wiki/Electronic_Banking_Internet_Communication_Standard) (Electronic Banking Internet Communication).
 
-The client is aimed to be 100% [ISO 20022](https://www.iso20022.org) compliant, and supports the complete initializations process ( INI, HIA, HPB orders ) and HTML letter generation.
+The client is aimed to be 100% [ISO 20022](https://www.iso20022.org) compliant, and supports the complete initializations process (INI, HIA, HPB orders) and HTML letter generation.
 
+## Usage
+
+For examples on how to use this library, take a look at the [examples](https://github.com/node-ebics/node-ebics-client/tree/master/examples).
+
+### A note on recent Node.js versions
+
+The latest Node.js versions don't support `RSA_PKCS1_PADDING` for private decryption for security reasons, throwing an error like _TypeError: RSA_PKCS1_PADDING is no longer supported for private decryption, this can be reverted with --security-revert=CVE-2023-46809_.
+
+EBICS requires this mode, so in order for this library to work, add the following parameter when starting Node.js: `--security-revert=CVE-2023-46809`
+
+### Initialization
+
+1. Create a configuration (see [example configs](https://github.com/node-ebics/node-ebics-client/tree/master/examples/config)) with the EBICS credentials you received from your bank and name it in this schema: `config.<environment>.<bank>[.<entity>].json` (the entity is optional).
+
+    - The fields `url`, `partnerId`, `userId`, `hostId` are provided by your bank.
+    - The `passphrase` is used to encrypt the keys file, which will be stored at the `storageLocation`.
+    - The `bankName` and `bankShortName` are used internally for creating files and identifying the bank to you.
+    - The `languageCode` is used when creating the Initialization Letter and can be either `de`, `en`, or `fr`.
+    - You can chose any environment, bank and, optionally, entity name. Entities are useful if you have multiple EBICS users for the same bank account.
+
+2. Run `node examples/initialize.js <environment> <bank> [entity]` to generate your key pair and perform the INI and HIA orders (ie. send the public keys to your bank)  
+   The generated keys are stored in the file specified in your config and encrypted with the specified passphrase.
+3. Run `node examples/bankLetter.js <environment> <bank> [entity]` to generate the Initialization Letter
+4. Print the letter, sign it and send it to your bank. Wait for them to activate your EBICS account.
+5. Download the bank keys by running `node examples/save-bank-keys.js <environment> <bank> [entity]`
+
+If all these steps were executed successfully, you can now do all things EBICS, like fetching bank statements by running `node examples/send-sta-order.js <environment> <bank> [entity]`, or actually use this library in your custom banking applications.
 
 ## Supported Banks
-The client is currently tested and verified to work with the following banks:
 
-* [Credit Suisse (Schweiz) AG](https://www.credit-suisse.com/ch/en.html)
-* [Zürcher Kantonalbank](https://www.zkb.ch/en/lg/ew.html)
-* [Raiffeisen Schweiz](https://www.raiffeisen.ch/rch/de.html)
-* [BW Bank](https://www.bw-bank.de/de/home.html)
-* [Bank GPB International S.A.](https://gazprombank.lu/e-banking)
-* [Bank GPB AO](https://gazprombank.ru/)
-* [J.P. Morgan](https://www.jpmorgan.com/)
+The client is currently tested and verified to work with the following banks:
 
+-   [Credit Suisse (Schweiz) AG](https://www.credit-suisse.com/ch/en.html)
+-   [Zürcher Kantonalbank](https://www.zkb.ch/en/lg/ew.html)
+-   [Raiffeisen Schweiz](https://www.raiffeisen.ch/rch/de.html)
+-   [BW Bank](https://www.bw-bank.de/de/home.html)
+-   [Bank GPB International S.A.](https://gazprombank.lu/e-banking)
+-   [Bank GPB AO](https://gazprombank.ru/)
+-   [J.P. Morgan](https://www.jpmorgan.com/)
 
 ## Inspiration
 
 The basic concept of this library was inspired by the [EPICS](https://github.com/railslove/epics) library from the Railslove Team.
 
-
 ## Copyright
 
 Copyright: Dimitar Nanov, 2019-2022.  
 Licensed under the [MIT](LICENSE) license.
-

examples/bankLetter.js

@@ -10,7 +10,7 @@ const os = require('os');
 const config = require('./loadConfig')();
 const client = require('./getClient')(config);
 const bankName = client.bankName;
-const template = fs.readFileSync("../templates/ini_"+client.languageCode+".hbs", { encoding: 'utf8'});
+const template = fs.readFileSync("./templates/ini_"+client.languageCode+".hbs", { encoding: 'utf8'});
 const bankLetterFile = path.join("./", "bankLetter_"+client.bankShortName+"_"+client.languageCode+".html");
 
 const letter = new ebics.BankLetter({ client, bankName, template });

examples/getClient.js

@@ -10,12 +10,14 @@ module.exports = ({
 	userId,
 	hostId,
 	passphrase,
+	iv,
 	keyStoragePath,
 } = loadConfig()) => new Client({
 	url,
 	partnerId,
 	userId,
 	hostId,
 	passphrase,
+	iv,
 	keyStorage: fsKeysStorage(keyStoragePath),
 });

lib/Client.js

@@ -43,15 +43,15 @@ const stringifyKeys = (keys) => {
  * @property {string} partnerId - PARTNERID provided by the bank
  * @property {string} hostId - HOSTID provided by the bank
  * @property {string} userId - USERID provided by the bank
- * @property {string} passphrase - passphrase for keys encryption
+ * @property {string|Buffer} passphrase - passphrase or key for keys encryption
+ * @property {string|Buffer} iv - Initialization Vector for keys encryption
  * @property {KeyStorage} keyStorage - keyStorage implementation
  * @property {object} [tracesStorage] - traces (logs) storage implementation
  * @property {string} bankName - Full name of the bank to be used in the bank INI letters.
  * @property {string} bankShortName - Short name of the bank to be used in folders, filenames etc.
  * @property {string} languageCode - Language code to be used in the bank INI letters ("de", "en" and "fr" are currently supported).
  * @property {string} storageLocation - Location where to store the files that are downloaded. This can be a network share for example.
  */
-
 module.exports = class Client {
 	/**
 	 *Creates an instance of Client.
@@ -63,6 +63,7 @@ module.exports = class Client {
 		userId,
 		hostId,
 		passphrase,
+		iv,
 		keyStorage,
 		tracesStorage,
 		bankName,
@@ -88,7 +89,7 @@ module.exports = class Client {
 		this.userId = userId;
 		this.hostId = hostId;
 		this.keyStorage = keyStorage;
-		this.keyEncryptor = defaultKeyEncryptor({ passphrase });
+		this.keyEncryptor = defaultKeyEncryptor({ passphrase, iv });
 		this.tracesStorage = tracesStorage || null;
 		this.bankName = bankName || 'Dummy Bank Full Name';
 		this.bankShortName = bankShortName || 'BANKSHORTCODE';
@@ -216,26 +217,25 @@ module.exports = class Client {
 					.persist();
 
 			rock({
-					method: 'POST',
-					url: this.url,
-					body: r,
-					headers: { 'content-type': 'text/xml;charset=UTF-8' },
-				},
-				(err, res, data) => {
-					if (err) reject(err);
-
-					const ebicsResponse = response.version(version)(data.toString('utf-8'), keys);
-
-					if (this.tracesStorage)
-						this.tracesStorage
-							.label(`RESPONSE.${order.orderDetails.OrderType}`)
-							.connect()
-							.data(ebicsResponse.toXML())
-							.persist();
-
-					resolve(ebicsResponse);
-				},
-			);
+				method: 'POST',
+				url: this.url,
+				body: r,
+				headers: { 'content-type': 'text/xml;charset=UTF-8' },
+			},
+			(err, res, data) => {
+				if (err) reject(err);
+
+				const ebicsResponse = response.version(version)(data.toString('utf-8'), keys);
+
+				if (this.tracesStorage)
+					this.tracesStorage
+						.label(`RESPONSE.${order.orderDetails.OrderType}`)
+						.connect()
+						.data(ebicsResponse.toXML())
+						.persist();
+
+				resolve(ebicsResponse);
+			});
 		});
 	}
 
@@ -250,7 +250,6 @@ module.exports = class Client {
 	async keys() {
 		try {
 			const keysString = await this._readKeys();
-
 			return new Keys(JSON.parse(this.keyEncryptor.decrypt(keysString)));
 		} catch (err) {
 			return null;

lib/crypto/Crypto.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const NodeRSA = require('node-rsa');
 
 const BigNumber = require('./BigNumber.js');
 const mgf1 = require('./MGF1');
@@ -54,10 +55,14 @@ module.exports = class Crypto {
 	}
 
 	static privateDecrypt(key, data) {
-		return crypto.privateDecrypt({
-			key: key.toPem(),
-			padding: crypto.constants.RSA_PKCS1_PADDING,
-		}, data);
+		const keyRSA = new NodeRSA(
+			key.toPem(),
+			'pkcs1-private-pem', {
+				encryptionScheme: 'pkcs1',
+				environment: 'browser', // would use the crypto module by default, which blocks pkcs1
+			},
+		);
+		return keyRSA.decrypt(data);
 	}
 
 	static privateSign(key, data, outputEncoding = 'base64') {

lib/crypto/encryptDecrypt.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const createKeyAndIv = (passphrase) => {
+	// this generates a 256-bit key and a 128-bit iv for aes-256-cbc
+	// just like nodejs's deprecated/removed crypto.createCipher would
+	const a = crypto.createHash('md5').update(passphrase).digest();
+	const b = crypto
+		.createHash('md5')
+		.update(Buffer.concat([a, Buffer.from(passphrase)]))
+		.digest();
+	const c = crypto
+		.createHash('md5')
+		.update(Buffer.concat([b, Buffer.from(passphrase)]))
+		.digest();
+	const bytes = Buffer.concat([a, b, c]);
+	const key = bytes.subarray(0, 32);
+	const iv = bytes.subarray(32, 48);
+	return { key, iv };
+};
+
+const encrypt = (data, algorithm, passphrase, iv) => {
+	let cipher;
+	if (iv) {
+		cipher = crypto.createCipheriv(algorithm, passphrase, iv);
+	} else {
+		console.warn(
+			'[Deprecation notice] No IV provided, falling back to legacy key derivation.\n'
+            + 'This will be removed in a future major release. You should encrypt your keys with a proper key and IV.',
+		);
+		if (crypto.createCipher) {
+			// nodejs < 22
+			cipher = crypto.createCipher(algorithm, passphrase);
+		} else {
+			const { key, iv: generatedIv } = createKeyAndIv(passphrase);
+			cipher = crypto.createCipheriv(algorithm, key, generatedIv);
+		}
+	}
+	const encrypted = cipher.update(data, 'utf8', 'hex') + cipher.final('hex');
+	return Buffer.from(encrypted).toString('base64');
+};
+
+const decrypt = (data, algorithm, passphrase, iv) => {
+	data = Buffer.from(data, 'base64').toString();
+	let decipher;
+	if (iv) {
+		decipher = crypto.createDecipheriv(algorithm, passphrase, iv);
+	} else {
+		console.warn(
+			'[Deprecation notice] No IV provided, falling back to legacy key derivation.\n'
+			+ 'This will be removed in a future major release. You should re-encrypt your keys with a proper key and IV.',
+		);
+		if (crypto.createDecipher) {
+			// nodejs < 22
+			decipher = crypto.createDecipher(algorithm, passphrase);
+		} else {
+			const { key, iv: generatedIv } = createKeyAndIv(passphrase);
+			decipher = crypto.createDecipheriv(algorithm, key, generatedIv);
+		}
+	}
+	const decrypted = decipher.update(data, 'hex', 'utf8') + decipher.final('utf8');
+	return decrypted;
+};
+
+module.exports = { encrypt, decrypt };

lib/keymanagers/KeysManager.js

@@ -1,24 +1,8 @@
 'use strict';
 
-const crypto = require('crypto');
-
+const { encrypt, decrypt } = require('../crypto/encryptDecrypt');
 const Keys = require('./Keys');
 
-const encrypt = (data, algorithm, passphrase) => {
-	const cipher = crypto.createCipher(algorithm, passphrase);
-	const encrypted = cipher.update(data, 'utf8', 'hex') + cipher.final('hex');
-
-	return Buffer.from(encrypted).toString('base64');
-};
-const decrypt = (data, algorithm, passphrase) => {
-	data = (Buffer.from(data, 'base64')).toString();
-
-	const decipher = crypto.createDecipher(algorithm, passphrase);
-	const decrypted = decipher.update(data, 'hex', 'utf8') + decipher.final('utf8');
-
-	return decrypted;
-};
-
 module.exports = (keysStorage, passphrase, algorithm = 'aes-256-cbc') => {
 	const storage = keysStorage;
 	const pass = passphrase;

lib/keymanagers/defaultKeyEncryptor.js

@@ -1,24 +1,9 @@
 'use strict';
 
-const crypto = require('crypto');
+const { encrypt, decrypt } = require('../crypto/encryptDecrypt');
 
-const encrypt = (data, algorithm, passphrase) => {
-	const cipher = crypto.createCipher(algorithm, passphrase);
-	const encrypted = cipher.update(data, 'utf8', 'hex') + cipher.final('hex');
-	return Buffer.from(encrypted).toString('base64');
-};
-const decrypt = (data, algorithm, passphrase) => {
-	data = (Buffer.from(data, 'base64')).toString();
-	const decipher = crypto.createDecipher(algorithm, passphrase);
-	const decrypted = decipher.update(data, 'hex', 'utf8') + decipher.final('utf8');
 
-	return decrypted;
-};
-
-module.exports = ({
-	passphrase,
-	algorithm = 'aes-256-cbc',
-}) => ({
-	encrypt: data => encrypt(data, algorithm, passphrase),
+module.exports = ({ passphrase, iv, algorithm = 'aes-256-cbc' }) => ({
+	encrypt: data => encrypt(data, algorithm, passphrase, iv),
 	decrypt: data => decrypt(data, algorithm, passphrase),
 });