README.md: What? Why?
This commit is contained in:
parent
46f53c8e89
commit
838dba2705
64
README.md
64
README.md
@ -4,7 +4,19 @@
|
|||||||
![GitHub commits since latest release (by date) for a branch](https://img.shields.io/github/commits-since/didactic-drunk/crypto-secret.cr/latest)
|
![GitHub commits since latest release (by date) for a branch](https://img.shields.io/github/commits-since/didactic-drunk/crypto-secret.cr/latest)
|
||||||
[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://didactic-drunk.github.io/crypto-secret.cr/main)
|
[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://didactic-drunk.github.io/crypto-secret.cr/main)
|
||||||
|
|
||||||
Interface intended to hold sensitive information.
|
Secrets hold sensitive information
|
||||||
|
|
||||||
|
The Secret interface manages limited time access to the secret and securely erasing the secret when no longer needed.
|
||||||
|
|
||||||
|
Secret providers may implement additional protections via:
|
||||||
|
* `#noaccess`, `#readonly` or `readwrite`.
|
||||||
|
* Using [mprotect]() to control access
|
||||||
|
* Encrypting the data when not in use
|
||||||
|
* Deriving keys on demand from a HSM
|
||||||
|
* Preventing the Secret from entering swap ([mlock]())
|
||||||
|
* Preventing the Secret from entering core dumps
|
||||||
|
* Other
|
||||||
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
@ -24,11 +36,45 @@ Interface intended to hold sensitive information.
|
|||||||
require "crypto-secret/not"
|
require "crypto-secret/not"
|
||||||
|
|
||||||
not_secret = Crypto::Secret::Not.new 32
|
not_secret = Crypto::Secret::Not.new 32
|
||||||
|
not_secret.wipe do
|
||||||
|
not_secret.readonly do |slice|
|
||||||
|
# May only read slice
|
||||||
|
end
|
||||||
|
not_secret.readwrite do |slice|
|
||||||
|
# May read or write to slice
|
||||||
|
end
|
||||||
|
end # Secret is erased
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## What is a Secret?
|
||||||
|
|
||||||
|
<strike>Secrets are Keys</strike>
|
||||||
|
That's complicated and specific to the application. Some examples:
|
||||||
|
|
||||||
|
* Passwords
|
||||||
|
* A crypto key is always a Secret. Except when used for verification (sometimes)
|
||||||
|
* A decrypted password vault (but it's not a Key)
|
||||||
|
|
||||||
|
Not secrets:
|
||||||
|
|
||||||
|
* Digest output. Except when used for key derivation, then it's a Secret, including the Digest state
|
||||||
|
* IO::Memory or writing a file. Except when the file is a password vault, cryptocurrency wallet, encrypted mail/messages, goat porn, maybe normal porn, sometimes scat porn, occassionally furry, not vanilla porn
|
||||||
|
|
||||||
|
## Why?
|
||||||
|
|
||||||
|
The Secret interface is designed to handle varied levels of confidentiality with a unified API for cryptography libraries.
|
||||||
|
|
||||||
|
There is no one size fits all solution. Different applications have different security requirements. Sometimes for the same algorithm.
|
||||||
|
|
||||||
|
A master key (kgk) may reside on a HSM and generate subkeys on demand.
|
||||||
|
Or for most applications the master key may use best effort protection using a combination of [guard pages, mlock, mprotect].
|
||||||
|
Other keys in the same application may handle a high volume of messages where [guard pages, mlock, mprotect] overhead is too high.
|
||||||
|
A key verifying a public key signature may not be Secret.
|
||||||
|
|
||||||
|
|
||||||
## Implementing a new Secret holding class
|
## Implementing a new Secret holding class
|
||||||
|
|
||||||
**Intended for use by crypto library authors**
|
**Only intended for use by crypto library authors**
|
||||||
|
|
||||||
```
|
```
|
||||||
class MySecret
|
class MySecret
|
||||||
@ -39,18 +85,26 @@ class MySecret
|
|||||||
# optionally mlock
|
# optionally mlock
|
||||||
end
|
end
|
||||||
|
|
||||||
def to_slice : Bytes
|
def to_slice(& : Bytes -> Nil)
|
||||||
# Return a slice
|
# yield Slice.new(pointer, size)
|
||||||
# Slice.new pointer, size
|
ensure
|
||||||
|
# optionally reencrypt or signal HSM
|
||||||
|
end
|
||||||
|
|
||||||
|
def bytesize : Int32
|
||||||
|
# return the size
|
||||||
end
|
end
|
||||||
|
|
||||||
# optionally override [noaccess, readonly, readwrite]
|
# optionally override [noaccess, readonly, readwrite]
|
||||||
|
# optionally override (almost) any other method with implementation specific version
|
||||||
end
|
end
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
|
**Open a discussion before creating PR's**
|
||||||
|
|
||||||
1. Fork it (<https://github.com/your-github-user/crypto-secret/fork>)
|
1. Fork it (<https://github.com/your-github-user/crypto-secret/fork>)
|
||||||
2. Create your feature branch (`git checkout -b my-new-feature`)
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
||||||
3. Commit your changes (`git commit -am 'Add some feature'`)
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
||||||
|
Loading…
Reference in New Issue
Block a user