X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=userv.git;a=blobdiff_plain;f=spec.sgml;h=75975a7fc8b9bf5891c7128188978bc564fb09b0;hp=f7c2321e3bb65223a6596c969151f5164dfcbed3;hb=5c38f6a9b5774073832e2b483b0c01b4f3261cb5;hpb=5043c988440a119e4f773c967be19a829582b8ba diff --git a/spec.sgml b/spec.sgml index f7c2321..75975a7 100644 --- a/spec.sgml +++ b/spec.sgml @@ -1,8 +1,9 @@ + 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.1.2~~iwj1</version> <abstract> This is a specification for a Unix system facility to allow one @@ -10,7 +11,10 @@ program to invoke another when only limited trust exists between them. <copyright> -Copyright 1996-1997 Ian Jackson. +<prgn/userv/ is +Copyright 1996-2017 Ian Jackson; +Copyright 2000 Ben Harris; +Copyright 2016-2017 Peter Benie. <p> <prgn/userv/ is free software; you can redistribute it and/or modify @@ -190,11 +194,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 +374,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> @@ -646,6 +652,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 @@ -704,7 +717,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 @@ -821,7 +834,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 @@ -862,13 +875,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 +960,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 +1249,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 +1291,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 +1363,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>