Ekon: Secure Config Encryption & Decryption

ekon is an NPM package that provides secure encryption and decryption for configuration files using customizable keys. It supports both symmetric (AES-256-CBC) and asymmetric (RSA) encryption, allowing developers to protect sensitive data in any file format (e.g., .json, .env). Encrypted data is stored in a custom .ekon format, ensuring security during storage or transmission.

Key Features

• Symmetric Encryption: Encrypt files using AES-256-CBC with a customizable passphrase.
• Asymmetric Encryption: Encrypt files using RSA public/private key pairs with optional passphrase-protected private keys.
• Decryption: Decrypt .ekon files back to their original format, preserving indentation and structure.
• Metadata Support: Include metadata (e.g., version, timestamp, source) with encrypted files.
• Custom File Format: Use .ekon extension for encrypted files (e.g., config.ekon, config.env.ekon).
• Command Line Interface (CLI): Encrypt, decrypt, and generate keys directly from the terminal.
• Universal File Handling: Encrypt and decrypt any text file (e.g., .json, .env) as a string, maintaining original formatting.

Problems Solved

• Secure Storage: Protect sensitive data like API keys, passwords, and tokens from exposure.
• Transmission Protection: Safely share configuration files across networks.
• Simplified Workflow: Seamlessly integrate encryption/decryption into Node.js projects with intuitive CLI commands.

Installation

1. Install the Package

Install ekon globally for CLI usage or as a local dependency in your Node.js project.

Install Globally (for CLI usage):

npm install -g ekon

Note: Check INSTALLATION.md for detailed installation instructions.

Usage

1. Generate Key Pair (Optional for RSA Encryption)

To use RSA encryption, generate a public/private key pair with the generate-keys command.

Command:

ekon generate-keys --public=<public-key-file> --private=<private-key-file> [--passphrase=<passphrase>]

Example (without passphrase):

ekon generate-keys --public=public.pem --private=private.pem

Example (with passphrase):

ekon generate-keys --public=public.pem --private=private.pem --passphrase=12345678

• Output: Creates public.pem and private.pem. If a passphrase is provided, the private key is encrypted.
• Note: Passphrases must be at least 8 characters long. Store the passphrase securely, as it cannot be recovered.

2. Encrypt a File (Terminal Level Usage)

Encrypt any text file (e.g., .json, .env) using either symmetric (passphrase) or asymmetric (public key) encryption.

Command (Symmetric Encryption):

ekon encrypt <path-to-file> [--key=<passphrase>] [--out=<output-file>]

Example (.json file):

ekon encrypt config.json --key=mysecretpass

• Output: Creates config.ekon.

Example (.env file):

ekon encrypt config.env --key=mysecretpass --out=config.env.ekon

• Output: Creates config.env.ekon (or appends .ekon to the input file name if --out is omitted).

Passphrase:

• Set via --key=<passphrase> or the PASS_CODE environment variable.

Example with environment variable:

PASS_CODE=mysecretpass ekon encrypt config.json

Command (Asymmetric Encryption):

ekon encrypt <path-to-file> --public-key=<public-key-file> [--out=<output-file>]

Example (.json file):

ekon encrypt config.json --public-key=public.pem

• Output: Creates config.ekon.

Example (.env file):

ekon encrypt config.env --public-key=public.pem --out=config.env.ekon

• Output: Creates config.env.ekon.

3. Decrypt an Encrypted File (Terminal Level Usage)

Decrypt .ekon files back to their original format using the corresponding passphrase or private key.

Command (Symmetric Decryption):

ekon decrypt <path-to-ekon-file> [--key=<passphrase>] [--out=<output-file>]

Example (.json file):

ekon decrypt config.ekon --key=mysecretpass

• Output: Creates config.decrypted (or the specified --out file).

Example (.env file):

ekon decrypt config.env.ekon --key=mysecretpass

• Output: Creates config.env (removes .ekon automatically unless --out is specified).

Passphrase:

• Use the same passphrase as encryption, via --key or PASS_CODE.

Example with environment variable:

PASS_CODE=mysecretpass ekon decrypt config.ekon

Example with GitHub Actions secret:

ekon decrypt config.ekon --key="${{ secrets.EKON_PASS_CODE }}"

Command (Asymmetric Decryption):

ekon decrypt <path-to-ekon-file> --private-key=<private-key-file> [--passphrase=<passphrase>] [--out=<output-file>]

Example (.json file):

ekon decrypt config.ekon --private-key=private.pem

• Output: Creates config.decrypted.

Example (.env file):

ekon decrypt config.env.ekon --private-key=private.pem --passphrase=12345678 --out=config.env

• Output: Creates config.env (or the specified --out file).

Passphrase:

• Required if the private key is encrypted. Provide via --passphrase or PRIVATE_KEY_PASSPHRASE environment variable.

Example with environment variable:

PRIVATE_KEY_PASSPHRASE=12345678 ekon decrypt config.env.ekon --private-key=private.pem

5. Handling Errors

• Non-.ekon Files:

  ❌ Invalid file type. Only ".ekon" files can be decrypted.

• Missing Passphrase:

  ❌ No passcode found. Set via --key=yourKey or PASS_CODE env variable.

• Invalid Private Key or Passphrase:

  ❌ An error occurred: RSA decryption failed: error:1C800064:Provider routines::bad decrypt. Check the private key, passphrase, or file integrity.

• File Not Found:

  ❌ File not found: <filename>

Example Workflow

1. Create configuration files:

   • config.json:

     {
       "apiKey": "12345",
       "dbPassword": "secretpassword"
     }

   • config.env:

     API_KEY=12345
     DB_PASSWORD=secretpassword

2. Generate key pair:

   ekon generate-keys --public=public.pem --private=private.pem --passphrase=12345678

3. Encrypt files:

   ekon encrypt config.json --public-key=public.pem
   ekon encrypt config.env --public-key=public.pem --out=config.env.ekon

4. Decrypt files:

   ekon decrypt config.ekon --private-key=private.pem --passphrase=12345678
   ekon decrypt config.env.ekon --private-key=private.pem --passphrase=12345678 --out=config.env

CLI Options

• --key=<passphrase>: Specify passphrase for symmetric encryption/decryption.
• --public-key=<file>: Path to public key for RSA encryption.
• --private-key=<file>: Path to private key for RSA decryption.
• --passphrase=<passphrase>: Passphrase for encrypted private keys or key pair generation.
• --out=<output-file>: Specify custom output file name.
• --public=<file>, --private=<file>: Specify output paths for key pair generation.

Contribution

Contributions are welcome! Submit pull requests, report issues, or suggest features via GitHub. Follow standard GitHub flow for contributions.

License

ekon is licensed under the MIT License.