summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--keymanager/changes/next-changelog.txt1
-rw-r--r--keymanager/docs/soledad-documents.rst77
2 files changed, 78 insertions, 0 deletions
diff --git a/keymanager/changes/next-changelog.txt b/keymanager/changes/next-changelog.txt
index be6da72..163c1ee 100644
--- a/keymanager/changes/next-changelog.txt
+++ b/keymanager/changes/next-changelog.txt
@@ -13,6 +13,7 @@ Features
- `#7485 <https://leap.se/code/issues/7485>`_: Move validation, usage and audited date to the active document.
- `#7713 <https://leap.se/code/issues/7713>`_: Update soledad documents by adding versioning field.
- `#7500 <https://leap.se/code/issues/7500>`_: Use fingerprints instead of key ids.
+- `#7712 <https://leap.se/code/issues/7712>`_: Document the soledad docs fields.
- Make EncryptionKey aware of the active address.
- `#1234 <https://leap.se/code/issues/1234>`_: Description of the new feature corresponding with issue #1234.
diff --git a/keymanager/docs/soledad-documents.rst b/keymanager/docs/soledad-documents.rst
new file mode 100644
index 0000000..67055b2
--- /dev/null
+++ b/keymanager/docs/soledad-documents.rst
@@ -0,0 +1,77 @@
+=================
+Soledad Documents
+=================
+
+KeyManager uses two types of documents for the keyring:
+
+* key document, that stores each gpg key.
+
+* active document, that relates an address to its corresponding key.
+
+
+Each key can have 0 or more active documents with a different email address
+each:
+
+::
+
+ .-------------. .-------------.
+ | foo@foo.com | | bar@bar.com |
+ '-------------' '-------------'
+ | |
+ | .-----------. |
+ | | | |
+ | | key | |
+ '----->| |<----'
+ | |
+ '-----------'
+
+
+Fields in a key document:
+
+* uids
+
+* fingerprint
+
+* key_data
+
+* private. bool marking if the key is private or public
+
+* length
+
+* expiry_date
+
+* refreshed_at
+
+* version = 1
+
+* type = "OpenPGPKey"
+
+* tags = ["keymanager-key"]
+
+
+Fields in an active document:
+
+* address
+
+* fingerprint
+
+* private
+
+* validation
+
+* last_audited_at
+
+* encr_used
+
+* sign_used
+
+* version = 1
+
+* type = "OpenPGPKey-active"
+
+* tags = ["keymanager-active"]
+
+
+The meaning of validation, encr_used and sign_used is related to the `Transitional Key Validation`_
+
+.. _Transitional Key Validation: https://leap.se/en/docs/design/transitional-key-validation