From 2f27cb12e30c9f6e780354eecc3ff0039ed52c63 Mon Sep 17 00:00:00 2001
From: "Neal H. Walfield" <neal@g10code.com>
Date: Tue, 29 Nov 2016 14:33:29 +0100
Subject: g10: Extend TOFU_STATS to always show the validity

* doc/DETAILS (TOFU_STATS): Rename the VALIDITY field to SUMMARY.  Add
a new field called VALIDITY.
* g10/tofu.c (write_stats_status): Update output accordingly.

--
Signed-off-by: Neal H. Walfield <neal@g10code.com>

Change TOFU_STATS as discussed offline with Werner, Justus and Andre.
---
 doc/DETAILS | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/DETAILS b/doc/DETAILS
index a264e53ee..534c48c0b 100644
--- a/doc/DETAILS
+++ b/doc/DETAILS
@@ -722,14 +722,14 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     userid encoded in UTF-8 and percent escaped.  The fingerprint is
     identical for all TOFU_USER lines up to a NEWSIG line.
 
-*** TOFU_STATS <validity> <sign-count> 0 [<policy> [<tm1> <tm2> <tm3> <tm4>]]
+*** TOFU_STATS <summary> <sign-count> <encryption-count> [<policy> [<tm1> <tm2> <tm3> <tm4> [<validity>]]]
 
     Statistics for the current user id.
 
-    Values for VALIDITY are:
-    - 0 :: conflict
-    - 1 :: key without history
-    - 2 :: key with too little history
+    Values for SUMMARY are:
+    - 0 :: attention, an interaction with the user is required (conflict)
+    - 1 :: key with no verification/encryption history
+    - 2 :: key with little history
     - 3 :: key with enough history for basic trust
     - 4 :: key with a lot of history
 
@@ -739,7 +739,8 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - good    :: Policy is "good"
     - bad     :: Policy is "bad"
     - ask     :: Policy is "ask"
-    - unknown :: Policy is not known.
+    - unknown :: Policy is "unknown" (TOFU information does not
+                 contribute to the key's validity)
 
     TM1 ist the time the first message was verified.  TM2 is the time
     the most recent message was verified.  TM3 is the time the first
@@ -747,6 +748,11 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     either be seconds since Epoch or an ISO time string
     (yyyymmddThhmmss).
 
+    VALIDITY is the same as SUMMARY with the exception that VALIDITY
+    doesn't reflect whether the key needs attention.  That is it never
+    takes on value 0.  Instead, if there is a conflict, VALIDITY still
+    reflects the key's validity (values: 1-4).
+
 *** TOFU_STATS_SHORT <long_string>
 
     Information about the TOFU binding for the signature.
-- 
cgit v1.2.3