From 802cd3bbf83e171b7377d9a2d9601f56b36b51a9 Mon Sep 17 00:00:00 2001 From: Ziga Zajc Date: Thu, 15 Aug 2024 22:38:26 +0200 Subject: [PATCH] Improve JSDocs --- jsr.json | 2 +- module/xchacha20.d.ts | 138 ++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- src/xchacha20.ts | 138 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 278 insertions(+), 2 deletions(-) diff --git a/jsr.json b/jsr.json index becc796..75361fa 100644 --- a/jsr.json +++ b/jsr.json @@ -1,5 +1,5 @@ { "name": "@rabbit-company/xchacha20", - "version": "2.1.0", + "version": "2.2.0", "exports": "./src/xchacha20.ts" } diff --git a/module/xchacha20.d.ts b/module/xchacha20.d.ts index 58f5b73..be7677f 100644 --- a/module/xchacha20.d.ts +++ b/module/xchacha20.d.ts @@ -1,24 +1,162 @@ +/** + * Class representing the XChaCha20 encryption and decryption algorithm. + * This class provides methods for encoding, encrypting, decrypting, and handling text and keys. + */ declare class XChaCha20 { + /** + * The keystream generated during encryption/decryption. + * @type {number[]} + */ keystream: number[]; + /** + * The encrypted text as an array of character codes. + * @type {number[]} + */ encryptedText: number[]; + /** + * The decrypted plain text as an array of character codes. + * @type {number[]} + */ plaintext: number[]; + /** + * The nonce used in the encryption process. + * @type {number[]} + */ nonce: number[]; + /** + * Constructs a new XChaCha20 instance. + */ constructor(); + /** + * Rotates bits to the left by a given number of positions. + * + * @param {number} a - The number to rotate. + * @param {number} b - The number of positions to rotate. + * @returns {number} The result after rotating left. + */ rotateleft: (a: number, b: number) => number; + /** + * Combines four bytes into a 32-bit little-endian integer. + * + * @param {number} a - The first byte. + * @param {number} b - The second byte. + * @param {number} c - The third byte. + * @param {number} d - The fourth byte. + * @returns {number} The resulting 32-bit integer. + */ le32: (a: number, b: number, c: number, d: number) => number; + /** + * Converts a string to an array of numbers based on character codes. + * + * @param {string} data - The string to convert. + * @returns {number[]} The resulting array of numbers. + */ int2(data: string): number[]; + /** + * Performs the quarter round operation in the ChaCha20 algorithm. + * + * @param {Uint32Array} state - The state to modify. + * @param {number} a - Index of the first element in the quarter round. + * @param {number} b - Index of the second element in the quarter round. + * @param {number} c - Index of the third element in the quarter round. + * @param {number} d - Index of the fourth element in the quarter round. + * @returns {void} + */ Qround(state: Uint32Array, a: number, b: number, c: number, d: number): void; + /** + * Applies the ChaCha20 inner block operation. + * + * @param {Uint32Array} state - The state to modify. + * @returns {void} + */ Inner_Block(state: Uint32Array): void; + /** + * Generates a block for the ChaCha20 encryption function. + * + * @param {number[]} key - The encryption key. + * @param {number[]} nonce - The nonce value. + * @param {number} block_counter - The block counter. + * @returns {number[]} The generated block. + */ Chacha20_BlockFunction(key: number[], nonce: number[], block_counter: number): number[]; + /** + * Generates a block for the HChaCha20 encryption function. + * + * @param {number[]} key - The encryption key. + * @param {number[]} nonce - The nonce value. + * @returns {number[]} The generated block. + */ HChacha20_BlockFunction(key: number[], nonce: number[]): number[]; + /** + * Encrypts plaintext using the ChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {number} counter - The block counter. + * @param {number[]} nonce - The nonce value. + * @param {number[]} plaintext - The plaintext to encrypt. + * @returns {void} + */ chacha20_encrypt(key: number[], counter: number, nonce: number[], plaintext: number[]): void; + /** + * Decrypts encrypted text using the ChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {number} counter - The block counter. + * @param {number[]} nonce - The nonce value. + * @param {number[]} eT - The encrypted text. + * @returns {void} + */ chacha20_decrypt(key: number[], counter: number, nonce: number[], eT: number[]): void; + /** + * Decrypts a message using the XChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {string} encryptedText - The encrypted text in base64 format. + * @returns {void} + */ xchacha20_decrypt(key: number[], encryptedText: string): void; + /** + * Encrypts a message using the XChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {number[]} nonce - The nonce value. + * @param {number[]} plaintext - The plaintext to encrypt. + * @returns {void} + */ xchacha20_encrypt(key: number[], nonce: number[], plaintext: number[]): void; + /** + * Converts an array of numbers representing character codes into a string. + * + * @param {number[]} data - The array of numbers to convert. + * @returns {string} The resulting string. + */ private static convertToText; + /** + * Encodes a given string into its hexadecimal representation. + * + * @param {string} data - The string to encode. + * @returns {any[]} The hexadecimal encoded string as an array of strings. + */ private static hexEncode; + /** + * Encodes a given string into base64 format, supporting Unicode characters. + * + * @param {string} str - The string to encode. + * @returns {string} The base64 encoded string. + */ private static b64EncodeUnicode; + /** + * Decodes a base64 string, supporting Unicode characters. + * + * @param {string} str - The base64 encoded string. + * @returns {string} The decoded string. + */ private static b64DecodeUnicode; + /** + * Generates a random nonce for use with the XChaCha20 algorithm. + * + * @returns {Uint8Array} A randomly generated nonce. + */ private static randomNonce; /** * Encrypts a given message using the XChaCha20 encryption algorithm. diff --git a/package.json b/package.json index 10102ef..afa3baa 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@rabbit-company/xchacha20", - "version": "2.1.0", + "version": "2.2.0", "description": "XChaCha20 encryption", "main": "./module/xchacha20.js", "browser": "./module/xchacha20.js", diff --git a/src/xchacha20.ts b/src/xchacha20.ts index e33aa94..87c90cc 100644 --- a/src/xchacha20.ts +++ b/src/xchacha20.ts @@ -1,9 +1,32 @@ +/** + * Class representing the XChaCha20 encryption and decryption algorithm. + * This class provides methods for encoding, encrypting, decrypting, and handling text and keys. + */ export default class XChaCha20 { + /** + * The keystream generated during encryption/decryption. + * @type {number[]} + */ keystream: number[]; + /** + * The encrypted text as an array of character codes. + * @type {number[]} + */ encryptedText: number[]; + /** + * The decrypted plain text as an array of character codes. + * @type {number[]} + */ plaintext: number[]; + /** + * The nonce used in the encryption process. + * @type {number[]} + */ nonce: number[]; + /** + * Constructs a new XChaCha20 instance. + */ constructor() { this.keystream = []; this.encryptedText = []; @@ -11,14 +34,36 @@ export default class XChaCha20 { this.nonce = []; } + /** + * Rotates bits to the left by a given number of positions. + * + * @param {number} a - The number to rotate. + * @param {number} b - The number of positions to rotate. + * @returns {number} The result after rotating left. + */ rotateleft = (a: number, b: number): number => { return (a << b) | (a >>> (32 - b)); }; + /** + * Combines four bytes into a 32-bit little-endian integer. + * + * @param {number} a - The first byte. + * @param {number} b - The second byte. + * @param {number} c - The third byte. + * @param {number} d - The fourth byte. + * @returns {number} The resulting 32-bit integer. + */ le32 = (a: number, b: number, c: number, d: number): number => { return (a ^ (b << 8) ^ (c << 16) ^ (d << 24)) >>> 0; }; + /** + * Converts a string to an array of numbers based on character codes. + * + * @param {string} data - The string to convert. + * @returns {number[]} The resulting array of numbers. + */ int2(data: string): number[] { let result: number[] = []; for (let i = 0; i < data.length; i++) { @@ -28,6 +73,16 @@ export default class XChaCha20 { return result; } + /** + * Performs the quarter round operation in the ChaCha20 algorithm. + * + * @param {Uint32Array} state - The state to modify. + * @param {number} a - Index of the first element in the quarter round. + * @param {number} b - Index of the second element in the quarter round. + * @param {number} c - Index of the third element in the quarter round. + * @param {number} d - Index of the fourth element in the quarter round. + * @returns {void} + */ Qround(state: Uint32Array, a: number, b: number, c: number, d: number): void { state[a] += state[b]; state[d] ^= state[a]; @@ -47,6 +102,12 @@ export default class XChaCha20 { state[d] >>>= 0; } + /** + * Applies the ChaCha20 inner block operation. + * + * @param {Uint32Array} state - The state to modify. + * @returns {void} + */ Inner_Block(state: Uint32Array): void { // column_QuarterRounds this.Qround(state, 0, 4, 8, 12); @@ -60,6 +121,14 @@ export default class XChaCha20 { this.Qround(state, 3, 4, 9, 14); } + /** + * Generates a block for the ChaCha20 encryption function. + * + * @param {number[]} key - The encryption key. + * @param {number[]} nonce - The nonce value. + * @param {number} block_counter - The block counter. + * @returns {number[]} The generated block. + */ Chacha20_BlockFunction(key: number[], nonce: number[], block_counter: number): number[] { let state: number[] = []; // Constant @@ -100,6 +169,13 @@ export default class XChaCha20 { return Serialized_Block; } + /** + * Generates a block for the HChaCha20 encryption function. + * + * @param {number[]} key - The encryption key. + * @param {number[]} nonce - The nonce value. + * @returns {number[]} The generated block. + */ HChacha20_BlockFunction(key: number[], nonce: number[]): number[] { let state: number[] = []; // Constant @@ -144,6 +220,15 @@ export default class XChaCha20 { return Serialized_Block; } + /** + * Encrypts plaintext using the ChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {number} counter - The block counter. + * @param {number[]} nonce - The nonce value. + * @param {number[]} plaintext - The plaintext to encrypt. + * @returns {void} + */ chacha20_encrypt(key: number[], counter: number, nonce: number[], plaintext: number[]): void { let keystream: number[] = []; keystream.push(...this.Chacha20_BlockFunction(key, nonce, counter)); @@ -166,6 +251,15 @@ export default class XChaCha20 { this.encryptedText = cipherText; } + /** + * Decrypts encrypted text using the ChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {number} counter - The block counter. + * @param {number[]} nonce - The nonce value. + * @param {number[]} eT - The encrypted text. + * @returns {void} + */ chacha20_decrypt(key: number[], counter: number, nonce: number[], eT: number[]): void { let keystream: number[] = []; keystream.push(...this.Chacha20_BlockFunction(key, nonce, counter)); @@ -186,6 +280,13 @@ export default class XChaCha20 { this.plaintext = pT; } + /** + * Decrypts a message using the XChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {string} encryptedText - The encrypted text in base64 format. + * @returns {void} + */ xchacha20_decrypt(key: number[], encryptedText: string): void { this.encryptedText = this.int2(XChaCha20.b64DecodeUnicode(encryptedText)); let nonce = this.encryptedText.slice(-24); @@ -197,6 +298,14 @@ export default class XChaCha20 { this.chacha20_decrypt(subkey, 0, chacha20_nonce, this.encryptedText); } + /** + * Encrypts a message using the XChaCha20 algorithm. + * + * @param {number[]} key - The encryption key. + * @param {number[]} nonce - The nonce value. + * @param {number[]} plaintext - The plaintext to encrypt. + * @returns {void} + */ xchacha20_encrypt(key: number[], nonce: number[], plaintext: number[]): void { let subkey = this.HChacha20_BlockFunction(key, nonce.slice(0, 16)); let chacha20_nonce = [0x00, 0x00, 0x00, 0x00]; @@ -204,6 +313,12 @@ export default class XChaCha20 { this.chacha20_encrypt(subkey, 0, chacha20_nonce, plaintext); } + /** + * Converts an array of numbers representing character codes into a string. + * + * @param {number[]} data - The array of numbers to convert. + * @returns {string} The resulting string. + */ private static convertToText(data: number[]): string { let text = ""; for (let i = 0; i < data.length; i++) { @@ -212,6 +327,12 @@ export default class XChaCha20 { return text; } + /** + * Encodes a given string into its hexadecimal representation. + * + * @param {string} data - The string to encode. + * @returns {any[]} The hexadecimal encoded string as an array of strings. + */ private static hexEncode(data: string): any[] { let result: string[] = []; for (let i = 0; i < data.length; i++) { @@ -220,6 +341,12 @@ export default class XChaCha20 { return result; } + /** + * Encodes a given string into base64 format, supporting Unicode characters. + * + * @param {string} str - The string to encode. + * @returns {string} The base64 encoded string. + */ private static b64EncodeUnicode(str: string): string { return btoa( encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function toSolidBytes(match, p1) { @@ -228,6 +355,12 @@ export default class XChaCha20 { ); } + /** + * Decodes a base64 string, supporting Unicode characters. + * + * @param {string} str - The base64 encoded string. + * @returns {string} The decoded string. + */ private static b64DecodeUnicode(str: string): string { return decodeURIComponent( atob(str) @@ -239,6 +372,11 @@ export default class XChaCha20 { ); } + /** + * Generates a random nonce for use with the XChaCha20 algorithm. + * + * @returns {Uint8Array} A randomly generated nonce. + */ private static randomNonce(): Uint8Array { let rand_n = new Uint8Array(24); crypto.getRandomValues(rand_n);