ocsptool: doc update

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>

1 files changed, 41 insertions, 21 deletions

diff --git a/src/ocsptool-args.def b/src/ocsptool-args.def
index 8ef8ba859f..274096cb75 100644
--- a/src/ocsptool-args.def
+++ b/src/ocsptool-args.def
@@ -2,12 +2,24 @@ AutoGen Definitions options;
 prog-name     = ocsptool;
 prog-title    = "GnuTLS OCSP tool";
 prog-desc     = "Program to handle OCSP request/responses.";
-detail    = "Ocsptool is a program that can parse and print information about
-OCSP requests/responses, generate requests and verify responses.
-";
+detail    = "ocsptool is a program that can parse and print information about
+OCSP requests/responses, generate requests and verify responses.";
 short-usage   = "ocsptool [options]\nocsptool --help for usage instructions.\n";
 explain       = "";
 
+doc-section = {
+  ds-type = 'DESCRIPTION';
+  ds-format = 'texi';
+  ds-text   = <<-_EOT_
+@subheading On verification
+Responses are typically signed/issued by designated certificates or
+certificate authorities and thus this tool requires on verification
+the certificate of the issuer or the full certificate chain in order to
+determine the appropriate signing authority. The specified certificate
+of the issuer is assumed trusted.
+_EOT_;
+};
+
 #define  INFILE_OPT   1
 #define  OUTFILE_OPT  1
 #define  VERBOSE_OPT  1
@@ -19,40 +31,40 @@ flag = {
     arg-name  = "server name|url";
     arg-optional;
     descrip   = "Ask an OCSP/HTTP server on a certificate validity";
-    doc = "Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate.";
+    doc = "Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate.
+It can be combined with --load-chain, where it checks
+all certificates in the provided chain, or with --load-cert and
+--load-issuer options. The latter checks the provided certificate
+against its specified issuer certificate.";
 };
 
 flag = {
     name      = verify-response;
     value     = e;
     descrip   = "Verify response";
-    doc = "";
-};
-
-flag = {
-    name      = verify-allow-broken;
-    descrip   = "Allow broken algorithms, such as MD5 for verification";
-    doc = "This can be combined with --verify-response.";
+    doc = "Verifies the provided OCSP response against the system trust
+anchors (unless --load-trust is provided). It requires the --load-signer
+or --load-chain options to obtain the signer of the OCSP response.";
 };
 
 flag = {
     name      = request-info;
     value     = i;
     descrip   = "Print information on a OCSP request";
-    doc = "";
+    doc = "Display detailed information on the provided OCSP request.";
 };
 
 flag = {
     name      = response-info;
     value     = j;
     descrip   = "Print information on a OCSP response";
-    doc = "";
+    doc = "Display detailed information on the provided OCSP response.";
 };
 
 flag = {
     name      = generate-request;
     value     = q;
-    descrip   = "Generate an OCSP request";
+    descrip   = "Generates an OCSP request";
     doc = "";
 };
 
@@ -68,7 +80,7 @@ flag = {
     name      = load-chain;
     arg-type  = file;
     file-exists = yes;
-    descrip   = "Read certificate and issuer chain from file";
+    descrip   = "Reads a set of certificates forming a chain from file";
     doc = "";
 };
 
@@ -76,7 +88,7 @@ flag = {
     name      = load-issuer;
     arg-type  = file;
     file-exists = yes;
-    descrip   = "Read issuer certificate from file";
+    descrip   = "Reads issuer's certificate from file";
     doc = "";
 };
 
@@ -84,7 +96,7 @@ flag = {
     name      = load-cert;
     arg-type  = file;
     file-exists = yes;
-    descrip   = "Read certificate to check from file";
+    descrip   = "Reads the certificate to check from file";
     doc = "";
 };
 
@@ -94,14 +106,16 @@ flag = {
     file-exists = yes;
     descrip   = "Read OCSP trust anchors from file";
     flags-cant = load-signer;
-    doc = "";
+    doc = "When verifying an OCSP response read the trust anchors from the
+provided file. When this is not provided, the system's trust anchors will be
+used.";
 };
 
 flag = {
     name      = load-signer;
     arg-type  = file;
     file-exists = yes;
-    descrip   = "Read OCSP response signer from file";
+    descrip   = "Reads the OCSP response signer from file";
     flags-cant = load-trust;
     doc = "";
 };
@@ -119,7 +133,7 @@ flag = {
     value     = Q;
     arg-type  = file;
     file-exists = yes;
-    descrip   = "Read DER encoded OCSP request from file";
+    descrip   = "Reads the DER encoded OCSP request from file";
     doc      = "";
 };
 
@@ -128,7 +142,7 @@ flag = {
     value     = S;
     arg-type  = file;
     file-exists = yes;
-    descrip   = "Read DER encoded OCSP response from file";
+    descrip   = "Reads the DER encoded OCSP response from file";
     doc      = "";
 };
 
@@ -138,6 +152,12 @@ flag = {
     doc = "";
 };
 
+flag = {
+    name      = verify-allow-broken;
+    descrip   = "Allow broken algorithms, such as MD5 for verification";
+    doc = "This can be combined with --verify-response.";
+};
+
 doc-section = {
   ds-type = 'SEE ALSO';
   ds-format = 'texi';