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`
* Wiping memory when the secret is no longer in use
Each implementation may add additional protections
* `Crypto::Secret::Key` - May use mlock, mprotect and canaries in future versions
* `Crypto::Secret::Large` - May use mprotect in future versions
### Provided secret classes
* `Crypto::Secret::Guarded` - Guard pages, mprotect, doesn't appear in core dumps (os dependent)
* `Crypto::Secret::Bidet` - Wipe only. Low overhead.
* `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:
* `#noaccess`, `#readonly` or `#readwrite`
* Using [mprotect]() to control access
* `#noaccess`, `#readonly` or `#readwrite` via `mprotect`
* Encrypting the data when not in use
* Deriving keys on demand from a HSM
* Preventing the Secret from entering swap ([mlock]())
@ -95,6 +93,24 @@ secret = Crypto::Secret::Bidet.new size_in_bytes
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?
<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)
#
# ## Which class should I use?
# * `Crypto::Secret::Key` - Use with small (<= 4096 bytes) keys
# * `Crypto::Secret::Large` - Use for decrypted data that may stress mlock limits
# * `Crypto::Secret::Todo` - Use with small (<= 4096 bytes) keys
# * `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.
#
# Other shards may provide additional `Secret` types ([sodium.cr](https://github.com/didactic-drunk/sodium.cr))