From 9cd1ded71dce057f5e2632404d65907a3c17d9e1 Mon Sep 17 00:00:00 2001 From: Nicolas Chabbey Date: Mon, 27 Feb 2023 17:06:34 +0100 Subject: [PATCH] Updated documentation Updated version string Added click.Group subclass Added '--user' option to Makefile docs receipt --- Makefile | 2 +- docs/reference.md | 2 +- docs/usages.md | 48 ++++++++++++++++++++++++++++++---------- encrypted.txt | 1 + kryptoxin/__version__.py | 2 +- kryptoxin/core/cli.py | 12 ++++++++-- 6 files changed, 50 insertions(+), 17 deletions(-) create mode 100644 encrypted.txt diff --git a/Makefile b/Makefile index 3415a36..f7cc0a7 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ deps: requirements.txt docs: cd docs; \ echo "[*] Building Kryptoxin Documentation..."; \ - pip install -r requirements.txt ; \ + pip install -r requirements.txt --user ; \ cd ..; \ $(PYTHON) -m mkdocs build; \ echo "[!] To browse local documentation, type in 'python -m mkdocs serve'" diff --git a/docs/reference.md b/docs/reference.md index 04d183c..9a9fa88 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -6,7 +6,7 @@ Kryptoxin is supporting various encryption features and options, this section of To keep the usage simple and streamlined, Kryptoxin implicitly uses parameters by default. Some of these have been selected due to their wide support across frameworks and operating systems. Therefore, most of the time you don't have to explicitly specify them to achieve a specific goal such as encrypting a payload. -### Encryption +### Encryption and Decryption * Encryption Algorithm: `Advanced Encryption Standard` or `AES` * Encryption key size: `256 bits` diff --git a/docs/usages.md b/docs/usages.md index 28c4dcf..da86c36 100644 --- a/docs/usages.md +++ b/docs/usages.md @@ -2,44 +2,47 @@ Kryptoxin can be used in a wide variety of scenarios and contexts. All the examples below assumes we will be using it for security purposes, let's say for a Red Team engagement. -Several functions or commands may be supported in the near future, at this time of writing only the `encrypt` command is available. As the name implies the `encrypt` command perform encryption on the supplied input. +To use Kryptoxin, pass the `kryptoxin` module to your Python interpreter using the `python -m kryptoxin` command. You can use the `--option` command-line parameter at any given time to lists the available options: ``` { .sh .no-copy } Usage: python -m kryptoxin [OPTIONS] COMMAND [ARGS]... Options: - --help Show this message and exit. + --version Show the version and exit. + --help Show this message and exit. Commands: encrypt This command perform encryption on the supplied input. + decrypt This command perform decryption on the supplied input. ``` ## Encryption (`encrypt`) -Most encryption options are self-explanatory, but can be listed using the `--help` command-line option. +As the name implies the `encrypt` command perform encryption on the supplied input. !!! info "Default encryption parameters" By default Kryptoxin uses the `AES` symmetric algorithm with a 256-bits key. The block cipher operation mode is `CBC` and uses the key-derivation function `PBKDF2` with the `SHA-1` digest algorithm. These parameters have been selected because they are widely supported across languages and framework such as `PowerShell` and `.NET` . ???+ warning "Mandatory command-line option" - Only one command-line option is required and mandatory to perform payload encryption, namely the `-k` or `--key` option. If a file is not provided using the `-i` or `--in` option, it will read the standard input. When omitting the `-i` or `--in` option, kryptoxin will prompt you and read your input until your hit the ++ctrl+d++ key. + Only one command-line option is required and mandatory to perform payload encryption, namely the `-k` or `--key` option. If a file is not provided using the `-i` or `--in` option, it will read the standard input (or stdin); when omitted, kryptoxin will prompt you and read your input until you hit the ++ctrl+d++ keys. -### Basic Usage +### Basic Encryption -Perform encryption using the default parameters and options: +The commands below perform encryption using the default parameters and options: -=== "Read from a file" +=== "Read from the standard input" ```{.sh .no-copy} - $ python -m kryptoxin encrypt -k 12345 -i input_file.txt + $ echo -n 'test' | python -m kryptoxin encrypt -k 12345 tRQYHkQkS9Z7z7i7rzmJSPTuOfE2UUUERsR9CRtdwSM= ``` -=== "Read from Standard Input (stdin)" +=== "Read from a file" ```{.sh .no-copy} - $ cat input_file.txt | python -m kryptoxin encrypt -k 12345 + $ python -m kryptoxin encrypt -k 12345 -i input_file.txt tRQYHkQkS9Z7z7i7rzmJSPTuOfE2UUUERsR9CRtdwSM= ``` + ??? question "What the above commands do ?" Let's break down the above commands, options and outputs: @@ -51,9 +54,9 @@ Perform encryption using the default parameters and options: Once the encryption operation is performed, Kryptoxin will return a base64 encoded output by default. The latter can be copy/pasted into variables, or can be stored in a file by using the `-o` or `--out` command-line option. -### Read, Encrypt and Output to a file +### Encrypt to a file -The command below encrypt the provided Dynamic Link Library (or .dll) and output the base64-encoded ciphertext to a file: +To encrypt a binary file such as a Dynamic Link Library (or .dll), you can use the command below: ```{.sh .no-copy} $ python -m kryptoxin encrypt --key 12345 --key_size 128 \ @@ -63,3 +66,24 @@ $ python -m kryptoxin encrypt --key 12345 --key_size 128 \ ??? question "What the above command-line options do ?" For this example we use the `AES` block cipher algorithm with a 128-bits key. We also specify the `SHA256` digest algorithm for the `HMAC` function. The block cipher operation mode is `CBC` and its initialization vector is manually specified. The latter must matches the block cipher's block size, which is 16 bytes. Finally, the output is written to the file specified by the `--out` command-line option. + +## Decryption (`decrypt`) + +The `decrypt` command as the name implies, allow you to perform decryption on a given `ciphertext`. If the decryption process is successful, kryptoxin will write the `plaintext` directly on the console standard output or will write the result in the file given by the `--out` option. + +### Quick Decryption + +To perform "a quick" decryption of a given input with the default parameters and options, you can use the command below: + +=== "Read from the standard input" + ```{.sh .no-copy} + $ echo 'tRQYHkQkS9Z7z7i7rzmJSPTuOfE2UUUERsR9CRtdwSM=' | \ + > python -m kryptoxin decrypt -k 12345 + test + ``` + +=== "Read from a file" + ```{.sh .no-copy} + $ python -m kryptoxin decrypt -k 12345 -i encrypted.txt + test + ``` diff --git a/encrypted.txt b/encrypted.txt new file mode 100644 index 0000000..40c3a74 --- /dev/null +++ b/encrypted.txt @@ -0,0 +1 @@ +tRQYHkQkS9Z7z7i7rzmJSPTuOfE2UUUERsR9CRtdwSM= diff --git a/kryptoxin/__version__.py b/kryptoxin/__version__.py index b9876f1..170609a 100644 --- a/kryptoxin/__version__.py +++ b/kryptoxin/__version__.py @@ -2,4 +2,4 @@ kryptoxin version module. This module holds the current version number. """ -__version__ = '0.9.4rc1' +__version__ = '0.9.4rc2' diff --git a/kryptoxin/core/cli.py b/kryptoxin/core/cli.py index 909b2b7..845d669 100644 --- a/kryptoxin/core/cli.py +++ b/kryptoxin/core/cli.py @@ -9,7 +9,15 @@ from ..crypto import aes -# local array of click.options for cryptographic parameters options +# Sub-class of click.Group +class NaturalOrderCommands(click.Group): + def list_commands(self, ctx): + """ This function returns commands in a natural order + """ + return self.commands.keys() + + +# Local array of click.options for cryptographic parameters options _cmd_opts_crypto = [ click.option('-i', '--in', 'input_file', type=click.File("rb"), default=sys.stdin.buffer, nargs=1, @@ -54,7 +62,7 @@ def _add_options(func): return _add_options -@ click.group() +@ click.group(cls=NaturalOrderCommands) @ click.version_option(prog_name=PROGRAM_NAME) def cli(**kwargs): pass