# react-native-des-machine

[![npm version](https://img.shields.io/npm/v/react-native-des-machine.svg)](https://www.npmjs.com/package/react-native-des-machine)
[![npm downloads](https://img.shields.io/npm/dm/react-native-des-machine.svg)](https://www.npmjs.com/package/react-native-des-machine)
[![license](https://img.shields.io/npm/l/react-native-des-machine.svg)](https://github.com/NeRo8/react-native-des-machine/blob/main/LICENSE)
[![platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey.svg)](https://reactnative.dev/)

A React Native TurboModule that provides DES (Data Encryption Standard) encryption and decryption with support for multiple cipher modes, padding schemes, and output formats.

## 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
- Full TypeScript support

## Compatibility

| Platform     | Minimum Version |
| ------------ | --------------- |
| iOS          | 13.0+           |
| Android      | API 21+ (5.0)   |
| React Native | 0.71+           |

## Installation

Using npm:

```sh
npm install react-native-des-machine
```

Using yarn:

```sh
yarn add react-native-des-machine
```

### iOS Setup

After installing, run pod install:

```sh
cd ios && pod install
```

### Android Setup

No additional setup required. The library auto-links on Android.

## Usage

### Basic Example - Using the DesMachine Class

```typescript
import { DesMachine } from 'react-native-des-machine';

// Create a DES machine instance with your encryption key
const machine = new DesMachine({
  key: 'mySecretKey123', // minimum 8 characters
});

// Encrypt text
const encrypted = machine.encrypt('Hello World!');
console.log('Encrypted:', encrypted);
// Output: "Encrypted: 2jmj7l5rSw0yVb/vlWAYkK/YBwk="

// Decrypt text
const decrypted = machine.decrypt(encrypted);
console.log('Decrypted:', decrypted);
// Output: "Decrypted: Hello World!"
```

### Advanced Configuration

```typescript
import { DesMachine, Mode, Padding, Format } from 'react-native-des-machine';

// 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 = machine.encrypt('Sensitive data');
console.log('Encrypted (hex):', 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 for building UI components:

```typescript
import {
  modeOptions,
  paddingOptions,
  formatOptions,
} from 'react-native-des-machine';

// modeOptions structure:
// [
//   { label: 'ECB (Electronic Codebook)', value: 'ECB' },
//   { label: 'CBC (Cipher Block Chaining)', value: 'CBC' },
//   { label: 'CFB (Cipher Feedback)', value: 'CFB' },
//   { label: 'OFB (Output Feedback)', value: 'OFB' },
//   { label: 'CTR (Counter)', value: 'CTR' },
// ]

// Use with React Native Picker or any dropdown component
<Picker selectedValue={selectedMode} onValueChange={setSelectedMode}>
  {modeOptions.map((option) => (
    <Picker.Item key={option.value} label={option.label} value={option.value} />
  ))}
</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

### DesMachine Class

The main class for DES encryption and decryption.

#### Constructor

```typescript
new DesMachine(params: DesMachineParams)
```

Creates a new DES machine instance.

**Throws:**

- `Error` if key is missing or less than 8 characters
- `Error` if iv is provided but not exactly 8 characters

#### Methods

| 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    |

### DesMachineParams

| 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                  |

### Quick Functions

#### `encrypt(params: DesMachineParams, text: string): string`

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

#### Mode

| Constant   | Value   | Description                   |
| ---------- | ------- | ----------------------------- |
| `Mode.ECB` | `'ECB'` | Electronic Codebook (default) |
| `Mode.CBC` | `'CBC'` | Cipher Block Chaining         |
| `Mode.CFB` | `'CFB'` | Cipher Feedback               |
| `Mode.OFB` | `'OFB'` | Output Feedback               |
| `Mode.CTR` | `'CTR'` | Counter                       |

#### Padding

| Constant           | Value        | Description              |
| ------------------ | ------------ | ------------------------ |
| `Padding.PKCS7`    | `'PKCS7'`    | PKCS#7 padding (default) |
| `Padding.ISO10126` | `'ISO10126'` | ISO 10126 padding        |
| `Padding.ZERO`     | `'ZERO'`     | Zero padding             |
| `Padding.NONE`     | `'NONE'`     | No padding               |

#### Format

| Constant        | Value      | Description               |
| --------------- | ---------- | ------------------------- |
| `Format.BASE64` | `'BASE64'` | Base64 encoding (default) |
| `Format.HEX`    | `'HEX'`    | Hexadecimal encoding      |

### Pre-built Options Arrays

| Export           | Type                                   | Description                 |
| ---------------- | -------------------------------------- | --------------------------- |
| `modeOptions`    | `OptionsList<ModeEncryptionType>[]`    | Mode options with labels    |
| `paddingOptions` | `OptionsList<PaddingEncryptionType>[]` | Padding options with labels |
| `formatOptions`  | `OptionsList<OutputFormatType>[]`      | Format options with labels  |

Each option has the structure: `{ label: string, value: string }`

## TypeScript Support

The library includes full TypeScript definitions:

```typescript
import {
  // Main class
  DesMachine,
  createDesMachine,
  // Quick functions
  encrypt,
  decrypt,
  // Constants
  Mode,
  Padding,
  Format,
  // Pre-built options
  modeOptions,
  paddingOptions,
  formatOptions,
} from 'react-native-des-machine';

// Types
import type {
  DesMachineParams,
  ModeEncryptionType,
  PaddingEncryptionType,
  OutputFormatType,
} from 'react-native-des-machine';
```

## Complete Exports

| 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

DES is considered cryptographically weak by modern standards due to its 56-bit key size. For production applications requiring strong encryption, consider using AES or other modern algorithms. This library is suitable for:

- Legacy system compatibility
- Educational purposes
- Low-security applications

## Author

- GitHub: [@NeRo8](https://github.com/NeRo8)

## Contributing

- [Development workflow](CONTRIBUTING.md#development-workflow)
- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
- [Code of conduct](CODE_OF_CONDUCT.md)

## Support

If you find this library helpful, please consider giving it a star on GitHub!

- [Report a bug](https://github.com/NeRo8/react-native-des-machine/issues)
- [Request a feature](https://github.com/NeRo8/react-native-des-machine/issues)

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)