From 334c3711789f67e259a7127b00e0a20ffa96bff1 Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Sun, 17 Oct 2010 20:39:16 -0400 Subject: [PATCH] simplify/shorten msva-query-agent documentation --- msva-query-agent | 68 +++++++++++++++++------------------------------- 1 file changed, 24 insertions(+), 44 deletions(-) diff --git a/msva-query-agent b/msva-query-agent index 79b76f7..ea1f7f2 100755 --- a/msva-query-agent +++ b/msva-query-agent @@ -45,61 +45,51 @@ msva-query-agent - query a Monkeysphere Validation Agent =head1 SYNOPSIS -msva-query-agent CONTEXT PEER PKC_TYPE < PKC_DATA +msva-query-agent CONTEXT PEER PKC_TYPE < /path/to/public_key_carrier =head1 ABSTRACT -msva-query-agent provides a means of querying a Monkeysphere -Validation Agent for certificate validation. - -=head1 INTRODUCTION - -The Monkeysphere Validation Agent offers a local service for tools to -validate certificates (both X.509 and OpenPGP) and other public keys. - -Clients of the validation agent query it with a public key carrier (a -raw public key, or some flavor of certificate), the supposed name of -the remote peer offering the pubkey, and the context in which the -validation check is relevant (e.g. ssh, https, etc). - -The validation agent tells the client whether it was able to -successfully validate the peer's use of the public key in the given -context. +msva-query-agent validates certificates for a given use by querying a +running Monkeysphere Validation Agent. =head1 USAGE -msva-query-agent create an agent post data (APD) object which is sent -to the msva. The return code of the client indicates the validity of -the certificate. If the certificate is valid, the return code is 0. -Otherwise, the return code if 1. +msva-query-agent reads a certificate from standard input, and posts it +to the running Monkeysphere Validation Agent. The return code +indicates the validity (as determined by the agent) of the certificate +for the specified purpose. The agent's return message (if any) is +emitted on stderr. -The APD is created from certificate data provided on stdin (PKC_DATA), -and the following information provided on the command line: +Three command-line arguments are all required, supplied in order, as +follows: =over 4 =item CONTEXT -Context of query, e.g. 'https', 'ssh', etc. +Context in which the certificate is being validated (e.g. 'https', +'ssh', 'ike') =item PEER -Service address portion of url, e.g. 'foo.example.net'. +The name of the intended peer. When validating a certificate for a +service, supply the host's full DNS name (e.g. 'foo.example.net') =item PKC_TYPE -Type of public key carrier data provided on stdin, e.g. 'x509der', -etc. +The format of public key carrier data provided on standard input +(e.g. 'x509der') -=item PKC_DATA +=back -Public key carrier data provided on stdin. +=head1 RETURN CODE -=back +If the certificate is valid for the requested peer in the given +context, the return code is 0. Otherwise, the return code is 1. =head1 ENVIRONMENT VARIABLES -msva-query-agent accepts some environment variables: +msva-query-agent's behavior is controlled by environment variables: =over 4 @@ -115,16 +105,6 @@ its verbosity, and should be one of (in increasing verbosity): silent, quiet, fatal, error, info, verbose, debug, debug1, debug2, debug3. Default is 'error'. -=item MSVA_KEYSERVER_POLICY - -msva-perl must decide when to check with keyservers (for new keys, -revocation certificates, new certifications, etc). There are three -possible options: 'always' means to check with the keyserver on every -query it receives. 'never' means to never check with a -keyserver. 'unlessvalid' will only check with the keyserver on a -specific query if no keys are already locally known to be valid for -the requested peer. Default is 'unlessvalid'. - =back =head1 COMMUNICATION PROTOCOL DETAILS @@ -141,8 +121,8 @@ msva-perl(1), monkeysphere(1), monkeysphere(7) =head1 BUGS AND FEEDBACK -Bugs or feature requests for msva-perl should be filed with the -Monkeysphere project's bug tracker at +Bugs or feature requests for msva-perl and associated tools should be +filed with the Monkeysphere project's bug tracker at https://labs.riseup.net/code/projects/monkeysphere/issues/ =head1 AUTHORS AND CONTRIBUTORS @@ -154,6 +134,6 @@ The Monkeysphere Team http://web.monkeysphere.info/ =head1 COPYRIGHT AND LICENSE -Copyright © Jameson Graef Rollins and others from the Monkeysphere +Copyright © 2010, Jameson Graef Rollins and others from the Monkeysphere team. msva-query-agent is free software, distributed under the GNU Public License, version 3 or later. -- 2.26.2