Added some docs on hashing and encryption

Ezeudoh Tochukwu · Ezeudoh Tochukwu · commit 9a9b20ba6ddb · 2023-10-21T11:35:54.000+01:00
diff --git a/docs/security/encryption_and_hashing.md b/docs/security/encryption_and_hashing.md
@@ -0,0 +1,115 @@
+# **Encryption and Hashing**
+
+**Encryption** is the method of transforming data. This process changes the original information, referred to as plaintext, 
+into an alternative form called ciphertext. 
+The goal is to ensure that only authorized parties possess the capability to decrypt ciphertext back into plaintext and access the original information. 
+Encryption doesn't inherently prevent interference but rather restricts the intelligible content from potential interceptors. 
+Encryption is a bidirectional operation; what's encrypted can be decrypted using the correct key.
+
+**Hashing** is the process of converting a given key into another value. 
+A hash function is employed to create this new value following a mathematical algorithm. 
+After hashing is applied, it should be practically impossible to reverse the process and derive the original 
+input from the output.
+
+## **Encryption**
+In Python, the [`cryptography`](https://pypi.org/project/cryptography/) library provides a user-friendly way to implement encryption. 
+One common encryption scheme is Fernet, which offers symmetric key encryption.
+
+For example,
+```python
+from cryptography.fernet import Fernet
+
+# Generate a random encryption key
+key = Fernet.generate_key()
+
+# Create a Fernet cipher object with the key
+cipher_suite = Fernet(key)
+
+# Text to be encrypted
+plaintext = b"Hello, this is a secret message!"
+
+# Encrypt the plaintext
+cipher_text = cipher_suite.encrypt(plaintext)
+
+# Decrypt the ciphertext
+decrypted_text = cipher_suite.decrypt(cipher_text)
+
+# Convert bytes to string for printing
+original_message = decrypted_text.decode("utf-8")
+
+print("Original Message: ", plaintext)
+print("Encrypted Message: ", cipher_text)
+print("Decrypted Message: ", original_message)
+
+```
+The provided Python example demonstrates this process, securing a message with encryption and then decrypting it using the same key. 
+It's crucial to manage encryption keys securely in real applications to maintain the confidentiality and integrity of your data.
+
+## **Hashing**
+For hashing, Ellar works with [passlib](https://pypi.org/project/passlib/) and [hashlib](https://docs.python.org/3/library/hashlib.html)
+to create a wrapper around some hashing algorithms listed below,
+
+- **PBKDF2Hasher**: `pbkdf2_sha256` hashing algorithm wrapper
+- **PBKDF2SHA1Hasher**: `pbkdf2_sha1` hashing algorithm wrapper
+- **Argon2Hasher**: `argon2` hashing algorithm wrapper
+- **BCryptSHA256Hasher**: `bcrypt_sha256` hashing algorithm wrapper
+- **BCryptHasher**: `bcrypt` hashing algorithm wrapper
+- **ScryptHasher**: `scrypt` hashing algorithm wrapper
+- **MD5Hasher**: `md5` hashing algorithm wrapper
+
+## **Password Hashing**
+Ellar provides two important utility functions: `make_password` for password hashing 
+and `check_password` for password validation. Both of these functions are available in the 
+`ellar.core.security.hashers` package.
+
+```python
+def make_password(
+    password: str|bytes,
+    algorithm: str = "pbkdf2_sha256",
+    salt: str|None = None,
+) -> str:
+    pass
+
+
+def check_password(
+    password: str|bytes,
+    encoded: str,
+    setter: Callable[..., Any]|None = None,
+    preferred_algorithm: str = "pbkdf2_sha256",
+) -> bool:
+    pass
+```
+
+The `make_password` function takes plain text and generates a hashed result based on the provided hash algorithm. 
+In the code snippet above, the default algorithm for `make_password` is `pbkdf2_sha256`.
+
+The [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) algorithm with a SHA256 hash is a password stretching mechanism recommended by [NIST](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf).
+This should be sufficient for most users as it is quite secure and requires massive amounts of computing time to break.
+
+!!! note
+    All hashing wrappers are registered as `key-value` pairs and can be accessed by the algorithm names
+    using the get_hasher utility function in the `ellar.core.security.hashers` package.
+
+For an example,
+```python
+from ellar.core.security.hashers import make_password
+
+## Using pbkdf2_sha256 - PBKDF2Hasher
+password_hash = make_password('mypassword1234', algorithm="pbkdf2_sha256", salt='seasalt')
+print(password_hash)
+# pbkdf2_sha256$870000$seasalt$XE8bb8u57rxvyv2SThRFtMg9mzJLff2wjm3J8kGgFVI=
+
+## Using bcrypt_sha256 - BCryptSHA256Hasher
+password_hash = make_password('mypassword1234', algorithm="bcrypt_sha256", salt='20AmWL1wKJZAHPiI1HEk4k')
+print(password_hash)
+# bcrypt_sha256$$2b$12$20AmWL1wKJZAHPiI1HEk4eZuAlMGHkK1rw4oou26bnwGmAE8F0JGK
+```
+
+On the other hand, you can check or validate a password using the `check_password` function.
+
+```python
+from ellar.core.security.hashers import check_password
+
+hash_secret = "bcrypt_sha256$$2b$12$20AmWL1wKJZAHPiI1HEk4eZuAlMGHkK1rw4oou26bnwGmAE8F0JGK"
+assert check_password('mypassword1234', hash_secret) # True
+```
diff --git a/ellar/core/security/hashers/__init__.py b/ellar/core/security/hashers/__init__.py
@@ -1,26 +1,26 @@
 import typing as t
 
-from .argon2 import Argon2PasswordHasher
-from .base import BasePasswordHasher, EncodingType, get_random_string, must_update_salt
-from .bcrypt import BCryptPasswordHasher, BCryptSHA256PasswordHasher
-from .md5 import MD5PasswordHasher
-from .pbkdf import PBKDF2PasswordHasher, PBKDF2SHA1PasswordHasher
-from .scrypt import ScryptPasswordHasher
+from .argon2 import Argon2Hasher
+from .base import BaseHasher, EncodingType, get_random_string, must_update_salt
+from .bcrypt import BCryptHasher, BCryptSHA256Hasher
+from .md5 import MD5Hasher
+from .pbkdf import PBKDF2Hasher, PBKDF2SHA1Hasher
+from .scrypt import ScryptHasher
 
 # This will never be a valid encoded hash
 _UNUSABLE_PASSWORD_PREFIX = "!"
 _UNUSABLE_PASSWORD_SUFFIX_LENGTH = (
     40  # number of random chars to add after UNUSABLE_PASSWORD_PREFIX
 )
-__HASHERS_DICT: t.Dict[str, t.Type["BasePasswordHasher"]] = {}
+__HASHERS_DICT: t.Dict[str, t.Type["BaseHasher"]] = {}
 
 
-def add_hasher(*hashers: t.Type["BasePasswordHasher"]) -> None:
+def add_hasher(*hashers: t.Type["BaseHasher"]) -> None:
     for hasher in hashers:
         __HASHERS_DICT.update({hasher.algorithm: hasher})
 
 
-def get_hasher(algorithm: str = "pbkdf2_sha256") -> "BasePasswordHasher":
+def get_hasher(algorithm: str = "pbkdf2_sha256") -> "BaseHasher":
     try:
         hasher_type = __HASHERS_DICT[algorithm]
         return hasher_type()
@@ -31,7 +31,7 @@ def get_hasher(algorithm: str = "pbkdf2_sha256") -> "BasePasswordHasher":
         ) from kex
 
 
-def identify_hasher(encoded: str) -> "BasePasswordHasher":
+def identify_hasher(encoded: str) -> "BaseHasher":
     possible_hashers = [v for k, v in __HASHERS_DICT.items() if v.identity(encoded)]
     if possible_hashers:
         return possible_hashers[0]()
@@ -83,8 +83,8 @@ def check_password(
     Return a boolean of whether the raw password matches the three
     part encoded digest.
 
-    If setter is specified, it'll be called when you need to
-    regenerate the password.
+    If setter is specified, it'll be called if a password hash needs to be updated
+     or regenerated based on the `preferred_algorithm`
     """
 
     if password is None or not is_password_usable(encoded):
@@ -107,23 +107,24 @@ def check_password(
 
 
 add_hasher(
-    PBKDF2PasswordHasher,
-    PBKDF2SHA1PasswordHasher,
-    Argon2PasswordHasher,
-    BCryptSHA256PasswordHasher,
-    BCryptPasswordHasher,
-    ScryptPasswordHasher,
-    MD5PasswordHasher,
+    PBKDF2Hasher,
+    PBKDF2SHA1Hasher,
+    Argon2Hasher,
+    BCryptSHA256Hasher,
+    BCryptHasher,
+    ScryptHasher,
+    MD5Hasher,
 )
 
 __all__ = [
-    "PBKDF2PasswordHasher",
-    "PBKDF2SHA1PasswordHasher",
-    "Argon2PasswordHasher",
-    "BCryptSHA256PasswordHasher",
-    "BCryptPasswordHasher",
-    "ScryptPasswordHasher",
-    "MD5PasswordHasher",
+    "BaseHasher",
+    "PBKDF2Hasher",
+    "PBKDF2SHA1Hasher",
+    "Argon2Hasher",
+    "BCryptSHA256Hasher",
+    "BCryptHasher",
+    "ScryptHasher",
+    "MD5Hasher",
     "must_update_salt",
     "make_password",
     "check_password",
diff --git a/ellar/core/security/hashers/argon2.py b/ellar/core/security/hashers/argon2.py
@@ -2,10 +2,10 @@
 
 from passlib.hash import argon2
 
-from .base import BasePasswordHasher, EncodingSalt, EncodingType, must_update_salt
+from .base import BaseHasher, EncodingSalt, EncodingType, must_update_salt
 
 
-class Argon2PasswordHasher(BasePasswordHasher):
+class Argon2Hasher(BaseHasher):
     """
     Secure password hashing using the argon2 algorithm.
 
diff --git a/ellar/core/security/hashers/base.py b/ellar/core/security/hashers/base.py
@@ -13,7 +13,7 @@
 
 RANDOM_STRING_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
-__HASHERS_DICT: t.Dict[str, t.Type["BasePasswordHasher"]] = {}
+__HASHERS_DICT: t.Dict[str, t.Type["BaseHasher"]] = {}
 EncodingType = t.Union[str, bytes]
 EncodingSalt = t.Optional[t.Union[str, bytes]]
 
@@ -39,7 +39,7 @@ def get_random_string(length: int, allowed_chars: str = RANDOM_STRING_CHARS) ->
     )  # pragma no cover
 
 
-class BasePasswordHasher(ABC):
+class BaseHasher(ABC):
     hasher: t.Union[t.Type[uh.GenericHandler], t.Any]
     algorithm: str
     salt_entropy: int = 128
diff --git a/ellar/core/security/hashers/bcrypt.py b/ellar/core/security/hashers/bcrypt.py
@@ -1,9 +1,9 @@
 from passlib.hash import django_bcrypt, django_bcrypt_sha256
 
-from .base import BasePasswordHasher
+from .base import BaseHasher
 
 
-class BCryptSHA256PasswordHasher(BasePasswordHasher):
+class BCryptSHA256Hasher(BaseHasher):
     """
     Secure password hashing using the bcrypt algorithm (recommended)
 
@@ -38,7 +38,7 @@ def must_update(self, encoded: str) -> bool:
         return decoded["work_factor"] != self.rounds  # type:ignore[no-any-return]
 
 
-class BCryptPasswordHasher(BCryptSHA256PasswordHasher):
+class BCryptHasher(BCryptSHA256Hasher):
     """
     Secure password hashing using the bcrypt algorithm
 
diff --git a/ellar/core/security/hashers/md5.py b/ellar/core/security/hashers/md5.py
@@ -2,10 +2,10 @@
 
 from passlib.hash import md5_crypt
 
-from .base import BasePasswordHasher, EncodingSalt, EncodingType, must_update_salt
+from .base import BaseHasher, EncodingSalt, EncodingType, must_update_salt
 
 
-class MD5PasswordHasher(BasePasswordHasher):
+class MD5Hasher(BaseHasher):
     """
     The Salted MD5 password hashing algorithm (not recommended)
     """
diff --git a/ellar/core/security/hashers/pbkdf.py b/ellar/core/security/hashers/pbkdf.py
@@ -1,9 +1,9 @@
 from passlib.hash import django_pbkdf2_sha1, django_pbkdf2_sha256
 
-from .base import BasePasswordHasher, must_update_salt
+from .base import BaseHasher, must_update_salt
 
 
-class PBKDF2PasswordHasher(BasePasswordHasher):
+class PBKDF2Hasher(BaseHasher):
     """
     Handles PBKDF2 passwords
     """
@@ -31,7 +31,7 @@ def must_update(self, encoded: str) -> bool:
         return (decoded["iterations"] != self.iterations) or update_salt
 
 
-class PBKDF2SHA1PasswordHasher(PBKDF2PasswordHasher):
+class PBKDF2SHA1Hasher(PBKDF2Hasher):
     """
     Alternate PBKDF2 hasher which uses SHA1, the default PRF
     recommended by PKCS #5. This is compatible with other
diff --git a/ellar/core/security/hashers/scrypt.py b/ellar/core/security/hashers/scrypt.py
@@ -3,10 +3,10 @@
 import secrets
 import typing as t
 
-from .base import BasePasswordHasher, EncodingSalt, EncodingType
+from .base import BaseHasher, EncodingSalt, EncodingType
 
 
-class ScryptPasswordHasher(BasePasswordHasher):
+class ScryptHasher(BaseHasher):
     """
     Secure password hashing using the Scrypt algorithm.
     """
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -110,6 +110,7 @@ nav:
   - Security:
       - Authentication: security/authentication.md
       - Authorization: security/authorization.md
+      - Encryption and Hashing: security/encryption_and_hashing.md
       - CSRF and CORS: security/csrf.md
       - Sessions: security/sessions.md
       - Rate Limiting: security/throttling.md
diff --git a/tests/test_hashers.py b/tests/test_hashers.py
