Pull from trunk.

svn path=/branches/tk705/; revision=6017

1 files changed, 112 insertions, 31 deletions

diff --git a/doc/doc.RPKI.Utils b/doc/doc.RPKI.Utils
index e6f89794..ce36dcbd 100644
--- a/doc/doc.RPKI.Utils
+++ b/doc/doc.RPKI.Utils
@@ -1,28 +1,36 @@
 ****** RPKI utility programs ******
 
 The distribution contains a few small utility programs. Most of these are
-nominally relying party tools. Some but not all of them are installed by "make
-install".
+nominally relying party tools, but work at a low enough level that they may
+also be useful in diagnosing CA problems.
+
+Unless otherwise specified, all of these tools expect RPKI objects
+(certificates, CRLs, CMS signed objects) to be in DER format.
+
+Several of these tools accept an rcynic_directory argument. Which directory to
+specify here depends on what you're trying to do, but if you're just trying to
+look at authenticated data in your RP cache, and assuming you've installed
+everything in the default locations, the directory you want is probably /var/
+rcynic/data/authenticated.
 
 ***** uri *****
 
 uri is a utility program to extract URIs from the SIA, AIA, and CRLDP
-extensions of one or more X.509v3 certificates.
+extensions of one or more X.509v3 certificates, either specified directly or as
+CMS objects containing X.509v3 certificates within the CMS wrapper.
 
 Usage:
 
-  $ uri [-p | -d] cert [cert...]
-
--d Input is in DER format
-
--p Input is in PEM format
+  $ uri [-h | --help] [-s | --single-line] cert [cert...]
 
--s Single output line per input file
+  -h --help
+      Show help
 
--v Verbose mode
+  -s --single-line
+      Single output line per input file
 
-The rp/utils directory in the source tree also includes a few experimental AWK
-scripts to post-process the uri program's output in various ways.
+  cert
+      Object(s) to examine
 
 ***** hashdir *****
 
@@ -34,31 +42,62 @@ repository system.
 
 Usage:
 
-  $ hashdir input-directory output-directory
+  $ hashdir [-h | --help] [-v | --verbose] rcynic_directory output_directory
+
+  -h --help
+      Show help
+
+  -v --verbose
+      Whistle while you work
+
+  rcynic_directory
+      rcynic authenticated output tree
+
+  output_directory
+      Output directory to create
 
 ***** print_rpki_manifest *****
 
-print_rpki_manifest prettyprints the content of a manifest. It does NOT attempt
-to verify the signature. Usage:
+print_rpki_manifest pretty-prints the content of a manifest. It does NOT
+attempt to verify the signature.
 
-  $ print_rpki_manifest [-c] manifest [manifest...]
+Usage:
+
+  $ print_rpki_manifest [-h | --help] [-c | --cms] manifest [manifest...]
+
+  -h --help
+      Show help
+
+  -c --cms
+      Print text representation of entire CMS blob
 
--c Print text representation of entire CMS blob
+  manifest
+      Manifest(s) to print
 
 ***** print_roa *****
 
-print_roa prettyprints the content of a ROA. It does NOT attempt to verify the
+print_roa pretty-prints the content of a ROA. It does NOT attempt to verify the
 signature.
 
 Usage:
 
-  $ print_roa [-b] [-c] [-s] ROA [ROA...]
+  $ print_roa [-h | --help] [-b | --brief] [-c | --cms] [-s | --signing-time]
+  ROA [ROA...]
 
--b Brief mode (only show ASN and prefix)
+  -h --help
+      Show help
 
--c Print text representation of entire CMS blob
+  -b --brief
+      Brief mode (only show ASN and prefix)
 
--s Show CMS signingTime
+  -c --cms
+      Print text representation of entire CMS blob
+
+  -s --signing-time
+      Show CMS signingTime
+
+  ROA
+      ROA object(s) to print
 
 ***** find_roa *****
 
@@ -67,17 +106,34 @@ matching specified prefixes.
 
 Usage:
 
-  $ find_roa authtree prefix [prefix...]
+  $ find_roa [-h | --help] [-a | --all]
+             [-m | --match-maxlength ] [-f | --show-filenames]
+             [-i | --show-inception]   [-e | --show-expiration]
+             authtree [prefix...]
 
-The find_roa directory also includes a script {{{test_roa.sh}, which uses
-hashdir, print_roa, find_roa, and the OpenSSL command line tool. find_roa
-builds a hashed directory, searches for ROAs matching specified prefixes,
-verifies the CMS signature and certificate path of each ROA found, and
-prettyprints each ROA that passes the checks.
+  -h --help
+      Show help
 
-Usage:
+  -a --all
+      Show all ROAs, do no prefix matching at all
+
+  -e --show-expiration
+      Show ROA chain expiration dates
 
-  $ test_roa.sh authtree prefix [prefix...]
+  -f --show-filenames
+      Show filenames instead of URIs
+
+  -i --show-inception
+      Show inception dates
+
+  -m -match-maxlength
+      Pay attention to maxLength values
+
+  authtree
+      rcynic authenticated output tree
+
+  prefix
+      ROA prefix(es) to on which to match
 
 ***** scan_roas *****
 
@@ -90,4 +146,29 @@ validated ROA payload after an rcynic validation run.
 
 Usage:
 
-  $ scan_roas authtree
+  $ scan_roas [-h | --help] rcynic_directory [rcynic_directory...]
+
+  -h --help
+      Show help
+
+  rcynic_directory
+      rcynic authenticated output tree
+
+***** scan_routercerts *****
+
+scan_routercerts searchs the authenticated result tree from an rcynic run for
+BGPSEC router certificates, and prints out data of interest to the rpki-rtr
+code.
+
+Other programs such as the rpki-rtr client use scan_routercerts to extract the
+validated ROA payload after an rcynic validation run.
+
+Usage:
+
+  $ scan_routercerts [-h | --help] rcynic_directory [rcynic_directory...]
+
+  -h --help
+      Show help
+
+  rcynic_directory
+      rcynic authenticated output tree