tDocument new secret format - safe - password protected secret keeper
(HTM) git clone git://git.z3bra.org/safe.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 27a7417e7ddf4db577995be2d4595dad9f418c5a
(DIR) parent a25d4e0e8990e3c9baeb922bcd5d2acb73055a7e
(HTM) Author: Willy Goiffon <contact@z3bra.org>
Date: Wed, 19 Oct 2022 10:17:41 +0200
Document new secret format
Diffstat:
M README | 6 ++++--
M safe-store.5 | 46 +++++++++++++++++++------------
2 files changed, 32 insertions(+), 20 deletions(-)
---
(DIR) diff --git a/README b/README
t@@ -13,6 +13,7 @@ Features
- Handle secrets of any size (stream encryption)
- Agent-like capabilities
- Support external askpass programs
+- Encrypt secrets in [cream][0] format
Usage
-----
t@@ -36,6 +37,7 @@ Edit config.mk as needed, then build/install with the following commands:
make
make install
-Require [libsodium][0].
+Require [libsodium][1].
-[0]: https://libsodium.org
+[0]: https://z3bra.org/cream
+[1]: https://libsodium.org
(DIR) diff --git a/safe-store.5 b/safe-store.5
t@@ -1,9 +1,11 @@
.Dd 2020-05-28
.Dt SAFE-STORE 5
.Os POSIX.1-2017
+
.Sh NAME
.Nm safe-store
.Nd Encrypted file storage for your secrets.
+
.Sh DESCRIPTION
The
.Nm
t@@ -16,10 +18,11 @@ in which case the secret shall be refered to by its path relative to the
.Bd -literal
$ find .secrets -type f
.secrets/master
- .secrets/randomname
+ .secrets/name
.secrets/subdir/name
.secrets/subdir/othername
.Ed
+
.Sh FILES
.Bl -tag -width "/etc/mail/smtpd.confXXX" -compact
.It Pa .secrets
t@@ -27,31 +30,35 @@ Default
.Nm
path
.It Pa .secrets/cipher
-A random secret named "cipher"
+A arbitrary secret named "cipher"
.It Pa .secrets/master
-A special secret used as a reference for salting and verifying the master password
+A special secret used as a reference for derivating a key from the
+master password
.El
+.Pp
.Pa secrets
-are the concatenation of a 16 bytes
-.Em salt
-and arbitraty data encrypted
-using the
-.Em XChaCha20
-stream cipher.
+are the concatenation of a 40 bytes
+.Xr cream 5
+header and arbitrary data encrypted using the
+.Em XChaCha20-Poly1305
+algorithm.
.Pp
-The key used for encryption is derived from a salt and a master
-password. Every secret is be encrypted using the same key.
+The key used for encryption is derived from the parameters in the header
+and a master password. Every secret is encrypted with the same key.
.Pp
.Pa master
is a special secret containing the master password.
-It is used to check the master password, and as a reference salt
-for new secrets. Its content is however never checked for, and could
-be anything, as long as it can be decrypted properly.
+It is used to check the master password, and as a reference for key
+derivation.
+Its content is however never checked for, and could be
+anything, as long as it can be decrypted properly.
+
.Sh SECURITY CONSIDERATIONS
-The master secret is used to check that your salt and master password
-are correct. If it is not absent, no secret can be decrypted, and the
+The master secret is used to verify that the key derivated from your
+master password is correct. If it is not absent, no secret can be
+decrypted, and the
.Xr safe 1
-utility will generate a new salt and master entry. It means that all
+utility will generate a new header and master entry. It means that all
secrets created with a different salt will not be decrypted properly.
.Pp
To recover from a lost master secret, you can do the following (assuming that
t@@ -65,8 +72,11 @@ is an existing secret):
chmod 400 master
safe master
.Ed
+
.Sh SEE ALSO
.Xr safe 1 ,
-.Xr safe-agent 1
+.Xr safe-agent 1 ,
+.Xr cream 5
+
.Sh AUTHORS
.An Willy Goiffon Aq Mt dev@z3bra.org