msva-perl

   1 #!/usr/bin/perl -wT
   2
   3 # Monkeysphere Validation Agent, Perl version
   4 # Copyright © 2010 Daniel Kahn Gillmor <dkg@fifthhorseman.net>
   5 #
   6 # This program is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 3 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 use warnings;
  20 use strict;
  21
  22 use Crypt::Monkeysphere::MSVA;
  23
  24 my $server = Crypt::Monkeysphere::MSVA->new();
  25 $server->run(host=>'localhost',
  26              log_level=> Crypt::Monkeysphere::MSVA::get_log_level(),
  27              user => POSIX::geteuid(),  # explicitly choose regular user and group (avoids spew)
  28              group => POSIX::getegid(),
  29              msva=>$server);
  30 __END__
  31
  32 =head1 NAME
  33
  34 msva-perl - Perl implementation of a Monkeysphere Validation Agent
  35
  36 =head1 SYNOPSIS
  37
  38   msva-perl [ COMMAND [ ARGS ... ] ]
  39
  40 =head1 ABSTRACT
  41
  42 msva-perl provides a Perl implementation of the Monkeysphere
  43 Validation Agent, a certificate validation service.
  44
  45 =head1 INTRODUCTION
  46
  47 The Monkeysphere Validation Agent offers a local service for tools to
  48 validate certificates (both X.509 and OpenPGP) and other public keys.
  49
  50 Clients of the validation agent query it with a public key carrier (a
  51 raw public key, or some flavor of certificate), the supposed name of
  52 the remote peer offering the pubkey, and the context in which the
  53 validation check is relevant (e.g. ssh, https, etc).
  54
  55 The validation agent then tells the client whether it was able to
  56 successfully validate the peer's use of the public key in the given
  57 context.
  58
  59 msva-perl relies on monkeysphere(1), which uses the user's OpenPGP web
  60 of trust to validate the peer's use of public keys.
  61
  62 =head1 USAGE
  63
  64 Launched with no arguments, msva-perl simply runs and listens forever.
  65
  66 Launched with arguments, it sets up a listener, spawns a subprocess
  67 using the supplied command and arguments, but with the
  68 MONKEYSPHERE_VALIDATION_AGENT_SOCKET environment variable set to refer
  69 to its listener.  When the subprocess terminates, msva-perl tears down
  70 the listener and exits as well, returning the same value as the
  71 subprocess.
  72
  73 This is a similar invocation pattern to that of ssh-agent(1).
  74
  75 =head1 ENVIRONMENT VARIABLES
  76
  77 msva-perl is configured by means of environment variables.
  78
  79 =over 4
  80
  81 =item MSVA_LOG_LEVEL
  82
  83 msva-perl logs messages about its operation to stderr.  MSVA_LOG_LEVEL
  84 controls its verbosity, and should be one of (in increasing
  85 verbosity): silent, quiet, fatal, error, info, verbose, debug, debug1,
  86 debug2, debug3.  Default is 'error'.
  87
  88 =item MSVA_ALLOWED_USERS
  89
  90 If your system is capable of it, msva-perl tries to figure out the
  91 owner of the connecting client.  If MSVA_ALLOWED_USERS is unset,
  92 msva-perl will only permit connections from the user msva is running
  93 as.  If you set MSVA_ALLOWED_USERS, msva-perl will treat it as a list
  94 of local users (by name or user ID) who are allowed to connect.
  95
  96 =item MSVA_PORT
  97
  98 msva-perl listens on a local TCP socket to facilitate access.  You can
  99 choose what port to bind to by setting MSVA_PORT.  Default is to bind
 100 on an arbitrary open port.
 101
 102 =item MSVA_KEYSERVER
 103
 104 msva-perl will request information from OpenPGP keyservers.  Set
 105 MSVA_KEYSERVER to declare the keyserver you want it to check with.
 106 Default is 'hkp://pool.sks-keyservers.net'.
 107
 108 =item MSVA_KEYSERVER_POLICY
 109
 110 msva-perl must decide when to check with keyservers (for new keys,
 111 revocation certificates, new certifications, etc).  There are three
 112 possible options: 'always' means to check with the keyserver on every
 113 query it receives.  'never' means to never check with a
 114 keyserver. 'unlessvalid' will only check with the keyserver on a
 115 specific query if no keys are already locally known to be valid for
 116 the requested peer.  Default is 'unlessvalid'.
 117
 118 =back
 119
 120 =head1 COMMUNICATION PROTOCOL DETAILS
 121
 122 Communications with the Monkeysphere Validation Agent are in the form
 123 of JSON requests over plain HTTP.  Responses from the agent are also
 124 JSON objects.  For details on the structure of the requests and
 125 responses, please see
 126 http://web.monkeysphere.info/validation-agent/protocol
 127
 128 =head1 SECURITY CONSIDERATIONS
 129
 130 msva-perl deliberately binds to the loopback adapter (via named lookup
 131 of "localhost") so that remote users do not get access to the daemon.
 132 On systems (like Linux) which report ownership of TCP sockets in
 133 /proc/net/tcp, msva-perl will refuse access from random users (see
 134 MSVA_ALLOWED_USERS above).
 135
 136 =head1 SEE ALSO
 137
 138 monkeysphere(1), monkeysphere(7), ssh-agent(1)
 139
 140 =head1 BUGS AND FEEDBACK
 141
 142 Bugs or feature requests for msva-perl should be filed with the
 143 Monkeysphere project's bug tracker at
 144 https://labs.riseup.net/code/projects/monkeysphere/issues/
 145
 146 =head1 AUTHORS AND CONTRIBUTORS
 147
 148 Daniel Kahn Gillmor E<lt>dkg@fifthhorseman.net<gt>
 149
 150 The Monkeysphere Team http://web.monkeysphere.info/
 151
 152 =head1 COPYRIGHT AND LICENSE
 153
 154 Copyright © Daniel Kahn Gillmor and others from the Monkeysphere team.
 155 msva-perl is free software, distributed under the GNU Public License,
 156 version 3 or later.
 157