X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=userv.git;a=blobdiff_plain;f=spec.sgml;h=e10c14eb26222e0d72d37fc9c849922716709f6b;hp=735aa34444d03f9f006dbcf810e066fd6d00b777;hb=6cab4f8fc3de7f4e4cd5ab5a1989017ea8e695fe;hpb=bf70bf4bd61f77133984b7bb84d2ada358333796 diff --git a/spec.sgml b/spec.sgml index 735aa34..e10c14e 100644 --- a/spec.sgml +++ b/spec.sgml @@ -3,7 +3,7 @@ User service daemon and client specification <author>Ian Jackson <email>ian@davenant.greenend.org.uk -<version>0.61.4</version> +<version>1.1.2~~iwj1</version> <abstract> This is a specification for a Unix system facility to allow one @@ -11,7 +11,9 @@ program to invoke another when only limited trust exists between them. <copyright> -<prgn/userv/ is Copyright 1996-1999 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 @@ -649,6 +651,13 @@ parameter value which is the empty string will be replaced with <tt/:empty/ (note that this is different from a parameter not having any values). +<p> +(In older versions of userv, a different translation was applied: +See <tt>https://bugs.debian.org/837391</tt>. The old translation +can be requested (for subsequent directives) with +<tt/include-lookup-quote-old/, which is undone by +<tt/include-lookup-quote-new/ and <tt/reset/.) + <tag/<tt/include-directory <var/directory/// <item> Read configuration from all files in directory <var/directory/ which @@ -824,7 +833,7 @@ strings; in this case any condition which tests it will be false, and </taglist> -<tag/<tt/errors-push/ <var/filename// +<tag/<tt/errors-push// <tag/<tt/srorre// <item> Stacks the error handling behaviour currently in effect. Any changes @@ -1239,29 +1248,38 @@ 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 will be specified. +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/.servdata/<var/service/</>, where -<var/service/ is the service name or application in question. +(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> -The use of a dot-directory inside <tt>~/.userv</> will hopefully 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. (Note that such -applications should of course not rely for their global integrity on -the integrity of the data on the user's side of the security -boundary.) +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> @@ -1272,13 +1290,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> @@ -1344,29 +1362,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>