From 194ed5f4ef65690efd361a3df45cd6be9663d854 Mon Sep 17 00:00:00 2001 From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com> Date: Tue, 17 Sep 2019 04:20:38 -0700 Subject: [PATCH] Add Documentation. --- README.md | 32 ++++++++++++++++++++++++------- examples/constants.cr | 6 +++--- src/sodium/password.cr | 12 +++++++----- src/sodium/password/abstract.cr | 7 +++---- src/sodium/password/create_key.cr | 3 +++ src/sodium/password/hash.cr | 17 ++++++++++++++++ src/sodium/password/params.cr | 20 +++++++++---------- 7 files changed, 68 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 713dddb..f03c3d0 100644 --- a/README.md +++ b/README.md @@ -83,8 +83,8 @@ Several features in libsodium are already provided by Crystal: | [`Sodium::Cipher::SecretStream`](https://didactic-drunk.github.io/sodium.cr/Sodium/Cipher/SecretStream/XChaCha20Poly1305.html) | I have a shared key and want encrypt + authenticate streamed data. | | [`Sodium::Digest::Blake2b`](https://didactic-drunk.github.io/sodium.cr/Sodium/Digest::Blake2b.html) | I want to hash data fast and securely. | | `Sodium::Digest::SipHash` | I want to hash data really fast and less securely. (Not implemented yet) | -| [`Sodium::Pwhash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Pwhash.html) | I want to hash a password and store it. | -| [`Sodium::Pwhash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Pwhash.html) | I want to derive a key from a password. | +| [`Sodium::Password::Hash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Password/Hash.html) | I want to hash a password and store it. | +| [`Sodium::Password::Key`](https://didactic-drunk.github.io/sodium.cr/Sodium/Password/Key.html) | I want to derive a key from a password. | | [`Sodium::Kdf`](https://didactic-drunk.github.io/sodium.cr/Sodium/Kdf.html) | I have a high quality master key and want to make subkeys. | | [`Sodium::Cipher::Chalsa`](https://didactic-drunk.github.io/sodium.cr/Sodium/Cipher/Chalsa.html) | What goes with guacamole? | | Everything else | I want to design my own crypto protocol and probably do it wrong. | @@ -228,15 +228,31 @@ subkey3 = kdf.derive "context2", 0, 32 subkey4 = kdf.derive "context2", 1, 64 ``` -### Password Hashing +### Password based keys ```crystal -pwhash = Sodium::Pwhash.new +pwcreate = Sodium::Password::Key::Create.new -pwhash.memlimit = Sodium::Pwhash::MEMLIMIT_MIN -pwhash.opslimit = Sodium::Pwhash::OPSLIMIT_MIN +# Take approximately 1 second to derive a key. +pwcreate.tcost = 1.0 pass = "1234" -hash = pwhash.hash_str pass +key, params = pwcreate.create_key pass +# Store `params` or `params.to_h` for later. + +# Derive the same key from the stored params. +pwkey = Sodium::Password::Key.from_params params.to_h +key = pekey.derive_key pass +``` + +### Password Hashing +```crystal +pwhash = Sodium::Password::Hash.new + +pwhash.mem = Sodium::Password::MEMLIMIT_MIN +pwhash.ops = Sodium::Password::OPSLIMIT_MIN + +pass = "1234" +hash = pwhash.create pass pwhash.verify hash, pass ``` @@ -260,6 +276,8 @@ Ops limit → | 2097152K | 2.119s | | Memory | + + ## Contributing 1. Fork it ( https://github.com/didactic-drunk/sodium.cr/fork ) diff --git a/examples/constants.cr b/examples/constants.cr index 9c4e0b4..9c05ae3 100644 --- a/examples/constants.cr +++ b/examples/constants.cr @@ -23,17 +23,17 @@ puts "" puts "" {% for name in %w(OPSLIMIT_MIN OPSLIMIT_INTERACTIVE OPSLIMIT_MODERATE OPSLIMIT_SENSITIVE OPSLIMIT_MAX) %} - puts "Sodium::Password::{{ name.id }} #{Sodium::Pwhash::{{ name.id }}}" + puts "Sodium::Password::{{ name.id }} #{Sodium::Password::{{ name.id }}}" {% end %} puts "" {% for name in %w(MEMLIMIT_MIN MEMLIMIT_INTERACTIVE MEMLIMIT_MAX) %} - puts "Sodium::Password::{{ name.id }} #{Sodium::Pwhash::{{ name.id }}}" + puts "Sodium::Password::{{ name.id }} #{Sodium::Password::{{ name.id }}}" {% end %} puts "" {% for name in %w(SALT_SIZE STR_SIZE) %} - puts "Sodium::Password::{{ name.id }} #{Sodium::Pwhash::{{ name.id }}}" + puts "Sodium::Password::{{ name.id }} #{Sodium::Password::{{ name.id }}}" {% end %} puts "" diff --git a/src/sodium/password.cr b/src/sodium/password.cr index 242e9b8..e9db0c9 100644 --- a/src/sodium/password.cr +++ b/src/sodium/password.cr @@ -2,13 +2,15 @@ require "./lib_sodium" require "./secure_buffer" # [Argon2 Password Hashing](https://libsodium.gitbook.io/doc/password_hashing/the_argon2i_function) -# * #store #verify #needs_rehash? are used together for password verification. -# * #derive_key is used on it's own to generate password based keys. +# * `Sodium::Password::Hash` +# * - Use for server side authentication replacing scrypt, bcrypt or crypt. +# * `Sodium::Password::Key::Create` +# * - Use to create a key with auto set parameters based on time. +# * - Often used in single user application such as password safes, gpg/ssh keys or other encrypted storage. +# * `Sodium::Password::Key` +# * - Use with the `params` returned by `Create#create_key` or set your own to derive a consistent key or kdf. # # **See `examples/pwhash_selector.cr` for help on selecting parameters.** -# -# ## Creating a key for encryption with auto set parameters based on time. -# module Sodium::Password OPSLIMIT_MIN = LibSodium.crypto_pwhash_opslimit_min OPSLIMIT_INTERACTIVE = LibSodium.crypto_pwhash_opslimit_interactive diff --git a/src/sodium/password/abstract.cr b/src/sodium/password/abstract.cr index 15aa3a6..fc67181 100644 --- a/src/sodium/password/abstract.cr +++ b/src/sodium/password/abstract.cr @@ -1,5 +1,4 @@ -require "../lib_sodium" -require "../secure_buffer" +require "../password" abstract class Sodium::Password::Abstract property ops = OPSLIMIT_INTERACTIVE @@ -29,8 +28,8 @@ abstract class Sodium::Password::Abstract if pw.responds_to?(:tcost=) && (tcost = hash["tcost"]?) pw.tcost = tcost.as(Float64) end - if pw.responds_to?(:auth=) && (auth = hash["auth"]?) - pw.auth = auth.as(Bytes) + if pw.responds_to?(:verify=) && (verify = hash["verify"]?) + pw.verify = verify.as(Bytes) end pw diff --git a/src/sodium/password/create_key.cr b/src/sodium/password/create_key.cr index 7df8e9e..b25c832 100644 --- a/src/sodium/password/create_key.cr +++ b/src/sodium/password/create_key.cr @@ -20,12 +20,15 @@ require "./key" # key, params = pwkc.create_key pass, 32 # # # Save params.[mode, ops, mem, salt, key_size] to derive the same key later. +# # Or serialize `params.to_h` # ``` # # ## Deriving a previously created key. # # Usage: # ``` +# pwkey = Sodium::Password::Key.from_params hash +# # Or # pwkey = Sodium::Password::Key.new # pwkey.mode = Mode.parse serialized[:mode] # pwkey.ops = serialized[:ops] diff --git a/src/sodium/password/hash.cr b/src/sodium/password/hash.cr index 80b594f..73121f7 100644 --- a/src/sodium/password/hash.cr +++ b/src/sodium/password/hash.cr @@ -1,6 +1,23 @@ require "./abstract" module Sodium::Password + # Argon2 password hashing. A modern substitute for scrypt, bcrypt or crypt. + # + # Often used to store password hashes on a server and authenticate clients against the stored hash. + # + # Usage: + # ```crystal + # pwhash = Sodium::Password::Hash.new + # + # pwhash.mem = Sodium::Password::MEMLIMIT_MIN + # pwhash.ops = Sodium::Password::OPSLIMIT_MIN + # + # pass = "1234" + # hash = pwhash.create pass + # pwhash.verify hash, pass + # ``` + # + # Use `examples/pwhash_selector.cr` to help choose ops/mem limits. class Hash < Abstract # Apply the most recent password hashing algorithm against a password. # Returns a opaque String which includes: diff --git a/src/sodium/password/params.cr b/src/sodium/password/params.cr index 4c394c0..a16f3cf 100644 --- a/src/sodium/password/params.cr +++ b/src/sodium/password/params.cr @@ -1,14 +1,18 @@ # Contains the params necessary for #derive_key. class Sodium::Password::Params - property mode : Mode property ops : UInt64 property mem : UInt64 + property mode : Mode? property salt : Bytes? property key_size : Int32? - property tcost : Float64? - property auth : Bytes? - def initialize(@mode, @ops, @mem, @salt = nil, @key_size = nil, @tcost = nil, @auth = nil) + # Information only. Not used to derive a key. + property tcost : Float64? + + # Application specific param to verify a password. + property verify : Bytes? + + def initialize(@mode, @ops, @mem, @salt = nil, @key_size = nil, @tcost = nil, @verify = nil) end def to_h @@ -27,14 +31,10 @@ class Sodium::Password::Params if ks = @key_size hash["key_size"] = ks end - if au = @auth - hash["auth"] = au + if v = @verify + hash["verify"] = v end hash end - - def self.from_h(hash) - self.new Pwhash::Mode.parse(hash["mode"]), hash["ops"], hash["mem"], hash["tcost"]?, hash["salt"]? - end end