diff --git a/README.md b/README.md index 4267c62..66b34d8 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,9 @@ Secrets hold sensitive information The Secret interface manages limited time access to a secret and securely erases the secret when no longer needed. +Multiple `Secret` classes exist. Most of the time you shouldn't need to change the `Secret` type - the cryptographic library should have sane defaults. +If you have a high security or high performance application see [which secret type should I choose?]() + Secret providers may implement additional protections via: * `#noaccess`, `#readonly` or `#readwrite` * Using [mprotect]() to control access diff --git a/spec/crypto_secret_spec.cr b/spec/crypto_secret_spec.cr index a2b7fc8..7a58ecf 100644 --- a/spec/crypto_secret_spec.cr +++ b/spec/crypto_secret_spec.cr @@ -1,7 +1,10 @@ require "./spec_helper" require "../src/crypto-secret/test" require "../src/crypto-secret/not" -require "../src/crypto-secret/bidet" +require "../src/crypto-secret/large" +require "../src/crypto-secret/key" test_secret_class Crypto::Secret::Not test_secret_class Crypto::Secret::Bidet +test_secret_class Crypto::Secret::Large +test_secret_class Crypto::Secret::Key diff --git a/src/crypto-secret/key.cr b/src/crypto-secret/key.cr new file mode 100644 index 0000000..870fe85 --- /dev/null +++ b/src/crypto-secret/key.cr @@ -0,0 +1,12 @@ +require "./bidet" + +module Crypto::Secret + # Use this class for holding small amounts of sensitive data such as encryption keys + # + # Underlying implentation subject to change + # + # TODO: mlock + # TODO: mprotect + class Key < Bidet + end +end diff --git a/src/crypto-secret/large.cr b/src/crypto-secret/large.cr new file mode 100644 index 0000000..f92144d --- /dev/null +++ b/src/crypto-secret/large.cr @@ -0,0 +1,13 @@ +require "./bidet" + +module Crypto::Secret + # Use this class as a default when holding possibly large amounts of data that may stress mlock limits + # + # Suitable uses: holding decrypted data + # + # no mlock + # + # Implementation subject to change + class Large < Bidet + end +end diff --git a/src/crypto-secret/not.cr b/src/crypto-secret/not.cr index d5c8ee3..e770913 100644 --- a/src/crypto-secret/not.cr +++ b/src/crypto-secret/not.cr @@ -3,6 +3,10 @@ require "./stateless" module Crypto::Secret # A not very secret `Secret`, but fast # + # Suitable uses: + # * Holding decrypted data that is NOT secret + # * Verification keys that are public (use with care) + # # * 0 overhead # * Not locked in memory # * Not access protected diff --git a/src/crypto-secret/secret.cr b/src/crypto-secret/secret.cr index 8fe9bd4..594da2c 100644 --- a/src/crypto-secret/secret.cr +++ b/src/crypto-secret/secret.cr @@ -6,6 +6,13 @@ require "./class_methods" # **Only for direct use by cryptographic library authors** # # For all other applications use a preexisting class that includes `Crypto::Secret` +# +# # 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::Not - Won't get wiped but 0 overhead. Only use when you're sure the data isn't secret +# +# Other shards may provide additional `Secret` types (sodium.cr) @[Experimental] module Crypto::Secret class Error < Exception