## dcrypt
Use RSA + Fernet encryption to encrypt and decrypt text and Python objects.
## Installation
Install with pip:
```bash
pip install dcrypt
```
## Usage
`dcrypt` contains three classes that can be used for encryption and decryption:
- `TextCrypt`: Encrypts and decrypts text.
- `ObjectCrypt`: Encrypts and decrypts text and Python objects (using `pickle`).
- `JSONCrypt`: `ObjectCrypt` that encrypts into a JSON parsable format.
Let's start by encrypting some text we want to keep secret:
```python
import dcrypt
# First, we create a cryptkey
cryptkey = dcrypt.CryptKey()
# Then, we create a TextCrypt object with the key
text_crypt = dcrypt.TextCrypt(key=cryptkey)
# Now, we can encrypt some text
encrypted_text = text_crypt.encrypt("This is a secret message!")
print(encrypted_text)
# And decrypt it again
decrypted_text = text_crypt.decrypt(encrypted_text)
print(decrypted_text)
```
How about encrypting Python objects?
```python
# We can use our existing cryptkey
# Create an ObjectCrypt object with the key
object_crypt = dcrypt.ObjectCrypt(key=cryptkey)
# Encrypt a Python object
my_secrets = {
"passcode": 1234,
"password": "password123",
}
encrypted_object = object_crypt.encrypt(my_secrets)
print(encrypted_object)
# The Output would be something like:
# {
# "passcode": "gAAAAABgJ0Z...",
# "password": "gAAAAABgJ0Z...",
# }
```
You could also decide to use the object crypt to encrypt text too.
Okay! Let's assume that we want to store `my_secrets` in JSON format. It would be nice if `my_secrets` is encrypted in a format that is JSON serializable. We can do this by using the `JSONCrypt` class:
```python
# Let's add a tuple of emails to our secrets
my_secrets["emails"] = ("user@host.com", "abc@xyz.com")
# With JSONCrypt
json_crypt = dcrypt.JSONCrypt(key=cryptkey)
encrypted_secrets = json_crypt.encrypt(my_secrets)
# Let's decrypt it again
decrypted_secrets = json_crypt.decrypt(encrypted_secrets)
# Just to be sure, let's check that the decrypted secrets are the same as the original secrets
assert decrypted_secrets == my_secrets
# Oops! We get an error:
# AssertionError
# Why? Because the tuple was converted to a list when we encrypted it.
# So take note of this when using JSONCrypt.
```
### `CryptKey`
A cryptkey is simply a key that is used to encrypt and decrypt data.
Let's create a cryptkey:
```python
import dcrypt
cryptkey = dcrypt.CryptKey()
```
Hmm... that was easy. But what actually is a cryptkey? A cryptkey is an object containing a signature used to encrypt and decrypt data. Wondering what the signature is? A cryptkey signature contains four things:
- A rsa public key
- A rsa private key
- An encrypted master key (Fernet key)
- The hash method used to sign and verify the master key
The rsa keys are used to encrypt and decrypt the master key. The master key is used to encrypt and decrypt data. The rsa keys are generated using the `rsa` library. The master key is generated using the `cryptography` library's `Fernet` class.
What if we want stronger encryption? We can specify the keys signature strength
```python
cryptkey = dcrypt.CryptKey(signature_strength=2)
# The default is 1. But we can specify 2 or 3 for stronger encryption.
# The caveat is that the higher the signature strength, the longer it takes to generate the cryptkey.
```
We can also specify the hash method used to sign and verify the master key
```python
cryptkey = dcrypt.CryptKey(hash_algorithm="SHA-512")
# See `dcrypt.signature.SUPPORTED_HASH_ALGORITHMS` for a list of supported hash methods.
```
### Saving and Loading CryptKeys
I know, I know. You want to save your cryptkey so you can use it later. You can do this by saving the cryptkey's signature to a file. Let's see how:
```python
import dcrypt
# Shinny new cryptkey
cryptkey = dcrypt.CryptKey()
# Now, let's save it
cryptkey.signature.dump("./secrets_folder/cryptkey.json")
# Yes! We saved it. Now, let's load our key signature back and recreate our cryptkey
signature = dcrypt.Signature.load("./secrets_folder/cryptkey.json")
cryptkey = dcrypt.CryptKey(signature=signature)
# Yay! We have our cryptkey back.
```
> Another reason why you may want to save your key signature is to remove the overhead of generating a new cryptkey every time you want to encrypt or decrypt data. Especially when the signature strength is maxed out(3). You can just load the signature from a file and use it to create a new cryptkey.
### Let's talk about cryptkey signatures
The cryptkey signature is a NamedTuple which contains...? Right! A public key, a private key, an encrypted master key and a hash method.
The cool thing about cryptkey signatures is that once created, they cannot be modified. So we can access the public key, private key, encrypted master key and hash method without worrying about them being modified.
Let's see how we can use cryptkey signatures:
```python
import dcrypt
signature = dcrypt.CryptKey.make_signature()
# Yes! we use the `make_signature` classmethod to create a cryptkey signature.
# Now, let's access the public key
public_key = signature.pub_key
# What about the hash method?
hash_method = signature.hash_method
# And the encrypted master key?
encrypted_master_key = signature.enc_master_key
```
There are two types of cryptkey signatures:
- `Signature`
- `CommonSignature`
What are the differences between them? Let's start with the `CommonSignature`.
A `CommonSignature` is a cryptkey signature whose values are all strings. This means that it can be easily serialized and deserialized. This is the type of signature that is saved to a file when we use the `dump` method.
Unlike the `CommonSignature`, a `Signature` is a cryptkey signature whose values are not all strings. Some are byte type. This means that it cannot be easily serialized and deserialized. This is the type of signature that is used to create a cryptkey.
However, we can convert a `Signature` to a `CommonSignature` and vice versa:
```python
import dcrypt
# Let's create a cryptkey signature
signature = dcrypt.CryptKey.make_signature()
# Now, let's convert it to a common signature
common_signature = signature.common()
# And back to a signature
signature = dcrypt.Signature.from_common(common_signature)
```
Easy, right? But why do we need to convert a signature to a common signature? Well, we need to do this when we want to save a cryptkey signature to a file. We can't save a `Signature` to a file. We can only save a `CommonSignature` to a file.
Another use case is if we need to send a cryptkey signature over a network, we need to convert it to a common signature first and then convert it back to a signature when we receive it.
```python
import dcrypt
import requests
# Let's create a cryptkey signature
signature = dcrypt.CryptKey.make_signature()
# Now, let's convert it to a common signature
common_signature = signature.common()
# Let's send it over a network
requests.post("https://example.com", json=common_signature.json())
# Now, let's receive it
common_signature_as_json = requests.get("https://example.com").json()
# Construct a common signature from the json
common_signature = dcrypt.CommonSignature(**common_signature_as_json)
# And convert it back to a signature
signature = dcrypt.Signature.from_common(common_signature)
# Easy peasy!
```
If you noticed, we converted the common signature to json before sending it over the network. You do this using the `json` method of the `CommonSignature` class.
### Encrypting function output
Say you have a method in a class called `Human` which returns the contact information of the human which will be sent over a network. You may want to encrypt the result of the method before sending it. How do you do this?
First let's define our `Human` class:
```python
from dataclasses import dataclass
@dataclass
class Human:
name: str
gender: str
email: str
phonenumber: str
address: str
...
def get_contact_info(self):
return {
"email": self.email,
"phonenumber": self.phonenumber,
}
```
Now, let's create a cryptkey and an `ObjectCrypt` object:
```python
import dcrypt
# Create a cryptkey
cryptkey = dcrypt.CryptKey()
# Create an ObjectCrypt object
object_crypt = dcrypt.ObjectCrypt(key=cryptkey)
# Let save the cryptkey signature to a file
cryptkey.signature.dump("./secrets_folder/cryptkey.json")
```
All that's left is to decorate the `get_contact_info` method with the object crypt we just created:
```python
class Human:
...
@object_crypt
def get_contact_info(self):
return {
"email": self.email,
"phonenumber": self.phonenumber,
}
```
That's it! Now, the result of the `get_contact_info` method will be encrypted before it is returned and yes you can decrypt it with the same object crypt or create a new object crypt with the already saved cryptkey signature.
```python
tolu = Human(
name="Tolu",
gender="Male",
email="tioluwa.dev@gmail.com",
phonenumber="08012345678",
address="Lagos, Nigeria."
)
# Let's get his contact info
encrypted_contact_info = tolu.get_contact_info()
# The output would be something like:
# {
# "email": "gAAAAABgJ0Z...",
# "phonenumber": "gAAAAABgJ0Z...",
# }
# Now, let's decrypt it
signature = dcrypt.Signature.load("./secrets_folder/cryptkey.json")
new_cryptkey = dcrypt.CryptKey(signature=signature)
new_object_crypt = dcrypt.ObjectCrypt(key=new_cryptkey)
decrypted_contact_info = new_object_crypt.decrypt(contact_info)
# The output should be:
# {
# "email": "tioluwa.dev@gmail",
# "phonenumber": "08012345678",
# }
```
You are now ready to use `dcrypt` to encrypt and decrypt your data. Goodluck!
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Testing
To run the tests, simply run the following command in the root directory of your cloned repository:
```bash
python -m unittest discover tests "test_*.py"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "dcrypt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "ti-oluwa <tioluwa.dev@gmail.com>",
"keywords": "encryption, decryption, rsa, fernet, cryptography",
"author": null,
"author_email": "ti-oluwa <tioluwa.dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c8/4b/ae3dfb4a9314c35352b0471055b7bff49b7025985054878ea949e7444e9b/dcrypt-0.0.6.tar.gz",
"platform": null,
"description": "## dcrypt\n\nUse RSA + Fernet encryption to encrypt and decrypt text and Python objects.\n\n## Installation\n\nInstall with pip:\n\n```bash\npip install dcrypt\n```\n\n## Usage\n\n`dcrypt` contains three classes that can be used for encryption and decryption:\n\n- `TextCrypt`: Encrypts and decrypts text.\n- `ObjectCrypt`: Encrypts and decrypts text and Python objects (using `pickle`).\n- `JSONCrypt`: `ObjectCrypt` that encrypts into a JSON parsable format.\n\nLet's start by encrypting some text we want to keep secret:\n\n```python\nimport dcrypt\n\n# First, we create a cryptkey\ncryptkey = dcrypt.CryptKey()\n\n# Then, we create a TextCrypt object with the key\ntext_crypt = dcrypt.TextCrypt(key=cryptkey)\n\n# Now, we can encrypt some text\nencrypted_text = text_crypt.encrypt(\"This is a secret message!\")\nprint(encrypted_text)\n\n# And decrypt it again\ndecrypted_text = text_crypt.decrypt(encrypted_text)\nprint(decrypted_text)\n```\n\nHow about encrypting Python objects?\n\n```python\n# We can use our existing cryptkey\n\n# Create an ObjectCrypt object with the key\nobject_crypt = dcrypt.ObjectCrypt(key=cryptkey)\n\n# Encrypt a Python object\nmy_secrets = {\n \"passcode\": 1234,\n \"password\": \"password123\",\n}\n\nencrypted_object = object_crypt.encrypt(my_secrets)\nprint(encrypted_object)\n\n# The Output would be something like:\n# {\n# \"passcode\": \"gAAAAABgJ0Z...\",\n# \"password\": \"gAAAAABgJ0Z...\",\n# }\n```\n\nYou could also decide to use the object crypt to encrypt text too.\n\nOkay! Let's assume that we want to store `my_secrets` in JSON format. It would be nice if `my_secrets` is encrypted in a format that is JSON serializable. We can do this by using the `JSONCrypt` class:\n\n```python\n# Let's add a tuple of emails to our secrets\nmy_secrets[\"emails\"] = (\"user@host.com\", \"abc@xyz.com\")\n\n# With JSONCrypt\njson_crypt = dcrypt.JSONCrypt(key=cryptkey)\nencrypted_secrets = json_crypt.encrypt(my_secrets)\n\n# Let's decrypt it again\ndecrypted_secrets = json_crypt.decrypt(encrypted_secrets)\n\n# Just to be sure, let's check that the decrypted secrets are the same as the original secrets\nassert decrypted_secrets == my_secrets\n\n# Oops! We get an error:\n# AssertionError\n# Why? Because the tuple was converted to a list when we encrypted it.\n# So take note of this when using JSONCrypt.\n```\n\n### `CryptKey`\n\nA cryptkey is simply a key that is used to encrypt and decrypt data.\n\nLet's create a cryptkey:\n\n```python\nimport dcrypt\n\ncryptkey = dcrypt.CryptKey()\n```\n\nHmm... that was easy. But what actually is a cryptkey? A cryptkey is an object containing a signature used to encrypt and decrypt data. Wondering what the signature is? A cryptkey signature contains four things:\n\n- A rsa public key\n- A rsa private key\n- An encrypted master key (Fernet key)\n- The hash method used to sign and verify the master key\n\nThe rsa keys are used to encrypt and decrypt the master key. The master key is used to encrypt and decrypt data. The rsa keys are generated using the `rsa` library. The master key is generated using the `cryptography` library's `Fernet` class.\n\nWhat if we want stronger encryption? We can specify the keys signature strength\n\n```python\ncryptkey = dcrypt.CryptKey(signature_strength=2)\n# The default is 1. But we can specify 2 or 3 for stronger encryption.\n# The caveat is that the higher the signature strength, the longer it takes to generate the cryptkey.\n```\n\nWe can also specify the hash method used to sign and verify the master key\n\n```python\ncryptkey = dcrypt.CryptKey(hash_algorithm=\"SHA-512\")\n\n# See `dcrypt.signature.SUPPORTED_HASH_ALGORITHMS` for a list of supported hash methods.\n```\n\n### Saving and Loading CryptKeys\n\nI know, I know. You want to save your cryptkey so you can use it later. You can do this by saving the cryptkey's signature to a file. Let's see how:\n\n```python\nimport dcrypt\n\n# Shinny new cryptkey\ncryptkey = dcrypt.CryptKey()\n\n# Now, let's save it\ncryptkey.signature.dump(\"./secrets_folder/cryptkey.json\")\n\n# Yes! We saved it. Now, let's load our key signature back and recreate our cryptkey\nsignature = dcrypt.Signature.load(\"./secrets_folder/cryptkey.json\")\ncryptkey = dcrypt.CryptKey(signature=signature)\n\n# Yay! We have our cryptkey back.\n```\n\n> Another reason why you may want to save your key signature is to remove the overhead of generating a new cryptkey every time you want to encrypt or decrypt data. Especially when the signature strength is maxed out(3). You can just load the signature from a file and use it to create a new cryptkey.\n\n### Let's talk about cryptkey signatures\n\nThe cryptkey signature is a NamedTuple which contains...? Right! A public key, a private key, an encrypted master key and a hash method.\n\nThe cool thing about cryptkey signatures is that once created, they cannot be modified. So we can access the public key, private key, encrypted master key and hash method without worrying about them being modified.\n\nLet's see how we can use cryptkey signatures:\n\n```python\nimport dcrypt\n\nsignature = dcrypt.CryptKey.make_signature()\n# Yes! we use the `make_signature` classmethod to create a cryptkey signature.\n\n# Now, let's access the public key\npublic_key = signature.pub_key\n\n# What about the hash method?\nhash_method = signature.hash_method\n\n# And the encrypted master key?\nencrypted_master_key = signature.enc_master_key\n```\n\nThere are two types of cryptkey signatures:\n\n- `Signature`\n- `CommonSignature`\n\nWhat are the differences between them? Let's start with the `CommonSignature`.\nA `CommonSignature` is a cryptkey signature whose values are all strings. This means that it can be easily serialized and deserialized. This is the type of signature that is saved to a file when we use the `dump` method.\n\nUnlike the `CommonSignature`, a `Signature` is a cryptkey signature whose values are not all strings. Some are byte type. This means that it cannot be easily serialized and deserialized. This is the type of signature that is used to create a cryptkey.\n\nHowever, we can convert a `Signature` to a `CommonSignature` and vice versa:\n\n```python\nimport dcrypt\n\n# Let's create a cryptkey signature\nsignature = dcrypt.CryptKey.make_signature()\n\n# Now, let's convert it to a common signature\ncommon_signature = signature.common()\n\n# And back to a signature\nsignature = dcrypt.Signature.from_common(common_signature)\n```\n\nEasy, right? But why do we need to convert a signature to a common signature? Well, we need to do this when we want to save a cryptkey signature to a file. We can't save a `Signature` to a file. We can only save a `CommonSignature` to a file.\n\nAnother use case is if we need to send a cryptkey signature over a network, we need to convert it to a common signature first and then convert it back to a signature when we receive it.\n\n```python\nimport dcrypt\nimport requests\n\n# Let's create a cryptkey signature\nsignature = dcrypt.CryptKey.make_signature()\n\n# Now, let's convert it to a common signature\ncommon_signature = signature.common()\n\n# Let's send it over a network\nrequests.post(\"https://example.com\", json=common_signature.json())\n\n# Now, let's receive it\ncommon_signature_as_json = requests.get(\"https://example.com\").json()\n\n# Construct a common signature from the json\ncommon_signature = dcrypt.CommonSignature(**common_signature_as_json)\n\n# And convert it back to a signature\nsignature = dcrypt.Signature.from_common(common_signature)\n# Easy peasy!\n```\n\nIf you noticed, we converted the common signature to json before sending it over the network. You do this using the `json` method of the `CommonSignature` class.\n\n### Encrypting function output\n\nSay you have a method in a class called `Human` which returns the contact information of the human which will be sent over a network. You may want to encrypt the result of the method before sending it. How do you do this?\n\nFirst let's define our `Human` class:\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Human:\n name: str\n gender: str\n email: str\n phonenumber: str\n address: str\n ...\n\n def get_contact_info(self):\n return {\n \"email\": self.email,\n \"phonenumber\": self.phonenumber,\n }\n```\n\nNow, let's create a cryptkey and an `ObjectCrypt` object:\n\n```python\nimport dcrypt\n\n# Create a cryptkey\ncryptkey = dcrypt.CryptKey()\n\n# Create an ObjectCrypt object\nobject_crypt = dcrypt.ObjectCrypt(key=cryptkey)\n\n# Let save the cryptkey signature to a file\ncryptkey.signature.dump(\"./secrets_folder/cryptkey.json\")\n```\n\nAll that's left is to decorate the `get_contact_info` method with the object crypt we just created:\n\n```python\n\nclass Human:\n ...\n\n @object_crypt\n def get_contact_info(self):\n return {\n \"email\": self.email,\n \"phonenumber\": self.phonenumber,\n }\n```\n\nThat's it! Now, the result of the `get_contact_info` method will be encrypted before it is returned and yes you can decrypt it with the same object crypt or create a new object crypt with the already saved cryptkey signature.\n\n```python\ntolu = Human(\n name=\"Tolu\",\n gender=\"Male\",\n email=\"tioluwa.dev@gmail.com\",\n phonenumber=\"08012345678\",\n address=\"Lagos, Nigeria.\"\n)\n\n# Let's get his contact info\nencrypted_contact_info = tolu.get_contact_info()\n\n# The output would be something like:\n# {\n# \"email\": \"gAAAAABgJ0Z...\",\n# \"phonenumber\": \"gAAAAABgJ0Z...\",\n# }\n\n# Now, let's decrypt it\nsignature = dcrypt.Signature.load(\"./secrets_folder/cryptkey.json\")\nnew_cryptkey = dcrypt.CryptKey(signature=signature)\nnew_object_crypt = dcrypt.ObjectCrypt(key=new_cryptkey)\ndecrypted_contact_info = new_object_crypt.decrypt(contact_info)\n\n# The output should be:\n# {\n# \"email\": \"tioluwa.dev@gmail\",\n# \"phonenumber\": \"08012345678\",\n# }\n```\n\nYou are now ready to use `dcrypt` to encrypt and decrypt your data. Goodluck!\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Testing\n\nTo run the tests, simply run the following command in the root directory of your cloned repository:\n\n```bash\npython -m unittest discover tests \"test_*.py\"\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Encrypt text and Python objects using RSA + Fernet encryption.",
"version": "0.0.6",
"project_urls": {
"Bug Tracker": "https://github.com/ti-oluwa/dcrypt/issues",
"Homepage": "https://github.com/ti-oluwa/dcrypt",
"Repository": "https://github.com/ti-oluwa/dcrypt"
},
"split_keywords": [
"encryption",
" decryption",
" rsa",
" fernet",
" cryptography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ecc45aad21d2c372845112702c79ce274b0ce0150e0dccdcfdf11190b411a84c",
"md5": "342169fead6a46a3dc784e9576e14d13",
"sha256": "08a5aee8e48e7d51e3c07e7ff6d3babaa4cb704142e90ef8a11ff9ad4f8c7897"
},
"downloads": -1,
"filename": "dcrypt-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "342169fead6a46a3dc784e9576e14d13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13847,
"upload_time": "2024-09-22T20:06:00",
"upload_time_iso_8601": "2024-09-22T20:06:00.275131Z",
"url": "https://files.pythonhosted.org/packages/ec/c4/5aad21d2c372845112702c79ce274b0ce0150e0dccdcfdf11190b411a84c/dcrypt-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c84bae3dfb4a9314c35352b0471055b7bff49b7025985054878ea949e7444e9b",
"md5": "7b01523de4e8db57f7174e1e8bbce49d",
"sha256": "bd5be297f6b53aa0f06a10617285eb2f62808806522f36b8fd9f7d8983a8480b"
},
"downloads": -1,
"filename": "dcrypt-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "7b01523de4e8db57f7174e1e8bbce49d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15924,
"upload_time": "2024-09-22T20:06:03",
"upload_time_iso_8601": "2024-09-22T20:06:03.372060Z",
"url": "https://files.pythonhosted.org/packages/c8/4b/ae3dfb4a9314c35352b0471055b7bff49b7025985054878ea949e7444e9b/dcrypt-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-22 20:06:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ti-oluwa",
"github_project": "dcrypt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "rsa",
"specs": [
[
">=",
"4.7.2"
]
]
},
{
"name": "cryptography",
"specs": [
[
">=",
"41.0.4"
]
]
},
{
"name": "simple_file_handler",
"specs": [
[
">=",
"0.0.1"
]
]
}
],
"lcname": "dcrypt"
}
JSON
