diff --git a/readme.md b/readme.md index 07fed64..2b6913c 100644 --- a/readme.md +++ b/readme.md @@ -1,130 +1,130 @@ -# Ghettocrypt -*because frankly i have no idea what the fuck i'm doing* -*Please don't use this for anything critical* - -## What the hell is this? -An educational project on implementing a block cipher using a feistel network. -This block cipher employs a few modes of operation. Read more about them [here](#modes-of-operation). - -## Features -* It has very easy syntax -* It's slow -* It absolutely tanks your ram when working with files -* Even leaves some key fragments in there✨ -* It's probably super insecure -* 512-bit keys \* -* But the syntax is pythonlike easy🙇 - -It's pretty ghetto, you know? - -## What are the actual advantages? -* It's two files to import into your project -* 1 Line to use -* 100% cross plattform - -## What could I use it for? -* For data obfuscation -* If your only other option would be no encryption at all - -### I am not kidding, don't use this for critical stuff! Homebrew ciphers tend to be shit! -Especially mine!🗡️ -Even assumed it's a good cipher, it's implementation leaves a lot to be desired in terms of being cryptographically secure. The whole leaving partial keys in ram- thingy... - -## How do I use this? -### *"I don't care about the library. Just let me use it from the command line!"* -There is a CLI version availabile [here](https://github.com/Leonetienne/GhettoCrypt/tree/master/GhettoCryptCLI). - -### Installation as a library -Download the `.h` and `.cpp` file from [INCLUDE/](https://github.com/Leonetienne/GhettoCrypt/tree/master/INCLUDE) and add them to your projects files. *Single-header-magic*. - -### Working with strings -```c++ -using namespace GhettoCipher; - -// Get some string -const std::string input = "I am a super secret message!"; -std::cout << input << std::endl; - -// Encrypt -const std::string encrypted = GhettoCryptWrapper::EncryptString(input, "password1"); -std::cout << encrypted << std::endl; - -// Decrypt -const std::string decrypted = GhettoCryptWrapper::DecryptString(encrypted, "password1"); -std::cout << decrypted << std::endl; -``` - -### Working with files -```c++ -using namespace GhettoCipher; - -// Encrypt -GhettoCryptWrapper::EncryptFile("main.cpp", "main.cpp.crypt", "password1"); - -// Decrypt -GhettoCryptWrapper::DecryptFile("main.cpp.crypt", "main.cpp.clear", "password1"); -``` - -If you want to do more complex stuff, use the cipher-class [`GhettoCipher::Cipher`](https://github.com/Leonetienne/GhettoCrypt/blob/master/GhettoCrypt/Cipher.h) aswell as the conversion methods in [Util.h](https://github.com/Leonetienne/GhettoCrypt/blob/master/GhettoCrypt/Util.h). This way you can cipher on bitlevel. Examples on how to do this are in [GhettoCryptWrapper.cpp](https://github.com/Leonetienne/GhettoCrypt/blob/master/GhettoCrypt/GhettoCryptWrapper.cpp). -This way you could, for example, decrypt an ecrypted file directly into memory. Or use a full-length key instead of a password. -Without saying, this is more advanced and not as-easy as the methods supplied in the wrapper. - ---- -\* A key is always of size `BLOCK_SIZE`. The default block size is 512 (bit), but you can easily change it in [Config.h](https://github.com/Leonetienne/GhettoCrypt/blob/master/GhettoCrypt/Config.h) or wherever it'll be put in the INCLUDE/*.cpp. `BLOCK_SIZE` is also the minimal output length! - -## The deets 🍝 - -### Modes of operation -* [CBC] This block cipher makes use of cipher block chaining. Nothing special. -* [IV] The initialization vector is indeed a bit of special sauce, as it depends on your key instead of being static. It is generated by running the feistel network on *E(m=seed, k=seed)*, which is a one-way function, because *m=k*. -* [RRKM] Never heard of a mode like this, so i've named it **R**olling**R**ound**K**ey**M**ode. This basically means that the round key extrapolation is carried out continously over EVERY round on EVERY block. So in addition to *Mi* being dependent on *E(Mi-1,Ki-1,0)* due to CBC, so is now *Ki* dependent on *Ki-1,r* with *r* being the maximum number of extrapolated keys within a call of *E()*. This is handled within the feistel network class, as an instance lifecycle sees all blocks. Just in case you want to take a peek. - -### Password to key -How does *GC* transform a password to a key? -First up, we have to establish what requirements this transformation must fulfill: -* A full key. Not just *len(passwd)\*8* bits and the rest zero-padded. -* Even if *len(passwd)\*8 > KEY_SIZE*, every bit of the password should affect the key -* Diffusion -* Ideally good collision resistance - -Let's be honest, I'm not a cryptographer, I have no idea how collision resistant this is. -This means, it has to be considered *insecure*! -I have tried a few passwords brute-forcibly, experimentally (about 1mil) and have not been able to produce a collision. -Obviously there have to be collisions, since *|P|, len\(p\) ∈ ℵ ≫ |C|*. - -How does it work? Basically, what happens is your password gets recoded to binary. It is then split into blocks of -size KEY_SIZE, they are ⨁ together, and this single block is then encrypted with itself as a key. - -The end result is the key corresponding to your password. -This is a one-way operation. Since the key used for this operation is the cleartext itself, you cannot undo it without already -knowing the password(=cleartext) to begin with. *You could make a hashfunction out of this.* - - -## LICENSE -``` -BSD 2-Clause License - -Copyright (c) 2021, Leon Etienne -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` +# GCrypt +*(GhettoCrypt), because frankly i have no idea what the fuck i'm doing* +*Please don't use this for anything critical* + +## What the hell is this? +An educational project on implementing a block cipher using a feistel network. +This block cipher employs a few modes of operation. Read more about them [here](#modes-of-operation). + +## Features +* It has very easy syntax +* It's slow +* It absolutely tanks your ram when working with files +* Even leaves some key fragments in there✨ +* It's probably super insecure +* 512-bit keys \* +* But the syntax is pythonlike easy🙇 + +It's pretty ghetto, you know? + +## What are the actual advantages? +* It's two files to import into your project +* 1 Line to use +* 100% cross plattform + +## What could I use it for? +* For data obfuscation +* If your only other option would be no encryption at all + +### I am not kidding, don't use this for critical stuff! Homebrew ciphers tend to be shit! +Especially mine!🗡️ +Even assumed it's a good cipher, it's implementation leaves a lot to be desired in terms of being cryptographically secure. The whole leaving partial keys in ram- thingy... + +## How do I use this? +### *"I don't care about the library. Just let me use it from the command line!"* +There is a CLI version availabile [here](https://gitea.leonetienne.de/leonetienne/GCrypt/src/branch/master/GhettoCryptCLI). + +### Installation as a library +Download the `.h` and `.cpp` file from [INCLUDE/](https://gitea.leonetienne.de/leonetienne/GCrypt/src/branch/master/INCLUDE) and add them to your projects files. *Single-header-magic*. + +### Working with strings +```c++ +using namespace GhettoCipher; + +// Get some string +const std::string input = "I am a super secret message!"; +std::cout << input << std::endl; + +// Encrypt +const std::string encrypted = GhettoCryptWrapper::EncryptString(input, "password1"); +std::cout << encrypted << std::endl; + +// Decrypt +const std::string decrypted = GhettoCryptWrapper::DecryptString(encrypted, "password1"); +std::cout << decrypted << std::endl; +``` + +### Working with files +```c++ +using namespace GhettoCipher; + +// Encrypt +GhettoCryptWrapper::EncryptFile("main.cpp", "main.cpp.crypt", "password1"); + +// Decrypt +GhettoCryptWrapper::DecryptFile("main.cpp.crypt", "main.cpp.clear", "password1"); +``` + +If you want to do more complex stuff, use the cipher-class [`GhettoCipher::Cipher`](https://gitea.leonetienne.de/leonetienne/GCrypt/src/branch/master/GhettoCrypt/Cipher.h) aswell as the conversion methods in [Util.h](https://gitea.leonetienne.de/leonetienne/GCrypt/src/branch/master/GhettoCrypt/Util.h). This way you can cipher on bitlevel. Examples on how to do this are in [GhettoCryptWrapper.cpp](https://gitea.leonetienne.de/leonetienne/GCrypt/src/branch/master/GhettoCrypt/GhettoCryptWrapper.cpp). +This way you could, for example, decrypt an ecrypted file directly into memory. Or use a full-length key instead of a password. +Without saying, this is more advanced and not as-easy as the methods supplied in the wrapper. + +--- +\* A key is always of size `BLOCK_SIZE`. The default block size is 512 (bit), but you can easily change it in [Config.h](https://gitea.leonetienne.de/leonetienne/GCrypt/src/branch/master/GhettoCrypt/Config.h) or wherever it'll be put in the INCLUDE/*.cpp. `BLOCK_SIZE` is also the minimal output length! + +## The deets 🍝 + +### Modes of operation +* [CBC] This block cipher makes use of cipher block chaining. Nothing special. +* [IV] The initialization vector is indeed a bit of special sauce, as it depends on your key instead of being static. It is generated by running the feistel network on *E(m=seed, k=seed)*, which is a one-way function, because *m=k*. +* [RRKM] Never heard of a mode like this, so i've named it **R**olling**R**ound**K**ey**M**ode. This basically means that the round key extrapolation is carried out continously over EVERY round on EVERY block. So in addition to *Mi* being dependent on *E(Mi-1,Ki-1,0)* due to CBC, so is now *Ki* dependent on *Ki-1,r* with *r* being the maximum number of extrapolated keys within a call of *E()*. This is handled within the feistel network class, as an instance lifecycle sees all blocks. Just in case you want to take a peek. + +### Password to key +How does *GC* transform a password to a key? +First up, we have to establish what requirements this transformation must fulfill: +* A full key. Not just *len(passwd)\*8* bits and the rest zero-padded. +* Even if *len(passwd)\*8 > KEY_SIZE*, every bit of the password should affect the key +* Diffusion +* Ideally good collision resistance + +Let's be honest, I'm not a cryptographer, I have no idea how collision resistant this is. +This means, it has to be considered *insecure*! +I have tried a few passwords brute-forcibly, experimentally (about 1mil) and have not been able to produce a collision. +Obviously there have to be collisions, since *|P|, len\(p\) ∈ ℵ ≫ |C|*. + +How does it work? Basically, what happens is your password gets recoded to binary. It is then split into blocks of +size KEY_SIZE, they are ⨁ together, and this single block is then encrypted with itself as a key. + +The end result is the key corresponding to your password. +This is a one-way operation. Since the key used for this operation is the cleartext itself, you cannot undo it without already +knowing the password(=cleartext) to begin with. *You could make a hashfunction out of this.* + + +## LICENSE +``` +BSD 2-Clause License + +Copyright (c) 2021, Leon Etienne +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +```