karchnu
/
crypto-secret.cr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation

master
Didactic Drunk 2022-05-22 18:27:59 -07:00
parent 49a999732e
commit 321db6f397
2 changed files with 26 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@ -18,16 +18,14 @@ If you have a high security or high performance application see [which secret ty
* Leaking data in to logs by overriding `inspect` * Leaking data in to logs by overriding `inspect`
* Wiping memory when the secret is no longer in use * Wiping memory when the secret is no longer in use
Each implementation may add additional protections ### Provided secret classes
* `Crypto::Secret::Guarded` - Guard pages, mprotect, doesn't appear in core dumps (os dependent)
* `Crypto::Secret::Key` - May use mlock, mprotect and canaries in future versions * `Crypto::Secret::Bidet` - Wipe only. Low overhead.
* `Crypto::Secret::Large` - May use mprotect in future versions
* `Crypto::Secret::Not` - It's not secret. Doesn't wipe and no additional protection. * `Crypto::Secret::Not` - It's not secret. Doesn't wipe and no additional protection.
* `Crypto::Secret::Todo` - Uses mlock, mprotect and canaries in future versions
Secret providers may implement additional protections via: Secret providers may implement additional protections via:
* `#noaccess`, `#readonly` or `#readwrite` * `#noaccess`, `#readonly` or `#readwrite` via `mprotect`
* Using [mprotect]() to control access
* Encrypting the data when not in use * Encrypting the data when not in use
* Deriving keys on demand from a HSM * Deriving keys on demand from a HSM
* Preventing the Secret from entering swap ([mlock]()) * Preventing the Secret from entering swap ([mlock]())
@ -95,6 +93,24 @@ secret = Crypto::Secret::Bidet.new size_in_bytes
secret.move_from slice secret.move_from slice
``` ```
### Optionally change the security level
The default should be sufficient for most applications. Do not change unless you have special needs.
Password managers or cryptocurrency wallets may prefer :strong or :paranoid.
Blockchain verifiers or apps that only handle high volume public info may prefer :lax.
```crystal
# Choose one
Crypto::Secret::Config.setup :paranoid
Crypto::Secret::Config.setup :strong
#Crypto::Secret::Config.setup :default # automatic
Crypto::Secret::Config.setup :lax
```
See [#setup](https://didactic-drunk.github.io/crypto-secret.cr/main/Crypto/Secret/Config.html) for further information.
## What is a Secret? ## What is a Secret?
<strike>Secrets are Keys</strike> <strike>Secrets are Keys</strike>

5
src/crypto-secret/secret.cr
View File

@ -4,8 +4,9 @@ require "./class_methods"
# Interface to hold sensitive information (often cryptographic keys) # Interface to hold sensitive information (often cryptographic keys)
# #
# ## Which class should I use? # ## Which class should I use?
# * `Crypto::Secret::Key` - Use with small (<= 4096 bytes) keys # * `Crypto::Secret::Todo` - Use with small (<= 4096 bytes) keys
# * `Crypto::Secret::Large` - Use for decrypted data that may stress mlock limits # * `Crypto::Secret::Guarded` - Use for decrypted data that may stress mlock limits
# * `Crypto::Secret::Bidet` - Wipe only with no other protection. General use and fast.
# * `Crypto::Secret::Not` - Only use when you're sure the data isn't secret. 0 overhead. No wiping. # * `Crypto::Secret::Not` - Only use when you're sure the data isn't secret. 0 overhead. No wiping.
# #
# Other shards may provide additional `Secret` types ([sodium.cr](https://github.com/didactic-drunk/sodium.cr)) # Other shards may provide additional `Secret` types ([sodium.cr](https://github.com/didactic-drunk/sodium.cr))