README.md
<p align="center">
<br>
<a href="#">
<img src="logo.svg" height="100" width="100" alt="Mersad Cryptography Library"/>
</a>
</p>
<h1 align="center">Mersad Cryptography Library</h1>
<h3 align="center">A side project of a (bad) Telecommunication student who loves ciphers.</h3>
<p align="center">
<p align="center">
<a title="Open Source" href="https://opensource.com/resources/what-open-source" target="_blank">
<img src="https://img.shields.io/badge/Open%20Source-Forever-brightgreen?logo=open-source-initiative&style=flat-square" alt="Open Source">
</a>
<a title="License: AGPLv3" href="https://www.opensource.org/licenses/AGPL-3.0" target="_blank">
<img src="https://img.shields.io/github/license/azadeh-afzar/Mersad-Cryptography-Library?logo=gnu&style=flat-square" alt="License: AGPL v3">
</a>
<a title="Language counter" href="#" target="_blank">
<img src="https://img.shields.io/github/languages/count/azadeh-afzar/Mersad-Cryptography-Library?logo=gitlab&style=flat-square" alt="Language counter">
</a>
<a title="Top language" href="#" target="_blank">
<img src="https://img.shields.io/github/languages/top/azadeh-afzar/Mersad-Cryptography-Library?logo=gitlab&style=flat-square" alt="Top language">
</a>
<br>
<a title="Code Quality: Codefactor.io" href="https://www.codefactor.io/repository/github/azadeh-afzar/mersad-cryptography-library" target="_blank">
<img src="https://www.codefactor.io/repository/github/azadeh-afzar/mersad-cryptography-library/badge?style=flat-square" alt="CodeFactor"/>
</a>
<a title="Code Quality: CodeClimate.com" href="https://codeclimate.com/github/azadeh-afzar/Mersad-Cryptography-Library/maintainability" target="_blank">
<img src="https://img.shields.io/codeclimate/maintainability/azadeh-afzar/Mersad-Cryptography-Library?logo=code-climate&style=flat-square" alt="CodeClimate rating"/>
</a>
<a title="Code Technical Debt: CodeClimate.com" href="https://codeclimate.com/github/azadeh-afzar/Mersad-Cryptography-Library/maintainability" target="_blank">
<img src="https://img.shields.io/codeclimate/tech-debt/azadeh-afzar/Mersad-Cryptography-Library?logo=code-climate&style=flat-square" alt="CodeClimate technical debt"/>
</a>
<a title="Code Issues: CodeClimate.com" href="https://codeclimate.com/github/azadeh-afzar/Mersad-Cryptography-Library/maintainability" target="_blank">
<img src="https://img.shields.io/codeclimate/issues/azadeh-afzar/Mersad-Cryptography-Library?logo=code-climate&style=flat-square" alt="CodeClimate issues"/>
</a>
<br>
<a title="GitLab: pipeline status" href="https://gitlab.com/Azadeh-Afzar/Cryptography/Mersad-Cryptography-Library/commits/master" target="_blank">
<img src="https://img.shields.io/gitlab/pipeline/Cryptography/Mersad-Cryptography-Library?gitlab_url=https%3A%2F%2Fgitlab.com%2FAzadeh-Afzar&logo=gitlab&style=flat-square" alt="pipeline status" />
</a>
<a title="Test Coverage: CodeClimate.com" href="https://codeclimate.com/github/azadeh-afzar/Mersad-Cryptography-Library" target="_blank">
<img src="https://img.shields.io/codeclimate/coverage/azadeh-afzar/Mersad-Cryptography-Library?logo=code-climate&style=flat-square" alt="CodeClimate"/>
</a>
<br>
<a title="PyPi: Mersad version" href="https://pypi.org/project/mersad" target="_blank">
<img src="https://img.shields.io/pypi/v/mersad?logo=pypi&style=flat-square" alt="PyPI version">
</a>
<a title="PyPi: Mersad downloads" href="https://pypi.org/project/mersad" target="_blank">
<img src="https://img.shields.io/pypi/dm/mersad?logo=pypi&style=flat-square" alt="PyPI downloads">
</a>
<a title="PyPi: version support" href="https://pypi.org/project/mersad" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/mersad?logo=pypi&style=flat-square" alt="Supported Python versions">
</a>
</p>
>Despite the fancy name "Cryptography Library"! this Project isn't anything close to real industry
>(ehem ... I mean military) level cryptography library.
## Mersad? what does it mean?
In Persian (and Arabic) language, "Mersad" means "Hidden", which makes it a perfect choice
for my cryptography library.
## Why is Gamora (yes, I'm a Marvel fan)?
In summer 2019 I had decided to practice Python and DevOps tasks like: continuous
integration and automated releasing software to packaging sources like PYPI, I don't
know how I ended up here writing this for you!
(even like if there is any "you" out there looking at this little side project of mine.)
So if you want to send unbreakable messages to your friends with ancient algorithms
without using pen and paper, Mersad can help you. (but seriously, :joy: unbreakable? c'mon!)
Oh and I :heart: codes and ciphers!
## Quick start
I'm sure you have worked with Python before and you are familiar with how to download
and install packages using pip, so here is how to install this totally (not at all :poop:)
secure package:
```bash
# 1. if you are an uncivilised savage living in a hell of dependency conflicts who doesn't
# even heard of virtual environments and always install packages in sudo mode, here you go:
sudo -H pip3 install mersad
# 2. another option is a non-sudo thing like:
pip3 install --user mersad
# 2. if you are a man of culture, activate your virtual environment and type this:
pip3 install mersad
# 3. pipenv is also a good thing to manage virtual environments and packages to use (I prefer this :smiley:):
pipenv install mersad
```
## Wait a second, What's Cryptography?
Honestly? I don't know either ... :grimacing:. seems a group of smart guys are inventing
ways (or what they call them "algorithms") to hide messages from others, and those "others"
somehow are finding ways to break their algorithms and read their messages.
Apparently people are calling the work of first group (designing encryption algorithms)
"Cryptography" and the work of second group (breaking those stupid ciphers) "Cryptanalysis".
## How does this package work?
Good question, it doesn't.
But if you are so smart and managed to make it work for you, here is some
explanation about the mess that is going on:
Mersad is divided into two main sub-packages, `classical` and `modern`, I'm currently
developing classical algorithms but in future I will start working on modern ones.
I'm also planning to add `cryptanalysis` module, this module will contains programs
to break ciphers.
Each cipher has a class and a translator function, you can use any of them or both of
them together.
the translator function has no memory and requires every argument in
each call but class have memory and can store key, alphabet sequence and etc.
### Example
It is a very simple example of using Shift cipher (aka Caesar cipher) :
```python
from mersad.classical.shift_cipher import ShiftCipher, shift_cipher_translator
MESSAGE = "Hail Caesar!"
ALPHABET = "abcdefghijklmnopqrstuvwxyz"
KEY = 4
# example 1: using translator function:
CIPHER = shift_cipher_translator(MESSAGE, key=KEY, letter_sequence=ALPHABET)
print(CIPHER)
# Out: Hemp Ceiwev!
# with translator function you need to pass all arguments
# in each call again and again.
# example 2: using cipher class.
# now the second way of using shift cipher is using the class instead of function.
# create object without any keyword arguments so agent will use
# default values for all the settings. defaults are predefined in class.
agent = ShiftCipher()
# override defaults.
agent.config(key=3453, letter_sequence=ALPHABET)
# also you can do it at the time yu creat object:
# agent = ShiftCipher(key=3453, letter_sequence=ALPHABET)
# config usage is to override any existing properties with
# new values at any time after creating the object.
# encrypt a string:
print(agent.encrypt("Hail Julius Caesar."))
# Out: 'Hvdg Jpgdpn Cvznvm.'
# with this object approach you don't need to pass every thing in each call to
# encrypt or decrypt.
# another one:
print(agent.encrypt("This method is not secure :0 but it is funny."))
# Out: Tcdn hzocjy dn ijo nzxpmz :0 wpo do dn apiit.
# for decryption simply call decrypt method on agent:
print(agent.decrypt("Tcdn hzocjy dn ijo nzxpmz :0 wpo do dn apiit."))
# Out: This method is not secure :0 but it is funny.
```
for more examples look at:
[snippets](https://gitlab.com/Azadeh-Afzar/Cryptography/Mersad-Cryptography-Library/snippets).
## Can I use this package in terminal?
Yes! :metal:
Each cipher module have a corresponding cli program with name convention of:
`mcl`+`ModuleName`. For example to run Shift cipher module in terminal just type `mclShift`.
To learn how to work with cli programs type `--help` after program name
(e.g. `mclShift --help`).
## Contribution
If you want to contribute to this project, please read [CONTRIBUTING](CONTRIBUTING.md).
## Code of Conduct
Visit the [Code of Conduct](CODE_OF_CONDUCT.md).
## Roadmap
Visit the [Roadmap](ROADMAP.md) to keep track of which features we are currently
working on and which futures will come at future.
## License
Licensed under the [AGPLv3](LICENSE).
## Attribution
- Books: [Cracking Codes with Python](https://inventwithpython.com/cracking) and
[Understanding Cryptography](https://www.springer.com/gp/book/9783642041006)
- Code ideas: [PyCryptodome](https://www.pycryptodome.org)
- Online resources: [Crypto Corner](https://crypto.interactive-maths.com)
- Mersad Logo: Designed with [OpenMoji](https://openmoji.org/)