diff --git a/doc/readme/cryptography.md b/doc/readme/cryptography.md index afb48aa49..42cf3b97d 100644 --- a/doc/readme/cryptography.md +++ b/doc/readme/cryptography.md @@ -1,10 +1,12 @@ # Cryptography -* [File encryption](#file-encryption) -* [File hashing](#file-hashing) +* [File Encryption](#file-encryption) +* [File Hashing](#file-hashing) +* [String/Byte Encryption](#string-byte-encryption) +* [String/Password Hashing](#string-password-hashing) -## File encryption +## File Encryption Venice supports encrypting and decrypting files, streams and buffers using AES and ChaCha20, both with 256 bit keys: @@ -123,7 +125,7 @@ Decrypt ChaCha20-BC: 74ms 73ms 74ms 85ms 160ms 931ms ``` -## File hashing +## File Hashing Venice computes hashes for files, streams, and buffers with the algorithms MD5, SHA-1, and SHA-256. @@ -183,3 +185,178 @@ Hash SHA-1 (memory): 0ms 1ms 1ms 7ms 64ms 642ms Hash SHA-256 (memory): 1ms 0ms 1ms 8ms 76ms 749ms -------------------------------------------------------------------- ``` + + + +## String/Byte Encryption + +Venice supports DES, 3DES and AES256. + + +### Encryption + +Encrypting strings: + +```clojure +(do + (load-module :crypt) + + ;; define the encryption function + (def encrypt (crypt/encrypt "3DES" "secret" :url-safe true)) + + (encrypt "hello") ; => "ndmW1NLsDHA" + (encrypt "world") ; => "KPYjndkZ8vM" +) +``` + +Encrypting bytebufs: + +```clojure +(do + (load-module :crypt) + (load-module :hexdump) + + ;; define the encryption function + (def encrypt (crypt/encrypt "AES256" "secret" :url-safe true)) + + (-> (encrypt (bytebuf [ 0 1 2 3 4 5 6 7 8 9 + 10 11 12 13 14 15 16 17 18 19])) + (hexdump/dump))) +``` + +Encrypts a string or a bytebuf. String data is returned as Base64 encoded string. + +The :url-safe option controls the base64 encoding regarding URL safety. +If _true_ the base64 encoder will emit '-' and '_' instead of the usual +'+' and '/' characters. Defaults to _false_. + +Note: no padding is added when encoding using the URL-safe alphabet. + +Supported algorithms: DES, 3DES, AES256 + + +### Decryption + +The crypt/decrypt function expects a Base64 encoded string or a bytebuf. + +Decrypting strings: + +```clojure +(do + (load-module :crypt) + + ;; define the encryption/decryption function + (def encrypt (crypt/encrypt "3DES" "secret" :url-safe true)) + (def decrypt (crypt/decrypt "3DES" "secret" :url-safe true)) + + (-> (encrypt "hello") + (decrypt))) +``` + +Decrypting bytebufs: + +```clojure +(do + (load-module :crypt) + + ;; define the decryption function + (def decrypt (crypt/decrypt "3DES" "secret" :url-safe true)) + + + (-> (encrypt (bytebuf [ 0 1 2 3 4 5 6 7 8 9 + 10 11 12 13 14 15 16 17 18 19])) + (decrypt))) +``` + + +## String/Password Hashing + +Venice supports PBKDF2, SHA-512, SHA-1, and MD5 for hashing strings. + + +### PBKDF2 + +PBKDF2 is the preferred hashing algorithm to hash password. + +Just using a salt: + +```clojure +(do + (load-module :crypt) + + (-> (crypt/pbkdf2-hash "hello world" "-salt-") + (str/bytebuf-to-hex :upper))) +``` + +Specifying a salt, the number of iterations, and key length: + +```clojure +(do + (load-module :crypt) + + (-> (crypt/pbkdf2-hash "hello world" "-salt-" 1000 256) + (str/bytebuf-to-hex :upper))) +``` + + +### SHA-512 + +```clojure +(do + (load-module :crypt) + + (-> (crypt/sha512-hash "hello world" "-salt-") + (str/bytebuf-to-hex :upper))) +``` + +```clojure +(do + (load-module :crypt) + + (-> (crypt/sha512-hash (bytebuf [54 78 99]) "-salt-") + (str/bytebuf-to-hex :upper))) +``` + + +### SHA-1 + +```clojure +(do + (load-module :crypt) + + (-> (crypt/sha1-hash "hello world" "-salt-") + (str/bytebuf-to-hex :upper))) +``` + +```clojure +(do + (load-module :crypt) + + (-> (crypt/sha1-hash (bytebuf [54 78 99]) "-salt-") + (str/bytebuf-to-hex :upper))) +``` + + +### MD5 + +Warning: The MD5 hash function’s security is considered to be +severely compromised. Collisions can be found within seconds, +and they can be used for malicious purposes. + +```clojure +(do + (load-module :crypt) + + (-> (crypt/md5-hash "hello world") + (str/bytebuf-to-hex :upper))) +``` + +```clojure +(do + (load-module :crypt) + + (-> (crypt/md5-hash (bytebuf [54 78 99])) + (str/bytebuf-to-hex :upper))) +``` + + diff --git a/doc/readme/ext-crypt.md b/doc/readme/ext-crypt.md deleted file mode 100644 index 399b56033..000000000 --- a/doc/readme/ext-crypt.md +++ /dev/null @@ -1,131 +0,0 @@ -# Cryptographic Functions - - -## Hashes - -Venice supports PBKDF2, SHA-512, SHA-1, and MD5 hashes. - -### PBKDF2 - -Just using a salt: - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/pbkdf2-hash "hello world" "-salt-") - :upper)) -``` - -Specifying a salt, the number of iterations, and key length: - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/pbkdf2-hash "hello world" "-salt-" 1000 256) - :upper)) -``` - - -### SHA-512 - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/sha512-hash "hello world" "-salt-") - :upper)) -``` - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/sha512-hash (bytebuf [54 78 99]) "-salt-") - :upper)) -``` - - -### SHA-1 - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/sha1-hash "hello world" "-salt-") - :upper)) -``` - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/sha1-hash (bytebuf [54 78 99]) "-salt-") - :upper)) -``` - - -### MD5 - -Note: MD5 is not safe anymore use PBKDF2 instead to hash passwords - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/md5-hash "hello world") - :upper)) -``` - -```clojure -(do - (load-module :crypt) - - (str/bytebuf-to-hex - (crypt/md5-hash (bytebuf [54 78 99])) - :upper)) -``` - - -## Encryption - -```clojure -(do - (def encrypt (crypt/encrypt "3DES" "secret" :url-safe true)) - (encrypt "hello") ; => "ndmW1NLsDHA" - (encrypt "world") ; => "KPYjndkZ8vM" - (encrypt (bytebuf [1 2 3 4 5])) ; => [234 220 237 189 12 176 242 147] -) -``` - -Encrypts a string or a bytebuf. String data is returned as base64 encoded string. - -The :url-safe option controls the base64 encoding regarding URL safety. -If _true_ the base64 encoder will emit '-' and '_' instead of the usual -'+' and '/' characters. Defaults to _false_. - -Note: no padding is added when encoding using the URL-safe alphabet. - -Supported algorithms: "DES", "3DES", "AES256" - - -## Decryption - -```clojure -(do - (def decrypt (crypt/decrypt "3DES" "secret" :url-safe true)) - (decrypt "ndmW1NLsDHA") ; => "hello" - (decrypt "KPYjndkZ8vM") ; => "world" - (decrypt (bytebuf [234 220 237 189 12 176 242 147])) ; => [1 2 3 4 5] -) -``` - -The decrypt function expects a base64 encoded string or a bytebuf. diff --git a/doc/readme/extension-modules.md b/doc/readme/extension-modules.md index 82dcd308b..2ce4d8c74 100644 --- a/doc/readme/extension-modules.md +++ b/doc/readme/extension-modules.md @@ -21,7 +21,6 @@ and loads a module only once and skips subsequent load attempts. * [CIDR (Classless Inter-Domain Routing)](ext-cidr.md) * [Semantic Versioning](ext-semver.md) * [XML](ext-xml.md) -* [Cryptographic Functions](ext-crypt.md) * [Apache Tomcat WEB Server](ext-tomcat.md) * [Ring WEB App library](ext-ring.md) * [WebDAV](ext-webdav.md)