react-native-des-machine 0.1.1 → 1.0.0

package/README.md

@@ -10,9 +10,11 @@ A React Native TurboModule that provides DES (Data Encryption Standard) encrypti
 ## Features
 
 - DES encryption and decryption
+- **Class-based API** - Create multiple independent instances with different configurations
 - Multiple cipher modes: ECB, CBC, CFB, OFB, CTR
 - Multiple padding schemes: PKCS7, ISO10126, Zero, None
 - Output formats: Base64, Hexadecimal
+- **Custom IV support** - Provide your own Initialization Vector
 - Native implementation for both iOS and Android
 - TurboModule support for improved performance
 - Pre-built options arrays for easy UI integration
@@ -54,23 +56,23 @@ No additional setup required. The library auto-links on Android.
 
 ## Usage
 
-### Basic Example
+### Basic Example - Using the DesMachine Class
 
 ```typescript
-import { setMachineParams, encrypt, decrypt } from 'react-native-des-machine';
+import { DesMachine } from 'react-native-des-machine';
 
-// Initialize the DES machine with your encryption key
-setMachineParams({
+// Create a DES machine instance with your encryption key
+const machine = new DesMachine({
   key: 'mySecretKey123', // minimum 8 characters
 });
 
 // Encrypt text
-const encrypted = encrypt('Hello World!');
+const encrypted = machine.encrypt('Hello World!');
 console.log('Encrypted:', encrypted);
 // Output: "Encrypted: 2jmj7l5rSw0yVb/vlWAYkK/YBwk="
 
 // Decrypt text
-const decrypted = decrypt(encrypted);
+const decrypted = machine.decrypt(encrypted);
 console.log('Decrypted:', decrypted);
 // Output: "Decrypted: Hello World!"
 ```
@@ -78,34 +80,96 @@ console.log('Decrypted:', decrypted);
 ### Advanced Configuration
 
 ```typescript
-import {
-  setMachineParams,
-  encrypt,
-  decrypt,
-  Mode,
-  Padding,
-  Format,
-} from 'react-native-des-machine';
+import { DesMachine, Mode, Padding, Format } from 'react-native-des-machine';
 
-// Configure with custom mode, padding, and output format
-setMachineParams({
+// Create a machine with custom mode, padding, and output format
+const machine = new DesMachine({
   key: 'mySecretKey123',
   mode: Mode.CBC, // Cipher Block Chaining mode
   padding: Padding.PKCS7, // PKCS7 padding
   outputFormat: Format.HEX, // Hexadecimal output
 });
 
-const encrypted = encrypt('Sensitive data');
+const encrypted = machine.encrypt('Sensitive data');
 console.log('Encrypted (hex):', encrypted);
-// Output: "Encrypted (hex): 4a6f686e446f65..."
 
-const decrypted = decrypt(encrypted);
+const decrypted = machine.decrypt(encrypted);
 console.log('Decrypted:', decrypted);
 ```
 
+### Using Custom Initialization Vector (IV)
+
+For non-ECB modes, you can provide a custom IV:
+
+```typescript
+import { DesMachine, Mode } from 'react-native-des-machine';
+
+const machine = new DesMachine({
+  key: 'mySecretKey123',
+  iv: 'custom88', // Exactly 8 characters for DES
+  mode: Mode.CBC,
+});
+
+const encrypted = machine.encrypt('Secret message');
+const decrypted = machine.decrypt(encrypted);
+```
+
+> **Note:** If `iv` is not provided for non-ECB modes, the first 8 bytes of the key are used as the IV.
+
+### Multiple Instances with Different Configurations
+
+One of the key features is the ability to create multiple independent instances:
+
+```typescript
+import { DesMachine, Mode, Format } from 'react-native-des-machine';
+
+// Machine for API communication (Base64 output)
+const apiMachine = new DesMachine({
+  key: 'apiSecretKey',
+  mode: Mode.CBC,
+  outputFormat: Format.BASE64,
+});
+
+// Machine for local storage (Hex output)
+const storageMachine = new DesMachine({
+  key: 'storageKey1',
+  mode: Mode.ECB,
+  outputFormat: Format.HEX,
+});
+
+// Use them independently
+const apiData = apiMachine.encrypt('API payload');
+const storageData = storageMachine.encrypt('Local data');
+```
+
+### Quick Functions for One-off Operations
+
+For simple one-time encryption/decryption without creating an instance:
+
+```typescript
+import { encrypt, decrypt } from 'react-native-des-machine';
+
+// Encrypt with params
+const encrypted = encrypt({ key: 'mySecretKey123' }, 'Hello World');
+
+// Decrypt with same params
+const decrypted = decrypt({ key: 'mySecretKey123' }, encrypted);
+```
+
+### Factory Function
+
+Alternative way to create instances:
+
+```typescript
+import { createDesMachine } from 'react-native-des-machine';
+
+const machine = createDesMachine({ key: 'mySecretKey123' });
+const encrypted = machine.encrypt('Hello');
+```
+
 ### Using Pre-built Options for UI
 
-The library exports pre-built option arrays that can be used directly with dropdown/picker components:
+The library exports pre-built option arrays for building UI components:
 
 ```typescript
 import {
@@ -131,36 +195,101 @@ import {
 </Picker>;
 ```
 
+### React Hook Example
+
+```typescript
+import { useMemo } from 'react';
+import { DesMachine, Mode, Padding, Format } from 'react-native-des-machine';
+import type {
+  ModeEncryptionType,
+  PaddingEncryptionType,
+  OutputFormatType,
+} from 'react-native-des-machine';
+
+function useDesMachine(
+  key: string,
+  mode: ModeEncryptionType = Mode.ECB,
+  padding: PaddingEncryptionType = Padding.PKCS7,
+  outputFormat: OutputFormatType = Format.BASE64
+) {
+  const machine = useMemo(() => {
+    if (key.length < 8) return null;
+    try {
+      return new DesMachine({ key, mode, padding, outputFormat });
+    } catch {
+      return null;
+    }
+  }, [key, mode, padding, outputFormat]);
+
+  return machine;
+}
+
+// Usage in component
+function MyComponent() {
+  const [key, setKey] = useState('defaultKey');
+  const machine = useDesMachine(key);
+
+  const handleEncrypt = (text: string) => {
+    if (!machine) {
+      Alert.alert('Error', 'Invalid key');
+      return;
+    }
+    return machine.encrypt(text);
+  };
+}
+```
+
 ## API Reference
 
-### Functions
+### DesMachine Class
+
+The main class for DES encryption and decryption.
+
+#### Constructor
+
+```typescript
+new DesMachine(params: DesMachineParams)
+```
+
+Creates a new DES machine instance.
 
-#### `setMachineParams(params: DesMachineParams): void`
+**Throws:**
 
-Initialize the DES machine with encryption parameters. Must be called before `encrypt()` or `decrypt()`.
+- `Error` if key is missing or less than 8 characters
+- `Error` if iv is provided but not exactly 8 characters
 
-| Parameter      | Type                    | Required | Default    | Description                           |
-| -------------- | ----------------------- | -------- | ---------- | ------------------------------------- |
-| `key`          | `string`                | Yes      | -          | Encryption key (minimum 8 characters) |
-| `mode`         | `ModeEncryptionType`    | No       | `'ECB'`    | Cipher mode                           |
-| `padding`      | `PaddingEncryptionType` | No       | `'PKCS7'`  | Padding scheme                        |
-| `outputFormat` | `OutputFormatType`      | No       | `'BASE64'` | Output encoding format                |
+#### Methods
 
-#### `encrypt(text: string): string`
+| Method                 | Parameters                  | Returns            | Description                        |
+| ---------------------- | --------------------------- | ------------------ | ---------------------------------- |
+| `encrypt(text)`        | `text: string`              | `string`           | Encrypt plaintext                  |
+| `decrypt(text)`        | `text: string`              | `string`           | Decrypt ciphertext                 |
+| `getParams()`          | -                           | `DesMachineParams` | Get current params (key/iv masked) |
+| `updateParams(params)` | `Partial<DesMachineParams>` | `void`             | Update mode, padding, or format    |
 
-Encrypt plaintext using the configured DES parameters.
+### DesMachineParams
 
-- **Parameters:** `text` - The plaintext string to encrypt
-- **Returns:** Encrypted string in the configured output format
-- **Throws:** Error if `setMachineParams()` has not been called
+| Parameter      | Type                    | Required | Default    | Description                             |
+| -------------- | ----------------------- | -------- | ---------- | --------------------------------------- |
+| `key`          | `string`                | Yes      | -          | Encryption key (minimum 8 characters)   |
+| `iv`           | `string`                | No       | -          | Initialization Vector (exactly 8 chars) |
+| `mode`         | `ModeEncryptionType`    | No       | `'ECB'`    | Cipher mode                             |
+| `padding`      | `PaddingEncryptionType` | No       | `'PKCS7'`  | Padding scheme                          |
+| `outputFormat` | `OutputFormatType`      | No       | `'BASE64'` | Output encoding format                  |
 
-#### `decrypt(text: string): string`
+### Quick Functions
 
-Decrypt ciphertext using the configured DES parameters.
+#### `encrypt(params: DesMachineParams, text: string): string`
 
-- **Parameters:** `text` - The encrypted string to decrypt
-- **Returns:** Decrypted plaintext string
-- **Throws:** Error if `setMachineParams()` has not been called
+Quick encrypt without creating an instance.
+
+#### `decrypt(params: DesMachineParams, text: string): string`
+
+Quick decrypt without creating an instance.
+
+#### `createDesMachine(params: DesMachineParams): DesMachine`
+
+Factory function to create a DesMachine instance.
 
 ### Constants
 
@@ -192,8 +321,6 @@ Decrypt ciphertext using the configured DES parameters.
 
 ### Pre-built Options Arrays
 
-These arrays are useful for building UI components like dropdowns or pickers:
-
 | Export           | Type                                   | Description                 |
 | ---------------- | -------------------------------------- | --------------------------- |
 | `modeOptions`    | `OptionsList<ModeEncryptionType>[]`    | Mode options with labels    |
@@ -208,8 +335,10 @@ The library includes full TypeScript definitions:
 
 ```typescript
 import {
-  // Functions
-  setMachineParams,
+  // Main class
+  DesMachine,
+  createDesMachine,
+  // Quick functions
   encrypt,
   decrypt,
   // Constants
@@ -233,20 +362,22 @@ import type {
 
 ## Complete Exports
 
-| Export                  | Type     | Description                      |
-| ----------------------- | -------- | -------------------------------- |
-| `setMachineParams`      | Function | Initialize DES with parameters   |
-| `encrypt`               | Function | Encrypt plaintext                |
-| `decrypt`               | Function | Decrypt ciphertext               |
-| `Mode`                  | Constant | Cipher mode constants            |
-| `Padding`               | Constant | Padding scheme constants         |
-| `Format`                | Constant | Output format constants          |
-| `modeOptions`           | Array    | Pre-built mode options for UI    |
-| `paddingOptions`        | Array    | Pre-built padding options for UI |
-| `formatOptions`         | Array    | Pre-built format options for UI  |
-| `ModeEncryptionType`    | Type     | TypeScript type for modes        |
-| `PaddingEncryptionType` | Type     | TypeScript type for padding      |
-| `OutputFormatType`      | Type     | TypeScript type for formats      |
+| Export                  | Type     | Description                          |
+| ----------------------- | -------- | ------------------------------------ |
+| `DesMachine`            | Class    | Main class for encryption/decryption |
+| `createDesMachine`      | Function | Factory to create DesMachine         |
+| `encrypt`               | Function | Quick encrypt with params            |
+| `decrypt`               | Function | Quick decrypt with params            |
+| `Mode`                  | Constant | Cipher mode constants                |
+| `Padding`               | Constant | Padding scheme constants             |
+| `Format`                | Constant | Output format constants              |
+| `modeOptions`           | Array    | Pre-built mode options for UI        |
+| `paddingOptions`        | Array    | Pre-built padding options for UI     |
+| `formatOptions`         | Array    | Pre-built format options for UI      |
+| `DesMachineParams`      | Type     | TypeScript type for params           |
+| `ModeEncryptionType`    | Type     | TypeScript type for modes            |
+| `PaddingEncryptionType` | Type     | TypeScript type for padding          |
+| `OutputFormatType`      | Type     | TypeScript type for formats          |
 
 ## Security Notice
 
@@ -256,6 +387,10 @@ DES is considered cryptographically weak by modern standards due to its 56-bit k
 - Educational purposes
 - Low-security applications
 
+## Author
+
+- GitHub: [@NeRo8](https://github.com/NeRo8)
+
 ## Contributing
 
 - [Development workflow](CONTRIBUTING.md#development-workflow)

package/android/src/main/java/com/desmachine/DesMachineModule.kt

@@ -4,7 +4,6 @@ import android.util.Base64
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
 import javax.crypto.Cipher
-import javax.crypto.SecretKey
 import javax.crypto.SecretKeyFactory
 import javax.crypto.spec.DESKeySpec
 import javax.crypto.spec.IvParameterSpec
@@ -12,97 +11,100 @@ import javax.crypto.spec.IvParameterSpec
 class DesMachineModule(reactContext: ReactApplicationContext) :
   NativeDesMachineSpec(reactContext) {
 
-  private var secretKey: SecretKey? = null
-  private var mode: String = MODE_ECB
-  private var padding: String = PADDING_PKCS7
-  private var outputFormat: String = FORMAT_BASE64
-  private var ivSpec: IvParameterSpec? = null
-
   /**
-   * Set the DES machine parameters including key, mode, padding, and output format.
+   * Encrypt the provided plaintext using DES algorithm.
+   * Stateless operation - all parameters are passed with each call.
+   *
    * @param params ReadableMap containing:
    *   - key: String (required, minimum 8 characters)
    *   - mode: String (optional, default: ECB) - ECB, CBC, CFB, OFB, CTR
    *   - padding: String (optional, default: PKCS7) - PKCS7, ISO10126, ZERO, NONE
    *   - outputFormat: String (optional, default: BASE64) - BASE64, HEX
+   * @param text The plaintext to encrypt
+   * @return Encrypted string in the configured output format (BASE64 or HEX)
    */
-  override fun setMachineParams(params: ReadableMap) {
-    // Extract and validate key
-    val key = params.getString("key")
-      ?: throw IllegalArgumentException("Key is required")
-    require(key.length >= 8) { "DES key must be at least 8 characters long" }
-
-    // Extract optional parameters with defaults
-    mode = params.getString("mode") ?: MODE_ECB
-    padding = params.getString("padding") ?: PADDING_PKCS7
-    outputFormat = params.getString("outputFormat") ?: FORMAT_BASE64
+  override fun encrypt(params: ReadableMap, text: String): String {
+    val config = parseParams(params)
+    val cipher = createCipher(Cipher.ENCRYPT_MODE, config)
 
-    // Initialize secret key
-    val keyBytes = key.toByteArray(Charsets.UTF_8)
-    val desKeySpec = DESKeySpec(keyBytes)
-    val keyFactory = SecretKeyFactory.getInstance(DES_ALGORITHM)
-    secretKey = keyFactory.generateSecret(desKeySpec)
+    val inputBytes = applyPaddingIfNeeded(text.toByteArray(Charsets.UTF_8), config.padding)
+    val encryptedBytes = cipher.doFinal(inputBytes)
 
-    // Initialize IV for modes that require it (CBC, CFB, OFB, CTR)
-    if (mode != MODE_ECB) {
-      // Use first 8 bytes of key as IV (DES block size is 8 bytes)
-      val ivBytes = keyBytes.copyOf(8)
-      ivSpec = IvParameterSpec(ivBytes)
-    }
+    return formatOutput(encryptedBytes, config.outputFormat)
   }
 
   /**
-   * Encrypt the provided plaintext using DES algorithm.
-   * @param text The plaintext to encrypt
-   * @return Encrypted string in the configured output format (BASE64 or HEX)
+   * Decrypt the provided ciphertext using DES algorithm.
+   * Stateless operation - all parameters are passed with each call.
+   *
+   * @param params ReadableMap containing:
+   *   - key: String (required, minimum 8 characters)
+   *   - mode: String (optional, default: ECB) - ECB, CBC, CFB, OFB, CTR
+   *   - padding: String (optional, default: PKCS7) - PKCS7, ISO10126, ZERO, NONE
+   *   - outputFormat: String (optional, default: BASE64) - BASE64, HEX
+   * @param text Encrypted string in the configured format (BASE64 or HEX)
+   * @return Decrypted plaintext
    */
-  override fun encrypt(text: String): String {
-    val key = secretKey
-      ?: throw IllegalStateException("DES not initialized. Call setMachineParams() first.")
+  override fun decrypt(params: ReadableMap, text: String): String {
+    val config = parseParams(params)
+    val cipher = createCipher(Cipher.DECRYPT_MODE, config)
 
-    val transformation = buildTransformation()
-    val cipher = Cipher.getInstance(transformation)
+    val encryptedBytes = parseInput(text, config.outputFormat)
+    val decryptedBytes = cipher.doFinal(encryptedBytes)
 
-    if (mode == MODE_ECB) {
-      cipher.init(Cipher.ENCRYPT_MODE, key)
-    } else {
-      cipher.init(Cipher.ENCRYPT_MODE, key, ivSpec)
-    }
+    return String(removePaddingIfNeeded(decryptedBytes, config.padding), Charsets.UTF_8)
+  }
 
-    val inputBytes = applyPaddingIfNeeded(text.toByteArray(Charsets.UTF_8))
-    val encryptedBytes = cipher.doFinal(inputBytes)
+  /**
+   * Parse and validate parameters from ReadableMap.
+   */
+  private fun parseParams(params: ReadableMap): DesConfig {
+    val key = params.getString("key")
+      ?: throw IllegalArgumentException("Key is required")
+    require(key.length >= 8) { "DES key must be at least 8 characters long" }
 
-    return formatOutput(encryptedBytes)
+    val iv = params.getString("iv")
+    if (iv != null) {
+      require(iv.length == 8) { "IV must be exactly 8 characters long" }
+    }
+
+    return DesConfig(
+      key = key,
+      iv = iv,
+      mode = params.getString("mode") ?: MODE_ECB,
+      padding = params.getString("padding") ?: PADDING_PKCS7,
+      outputFormat = params.getString("outputFormat") ?: FORMAT_BASE64
+    )
   }
 
   /**
-   * Decrypt the provided ciphertext using DES algorithm.
-   * @param text Encrypted string in the configured format (BASE64 or HEX)
-   * @return Decrypted plaintext
+   * Create and initialize a cipher with the given configuration.
    */
-  override fun decrypt(text: String): String {
-    val key = secretKey
-      ?: throw IllegalStateException("DES not initialized. Call setMachineParams() first.")
+  private fun createCipher(opMode: Int, config: DesConfig): Cipher {
+    val keyBytes = config.key.toByteArray(Charsets.UTF_8)
+    val desKeySpec = DESKeySpec(keyBytes)
+    val keyFactory = SecretKeyFactory.getInstance(DES_ALGORITHM)
+    val secretKey = keyFactory.generateSecret(desKeySpec)
 
-    val transformation = buildTransformation()
+    val transformation = buildTransformation(config.mode, config.padding)
     val cipher = Cipher.getInstance(transformation)
 
-    if (mode == MODE_ECB) {
-      cipher.init(Cipher.DECRYPT_MODE, key)
+    if (config.mode == MODE_ECB) {
+      cipher.init(opMode, secretKey)
     } else {
-      cipher.init(Cipher.DECRYPT_MODE, key, ivSpec)
+      // Use provided IV or first 8 bytes of key as IV (DES block size is 8 bytes)
+      val ivBytes = config.iv?.toByteArray(Charsets.UTF_8) ?: keyBytes.copyOf(8)
+      val ivSpec = IvParameterSpec(ivBytes)
+      cipher.init(opMode, secretKey, ivSpec)
     }
 
-    val encryptedBytes = parseInput(text)
-    val decryptedBytes = cipher.doFinal(encryptedBytes)
-
-    return String(removePaddingIfNeeded(decryptedBytes), Charsets.UTF_8)
+    return cipher
   }
 
   /**
    * Build the cipher transformation string based on mode and padding.
    */
-  private fun buildTransformation(): String {
+  private fun buildTransformation(mode: String, padding: String): String {
     val javaPadding = when (padding) {
       PADDING_PKCS7 -> "PKCS5Padding" // PKCS5 is equivalent to PKCS7 for DES
       PADDING_ISO10126 -> "ISO10126Padding"
@@ -115,7 +117,7 @@ class DesMachineModule(reactContext: ReactApplicationContext) :
   /**
    * Apply manual padding for ZERO padding mode.
    */
-  private fun applyPaddingIfNeeded(data: ByteArray): ByteArray {
+  private fun applyPaddingIfNeeded(data: ByteArray, padding: String): ByteArray {
     if (padding != PADDING_ZERO && padding != PADDING_NONE) {
       return data
     }
@@ -135,7 +137,7 @@ class DesMachineModule(reactContext: ReactApplicationContext) :
   /**
    * Remove manual padding for ZERO padding mode.
    */
-  private fun removePaddingIfNeeded(data: ByteArray): ByteArray {
+  private fun removePaddingIfNeeded(data: ByteArray, padding: String): ByteArray {
     if (padding != PADDING_ZERO) {
       return data
     }
@@ -151,7 +153,7 @@ class DesMachineModule(reactContext: ReactApplicationContext) :
   /**
    * Format encrypted bytes to the configured output format.
    */
-  private fun formatOutput(bytes: ByteArray): String {
+  private fun formatOutput(bytes: ByteArray, outputFormat: String): String {
     return when (outputFormat) {
       FORMAT_HEX -> bytes.joinToString("") { "%02x".format(it) }
       else -> Base64.encodeToString(bytes, Base64.NO_WRAP)
@@ -161,13 +163,24 @@ class DesMachineModule(reactContext: ReactApplicationContext) :
   /**
    * Parse input string from the configured format to bytes.
    */
-  private fun parseInput(text: String): ByteArray {
+  private fun parseInput(text: String, outputFormat: String): ByteArray {
     return when (outputFormat) {
       FORMAT_HEX -> text.chunked(2).map { it.toInt(16).toByte() }.toByteArray()
       else -> Base64.decode(text, Base64.NO_WRAP)
     }
   }
 
+  /**
+   * Data class to hold DES configuration.
+   */
+  private data class DesConfig(
+    val key: String,
+    val iv: String?,
+    val mode: String,
+    val padding: String,
+    val outputFormat: String
+  )
+
   companion object {
     const val NAME = NativeDesMachineSpec.NAME
 
@@ -175,10 +188,6 @@ class DesMachineModule(reactContext: ReactApplicationContext) :
 
     // Mode constants
     private const val MODE_ECB = "ECB"
-    private const val MODE_CBC = "CBC"
-    private const val MODE_CFB = "CFB"
-    private const val MODE_OFB = "OFB"
-    private const val MODE_CTR = "CTR"
 
     // Padding constants
     private const val PADDING_PKCS7 = "PKCS7"

package/ios/DesMachine.h

@@ -3,10 +3,4 @@
 
 @interface DesMachine : NSObject <NativeDesMachineSpec>
 
-@property (nonatomic, strong) NSData *secretKey;
-@property (nonatomic, strong) NSData *ivData;
-@property (nonatomic, copy) NSString *mode;
-@property (nonatomic, copy) NSString *padding;
-@property (nonatomic, copy) NSString *outputFormat;
-
 @end