chiark / gitweb /
spec is generated
[userv.git] / spec.sgml
index f7c2321..1ef3bc6 100644 (file)
--- a/spec.sgml
+++ b/spec.sgml
@@ -1,8 +1,9 @@
 <!doctype debiandoc system>
+
 <book>
 <title>User service daemon and client specification
-<author>Ian Jackson <email>ian@chiark.greenend.org.uk
-<version>draft 0.17
+<author>Ian Jackson <email>ian@davenant.greenend.org.uk
+<version>1.0.6</version>
 
 <abstract>
 This is a specification for a Unix system facility to allow one
@@ -10,7 +11,9 @@ program to invoke another when only limited trust exists
 between them.
 
 <copyright>
-Copyright 1996-1997 Ian Jackson.
+<prgn/userv/ is
+Copyright 1996-2003,2006 Ian Jackson;
+Copyright 2000 Ben Harris.
 <p>
 
 <prgn/userv/ is free software; you can redistribute it and/or modify
@@ -190,11 +193,10 @@ other words are allowed.  The <var/filename/ may also be <tt/stdin/,
 <p>
 
 If no <var/modifiers/ which imply <tt/read/ or <tt/write/ are used it
-is as if <tt/read/ had been specified, except that if the
-filedescriptor 1 or 2 of the service is being opened (either specified
-numerically or with <tt/stdout/ or <tt/stderr/) it is as if
-<tt/overwrite/ had been specified (or <tt/write/ if only <tt/fd/ was
-specified).
+is as if <tt/write/ had been specified, except that if the
+filedescriptor 0 of the service is being opened (either specified
+numerically or with <tt/stdin/) it is as if <tt/overwrite/ had been
+specified (or <tt/write/ if only <tt/fd/ was specified).
 <p>
 
 The client will also use <tt/O_NOCTTY/ when opening files specified by
@@ -371,7 +373,10 @@ contain one or more real newlines.
 Pretend to the service that it is being called by <var/user/ (which
 may be a username or a uid).  This will also affect the group and
 supplementary groups supplied to the service; they will be the
-standard group and supplementary groups for <var/user/.
+standard group and supplementary groups for <var/user/.  The
+<tt/--spoof-user/ option will <em/not/ affect which user is chosen if
+the service user is specified as just <tt/-/; in this case the service
+user will be the real calling user.
 
 </taglist>
 
@@ -704,7 +709,7 @@ in the context of and with the privileges of the service user.
 <tag/<tt/errors-to-syslog/ [<var/facility/ [<var/level/]]/
 <item>
 Error messages will be delivered using <prgn/syslog/.  The default
-<var/facility/ is <tt/daemon/; the default <var/level/ is <tt/error/.
+<var/facility/ is <tt/user/; the default <var/level/ is <tt/error/.
 </taglist>
 
 <sect1 id="dirs-control">Control structure directives
@@ -862,13 +867,13 @@ directive which modifies any particuar setting will take effect.
 Reject the request.  <prgn/execute/, <prgn/execute-from-directory/ and
 <prgn/execute-from-path/ will change this setting.
 
-<tag/<tt/execute <var/pathname/ [<var/argument/ ...]//
+<tag/<tt/execute <var/program/ [<var/argument/ ...]//
 <item>
-Execute the program <var/pathname/, with the arguments as specified,
+Execute the program <var/program/, with the arguments as specified,
 followed by any arguments given to the client if
 <prgn/no-suppress-args/ is in effect.  It is an error for the
 execution to fail when it is attempted (after all the configuration
-has been parsed).  If <var/pathname/ does not contain a slash it will
+has been parsed).  If <var/program/ does not contain a slash it will
 be searched for on the service user's path.
 
 <tag/<tt/execute-from-directory <var/pathname/ [<var/argument/ ...]//
@@ -947,6 +952,10 @@ files).
 Displays the top-level override configuration (the configuration data,
 evaluated by the server, which causes all the other configuration data
 to be parsed).
+
+<tag/<tt/help//
+<item>
+Displays a list of the understood builtin service names and arguments.
 </taglist>
 
 In the future other builtin services may be defined which do more than
@@ -1232,6 +1241,39 @@ and the service.
 <chapt id="notes">Applications and notes on use
 <p>
 
+<sect id="examples">Examples
+<p>
+
+The companion package, <prgn/userv-utils/, contains a selection of
+example services, some of which are useful tools in their own right.
+See the <prgn/README/ in its top-level directory for details.
+
+<sect id="standards">Standard services and directory management
+<p>
+
+In later versions of this specification standard service names and
+interfaces for common services such as mail delivery and WWW CGI
+scripts may be specified.
+<p>
+
+<prgn/userv/-using applications and system services which hide
+<prgn/userv/ behind wrapper scripts may need to store information in
+the user's filespace to preserve the correct placement of the security
+perimiters.  Such applications should usually do so in a directory
+(created by them) <tt>~/.userv/<var/service/</>, where <var/service/
+is the service name or application in question.
+<p>
+
+If desired, a dot-directory inside <tt>~/.userv</> may be used to
+avoid the user becoming confused by finding parts of a semi-privileged
+application's internal state in their filespace, and/or discourage
+them from fiddling with and thus corrupting it.
+<p>
+
+However, <prgn/userv/ applications should of course not rely for their
+global integrity and security on the integrity of the data on the
+user's side of the security boundary.
+
 <sect id="reducepriv">Reducing the number of absolutely privileged subsystems
 <p>
 
@@ -1241,13 +1283,13 @@ it.  This gives rise to a large and complex body of code which must be
 trusted with the security of the system.
 <p>
 
-Using <prgn/userv/ many of these subsystems no longer need any unusual
-privilege.
-<p>
+If they were to use <prgn/userv/, many of these subsystems would no
+longer need any unusual privilege.  <p>
 
 <prgn/cron/ and <prgn/at/, <prgn/lpr/ and the system's mail transfer
 agent (<prgn/sendmail/, <prgn/smail/, <prgn/exim/ or the like) all
-fall into this category.
+fall into this category, though <prgn/userv/-based versions of these
+programs are not currently available.
 
 <sect id="noexcess">Do not give away excessive privilege to <prgn/userv/-using facilities
 <p>
@@ -1313,29 +1355,59 @@ facilities which currently run as root.
 It is debatable whether the user-controlled state should be kept in
 the user's filespace (in dotfiles, say) or kept in a separate area set
 aside for the purpose; however, using the user's home directory (and
-probably creating a separate subdirectory of it as a dotfile to
-contain many subsystems' state) has fewer implications for the rest of
-the system and makes it entirely clear where the security boundaries
-lie.
+possibly creating a separate subdirectory of it as a dotfile to
+contain subsystem state) has fewer implications for the rest of the
+system and makes it entirely clear where the security boundaries lie.
 
-<sect id="notreally"><prgn/userv/ is not a replacement for <prgn/really/ and <prgn/sudo/
+<sect id="notreally"><prgn/userv/ can often replace <prgn/sudo/, but not <prgn/really/
 <p>
 
 <prgn/userv/ is not intended as a general-purpose system
 administration tool with which system administrators can execute
-privileged programs when they need to.  It is unsuitable for this
-purpose precisely because it enforces a strong separation between the
-calling and the called program, which is undesirable in this context.
+arbitrary programs like text editors as root (or other system users)
+when they need to.  It is unsuitable for this purpose precisely
+because it enforces a strong separation between the calling and the
+called program, which is undesirable in this context.
 <p>
 
-Its facilities for restricting activities to running certain programs
-may at first glance seem to provide similar functionality to
+However, its use when restricted to running particular programs in
+particular ways is very similar to many common uses of
 <prgn/sudo/<footnote><prgn/sudo/ is a program which allows users to
 execute certain programs as root, according to configuration files
-specified by the system administrator.</footnote>.  However, the
-separation mentioned above is a problem here too, particular for
-interaction - it can be hard for a <prgn/userv/ service program to
-interact with its real caller or the user in question.
+specified by the system administrator.</footnote>.  <prgn/userv/ is
+generally much better than restricted <prgn/sudo/, because it protects
+the called program much more strongly from bad environmental
+conditions set up by the caller.  Most programs that one might want to
+run via restricted <prgn/sudo/, have not been designed to run in a
+partially hostile environment.  <prgn/userv/ allows these programs to
+be run in a safer environment and should be used instead.
+
+<sect id="stdinerr">Error handling and input streams (eg stdin)
+<p>
+
+When the service program is reading from a file descriptor connected
+to the calling side, the fd that the service program refers to a pipe
+set up by <prgn/userv/ and not to the same object as was presented by
+the caller.
+<p>
+
+Therefore if there is some kind of error it is possible for the
+service-side fd to give premature end of file.  If it is important to
+tell whether all of the intended data has been received by the service
+program, the datastream must contain an explicit end-of-file
+indication of some kind.
+<p>
+
+For example, consider a <prgn/userv/ service for submitting a mail
+message, where message is supplied on the service's stdin.  However,
+if the calling process is interrupted before it has written all of the
+message, the service program will get EOF on the message data.  In a
+naive arrangement this would cause a half-complete message to be
+sent.  To prevent this, it is necessary to adopt some kind of explicit
+end indication; for example, the end of the message could be signalled
+by a dot on a line by itself, and dots doubled, as in SMTP.  Then the
+service program would know when the entire message had been received,
+and could avoid queueing incomplete messages.
 
 <sect id="nogeneral">Don't give access to general-purpose utilities
 <p>