\input texinfo @c -*-texinfo-*-
@c
-@c $Id: become.texi,v 1.2 1998/01/12 16:41:31 mdw Exp $
+@c $Id: become.texi,v 1.9 2004/04/17 10:54:21 mdw Exp $
@c
@c Documentation for `become'
@c
@c (c) 1998 EBI
@c
-@c ----- Revision history ---------------------------------------------------
-@c
-@c $Log: become.texi,v $
-@c Revision 1.2 1998/01/12 16:41:31 mdw
-@c Tidying for new release versions. Fix copyright date.
-@c
-@c Revision 1.1 1997/09/18 11:16:34 mdw
-@c Brand new Texinfo manual, with wider scope than the original LaTeX one.
-@c
-
@c ----- Standard boilerplate -----------------------------------------------
@c %**start of header
-@setfilename become
+@setfilename become.info
@settitle Become
@setchapternewpage odd
@footnotestyle end
@paragraphindent 0
@iftex
-@c @smallbook
+@input texinice.tex
@afourpaper
@c @parindent=0pt
@end iftex
@c %**end of header
+@dircategory Administration tools
+@direntry
+* Become: (become). Shared account administration tool
+@end direntry
+
@c ----- Useful macros ------------------------------------------------------
-@set version 1.2
+@set version 1.4
@c ----- Copyright matters --------------------------------------------------
@title The Become program
@subtitle Become version @value{version}
-@author Mark Wooding (@email{mdw@@ebi.ac.uk})
+@author Mark Wooding @email{mdw@@ebi.ac.uk}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1997 European Bioinformatics Institute.
+Copyright @copyright{} 1998 European Bioinformatics Institute.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
* Administering Become:: How to maintain Become
* Invoking Become:: Reference to Become's command line options
+@detailmenu
--- The Detailed Node Listing ---
Becoming someone else
Considerations for X authority
-* The user-group method:: A secure method for handling X authority
+* The user-group method:: A fairly secure way of handling X authority
* Using xauth:: A less secure method, which might be easier
Become administration
The configuration file
+* Requests and rules:: How the configuration file works
* Basic syntax:: Quick overview of Become's syntax
* Classes:: Defining classes of things
* Predefined classes:: Become predefines some (maybe) useful classes
* Allow statements:: Allow users to become other users
* Other statements:: Some other useful statements
* Example configuration file:: An example, showing a few features.
+* Checking and querying:: Checking and querying configuration files
* Complete grammar:: Complete grammar for Become config files
+Checking and querying the configuration file
+
+* Verifying config files:: Checking a configuration file is correct
+* Querying config files:: Asking questions about privileges
+* Output formats:: Different ways of formatting output
+* Restricting output:: Being selective about what gets output
+* bcquery reference:: Complete command line reference
+
Networked configuration
* Choosing servers:: Which servers Become tries to talk to
* Setting up keys:: How to generate keys for Become
-* Random number files:: Become keeps random number state around
* Issuing a new key:: How to issue new keys without disruption
-Setting up keys
-
-* Invoking keygen:: How to use the @code{keygen} program
-
Invoking Become
* Becoming another user:: Options for becoming another user
* Starting Become daemons:: Options for starting Become daemons
* Debugging options:: Options to use when Become goes wrong
+
+@end detailmenu
@end menu
@c --------------------------------------------------------------------------
@node Copying, Introduction, Top, Top
@unnumbered The GNU General Public License
-
@include gpl.texi
group of legitimate users.
The Become program presented here offers a solution to the problems of
-shared accounts. It allows the system adminstrator to define which
+shared accounts. It allows the system administrator to define which
users are allowed access to which accounts, on which hosts, and to
execute which commands. Such shared accounts can then, in general, have
their passwords removed.
Login styles are selected by giving command line arguments:
@table @code
-@item -p
+@item -e
@itemx --preserve
The original style: try to preserve the existing user's environment as much
as possible.
@subsubsection The `login' login style
The `login' style causes Become to attempt to emulate a full login. Become
-will empty the environment of any variables which aren't explicitly preserved
-(@pxref{Tweaking the environment}). It will then set the following
-variables:
+will empty the environment of almost variables which aren't explicitly
+preserved (@pxref{Tweaking the environment}). However, the following
+variables are retained:
+
+@itemize @bullet
+@item
+TERM
+@item
+DISPLAY
+@item
+TZ
+@end itemize
+
+@noindent
+It will set the following variables:
@table @code
@item USER
copy of your display's magic cookie, or you can retain permission to read the
cookie file.
+Be aware that allowing a shared account to connect to your X display is a
+security risk.
+
@menu
-* The user-group method:: A secure method for handling X authority
+* The user-group method:: A fairly secure way of handling X authority
* Using xauth:: A less secure method, which might be easier
@end menu
@node The user-group method, Using xauth, X authority, X authority
@subsection The user-group method for handling X authority
-This method is completely secure only if your site uses the `user-group'
-system. In this system, each user is allocated a group containing only that
-user. Usually this is made the user's default primary group, although that's
-not necessary here.
+This method is secure only if your site uses the `user-group' system. In
+this system, each user is allocated a group containing only that user.
+Usually this is made the user's default primary group, although that's not
+necessary here.
When you start a new X session, ensure that your cookie file is owned by you
and your private group. Change the file's permissions so that it's group
become someone else (@pxref{Group permissions}), and that the
@code{XAUTHORITY} variable is set correctly.
+Note that Unix's security mechanisms aren't designed to prevent processes
+owned by the same user from interfering with each other. This method does
+not provide complete security.
+
The following Bourne shell code in a @file{.xinitrc} should do most of the
work:
in @file{.cshrc} for C shell users.
-
@node Using xauth, , The user-group method, X authority
-@subsection The `xauth' method for handling X authority
+@subsection The @code{xauth} method for handling X authority
This method sends your X cookie to the shared account. It's therefore
intrinsically dangerous: you must be able to trust the other users of the
A list of servers to contact. Only needed on client machines.
@item become.key
-The encryption key to use when sending requests to servers. Needed on
-clients and servers, but not on standalone machines.
+The signing key to use when sending requests to servers. Needed on servers,
+but not on standalone machines.
+
+@item become.pubkey
+The verification keys to use when checking server responses. Needed on
+clients, but not on standalone machines.
@item become.pid
The process id of the server. Created automatically by Become's server when
in starts up.
-
-@item become.random
-Contains state information for Become's random number generator. Created
-automatically if it doesn't exist.
@end table
should grant or deny permission.
Standalone installations don't depend on servers being available, or even on
-the existance of a network. They're useful for small sites, or sites with a
+the existence of a network. They're useful for small sites, or sites with a
small number of users. The disadvantages are that reading the configuration
file takes a while, so the program doesn't feel as responsive as it should,
and ensuring that all the hosts' configuration files are synchronised becomes
Become daemons, if you're using a networked installation.
@menu
+* Requests and rules:: How the configuration file works
* Basic syntax:: Quick overview of Become's syntax
* Classes:: Defining classes of things
* Predefined classes:: Become predefines some (maybe) useful classes
* Allow statements:: Allow users to become other users
* Other statements:: Some other useful statements
* Example configuration file:: An example, showing a few features.
+* Checking and querying:: Checking and querying configuration files
* Complete grammar:: Complete grammar for Become config files
@end menu
-@node Basic syntax, Classes, The configuration file, The configuration file
+@node Requests and rules, Basic syntax, The configuration file, The configuration file
+@subsection Requests and rules
+
+Become looks at four pieces of information when it's analysing a request:
+
+@itemize @bullet
+@item
+the user's current identity;
+@item
+the identity the user wishes to assume;
+@item
+the host which generated the request; and
+@item
+the command the user wishes to run.
+@end itemize
+
+Each of these pieces of information is looked at when Become decides whether
+to honour a request.
+
+The configuration file's main purpose is to describe the conditions under
+which Become should honour a request. These conditions are described by a
+number of @emph{rules}. A rule consists of two lists of users (called `from'
+and `to'), a list of hosts, and a list of commands. A rule matches a request
+if:
+
+@itemize @bullet
+@item
+the user's current identity is in the rule's `from' list;
+@item
+the target user's identity is in the rule's `to' list;
+@item
+the host is in the rule's host list; and
+@item
+the command to be run is in the rule's command list.
+@end itemize
+
+A request is honoured if there is a rule which matches the request.
+
+
+@node Basic syntax, Classes, Requests and rules, The configuration file
@subsection Basic configuration file syntax
The configuration file consists of a sequence of statements, each terminated
Names begin with an alphabetic character or an underscore, and consist of
letters, digits and underscores.
-In general, ...
-
-
@node Classes, Predefined classes, Basic syntax, The configuration file
@subsection Classes
@end example
@noindent
-The @code{none} class isn't particularly useful in itself. It's there for
-completeness.
+The @code{none} class is provided because it's needed internally anyway and
+someone might come up with a use for it.
Become also defines some other classes:
It still needs to know about all the users known to the outside world.
Netgroups are read only from the NIS servers. In particular, although GNU
-systems allow netgroup databases to be stored in local files, Become wonn't
+systems allow netgroup databases to be stored in local files, Become won't
read them because there's no defined interface for enumerating netgroups.
@node Allow statements, Other statements, Predefined classes, The configuration file
@subsection Allow statements
-Defining classes is just a means to an end. The end is to specify which
-users are allowed to do what, where, and as whom. This is done with an
-@code{allow} statement:
+The @code{allow} statement defines the rules Become uses when deciding
+whether to grant a request; see @ref{Requests and rules}.
@example
allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
@var{key-file}, which must be a quoted string.
-@node Example configuration file, Complete grammar, Other statements, The configuration file
+@node Example configuration file, Checking and querying, Other statements, The configuration file
@subsection An example configuration file
@example
allow NEWS -> "news";
user HTTP = "jim", "bob";
-allow HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
+allow ["www.somewhere.com"]
+ HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
+@end example
+
+
+@node Checking and querying, Complete grammar, Example configuration file, The configuration file
+@subsection Checking and querying the configuration file
+
+At a reasonably sized site, Become configuration files can get rather large,
+and becomes tricky to work out exactly who's allowed to do what and where.
+
+The @code{bcquery} tool provided allows Become configuration files to be
+verified and queried. It can be used to ensure that a file is syntactically
+correct before it is deployed, or to enquire about privileges granted.
+
+@menu
+* Verifying config files:: Checking a configuration file is correct
+* Querying config files:: Asking questions about privileges
+* Output formats:: Different ways of formatting output
+* Restricting output:: Being selective about what gets output
+* bcquery reference:: Complete command line reference
+@end menu
+
+@node Verifying config files, Querying config files, Checking and querying, Checking and querying
+@subsubsection Verifying configuration files
+
+A common use of @code{bcquery} is to ensure that a configuration file is
+actually valid. The command
+
+@example
+bcquery [-file @var{file}] -check
+@end example
+
+@noindent
+verifies that a configuration file conforms to Become's expectations. If
+there are any errors in @var{file}, they are reported, and @code{bcquery}
+will return a nonzero exit code.
+
+If no @var{file} is specified, @code{bcquery} will read the configuration
+file which Become itself reads by default, usually
+@code{/etc/become/become.conf}.
+
+
+@node Querying config files, Output formats, Verifying config files, Checking and querying
+@subsubsection Querying configuration files
+
+The @code{bcquery} program will list all rules which match a selected request
+pattern. For example, you can display all rules which allow a particular
+user to change identity, or all rules which allow people to assume root
+privileges on a particular host.
+
+@example
+bcquery [-file @var{file}] @var{query}
+@end example
+
+The following simple queries are supported:
+
+@table @asis
+@item @code{-from} @var{user}
+Matches any rule containing @var{user} in its `from' list.
+@item @code{-to} @var{user}
+Matches any rule containing @var{user} in its `to' list.
+@item @code{-host} @var{host}
+Matches any rule containing @var{host} in its host list.
+@item @code{-command} @var{cmd}
+Matches any rule containing @var{cmd} in its `command' list.
+@end table
+
+@noindent
+Simple queries can be combined using the following operators:
+
+@table @asis
+@item @var{query-a} @code{-or} @var{query-b}
+Matches a rule matched by either @var{query-a} or @var{query-b}.
+@item @var{query-a} @code{-and} @var{query-b}
+Matches a rule matched by both @var{query-a} and @var{query-b}.
+@item @code{-not} @var{query}
+Matches a rule which is not matched by @var{query}.
+@item @code{(} @var{query} @code{)}
+Matches a rule matched by @var{query} (overrides default precedence).
+@end table
+
+The @code{-and}, @code{-or} and @code{-not} operators may be written
+@code{&}, @code{|} and @code{!} respectively, if you prefer, and the
+@code{-and} operator is optional. These characters (and the parentheses
+@code{(} and @code{)}) may need to be quoted to prevent interpretation by the
+shell.
+
+Some examples may explain what's going on:
+
+@table @samp
+@item bcquery -from hacker
+Displays all rules applying to user `hacker'.
+@item bcquery -host somehost -to root
+Displays rules allowing people to become root on @code{somehost}.
+@end table
+
+
+@node Output formats, Restricting output, Querying config files, Checking and querying
+@subsubsection Output formats
+
+The @code{bcquery} program has two distinct output formats: `rows' and
+`columns'.
+
+The `columns' format is probably the simpler to understand, and certainly the
+easier to read. Each matching record is displayed with the lists of users,
+hosts and commands in columns. A query on the example configuration file
+(@pxref{Example configuration file}) is shown below:
+
+@example
+FROM TO HOST COMMAND
+
+frankie root ALL ALL
+selina
+
+fred news ALL ALL
+jim
+
+jim httpd www.somewhere.com /bin/kill
+bob /etc/init.d/httpd
+@end example
+
+@noindent
+The `columns' format can only show simple lists. A more complex class
+definition will show up as @samp{<complex>} in a `columns' format listing.
+
+The `rows' format is capable of displaying classes in their full generality,
+but is harder to parse and read. It displays each list in the form of an
+expression, in more or less the same syntax as a class definition
+(@pxref{Classes}).
+
+The default behaviour is to use `columns' format where possible, or `rows'
+format if some of the lists are too complex to be represented in columns.
+You can select a format explicitly using the @code{-columns} or @code{-rows}
+options, which is useful if you're trying to parse the output of
+@code{bcquery} with a script.
+
+
+@node Restricting output, bcquery reference, Output formats, Checking and querying
+@subsubsection Restricting output
+
+It's also possible to suppress bits of information about each matched rule.
+For example, you can show only the `from' list, or just the `to' and `host'
+lists. This is done with the @code{-output} option.
+
+Each list is given a letter; the `from' list is called @samp{f}, the `to'
+list @samp{t}, the host list @samp{h} and the command list @samp{c}. You can
+select which lists are displayed by giving the corresponding letters (the
+order isn't important). You can also turn individual lists on or off by
+preceding the characters with @samp{+} or @samp{-} characters. If you start
+with a @samp{+} or @samp{-}, then the last-set selection (or the initial
+default of all-lists-enabled) is modified.
+
+For example, @samp{-output ftc} shows only the `from', `to' and `command'
+lists. This could be written @samp{-output -h} too, to turn the hosts list
+off.
+
+This option is mainly useful with the `columns' output format (@pxref{Output
+formats}) to save scripts having to select columns out themselves.
+
+
+@node bcquery reference, , Restricting output, Checking and querying
+@subsubsection @code{bcquery} options summary
+
+@example
+bcquery [@var{option}@dots{}] [@var{query}]
@end example
+The @var{option}s available are:
+
+@table @asis
+@item @code{-help}
+Displays a summary of the available options, and exits.
-@node Complete grammar, , Example configuration file, The configuration file
+@item @code{-file} @var{file}
+Read @var{file}, rather than the compiled-in default (usually
+@file{/etc/become/become.conf}).
+
+@item @code{-dump}
+Don't read a configuration file. Instead, display the query tree parsed from
+the command line. This is a debugging feature.
+
+@item @code{-check}
+Don't attempt to output any rules. Instead, just check the configuration
+file for validity.
+
+@item @code{-output} @var{spec}
+Selects which columns are to be displayed for each matching rule.
+For full details, see @ref{Restricting output}.
+
+@item @code{-columns}
+@itemx @code{-rows}
+Forces `columns' or `rows' output format. @xref{Output formats}.
+
+@item @code{-nohead}
+Suppress the header line at the top of the output in `columns' mode. Makes
+the output more amenable to automatic processing (but harder to read).
+
+@item @code{-from} @var{user}
+@itemx @code{-to} @var{user}
+@itemx @code{-host} @var{hostname}
+@itemx @code{-command} @var{cmd}
+Simple queries for selecting rules. @xref{Querying config files}.
+
+@item @code{-and}
+@itemx @code{-or}
+@itemx @code{-not}
+Operators for combining queries into something useful. @xref{Querying config
+files}.
+@end table
+
+
+@node Complete grammar, , Checking and querying, The configuration file
@subsection Complete grammar for configuration files
@format
@end format
+
@node Networked configuration, , The configuration file, Administering Become
@section Networked configuration
@menu
* Choosing servers:: Which servers Become tries to talk to
* Setting up keys:: How to generate keys for Become
-* Random number files:: Become keeps random number state around
* Issuing a new key:: How to issue new keys without disruption
@end menu
very much memory.
-@node Setting up keys, Random number files, Choosing servers, Networked configuration
+@node Setting up keys, Issuing a new key, Choosing servers, Networked configuration
@subsection Setting up keys
Communication between Become clients and the server is encrypted to ensure
that it's not feasible to gain unauthorised privilege by subverting the
-network. Become uses simple symmetric cryptography -- it's not necessary to
-use complicated public key techniques in this case.
+network. Become uses the DSA algorithm to ensure authenticity of replies.
Each client machine, and the server, must have a copy of the same key. The
key is usually stored in @file{/etc/become/become.key}. Become's keys are
128 bits long.
-The key file can be generated using the @code{keygen} program, supplied. The
-command
+The key file can be generated using Catacomb's @code{key} program. The
+commands
@example
-keygen --bits=128 --output=/etc/become/become.key
+key -k /etc/become/become.key add -adsa -e"now + 1 year" become
+key -k /etc/become/become.key extract -f -secret /etc/become/become.pubkey
@end example
@noindent
-generates a 128-bit key and writes it to @file{/etc/become/become.key} in a
-format which Become can read.
-
-The @code{keygen} program works by measuring the time between keystrokes. It
-also tries to obtain some randomness from the environment, and mixes all of
-this noise together before it outputs the key file.
-
-Having generated a key, it must be distributed to all of the other hosts
-which will use this server. The author recommends using the @code{scp}
-program, distributed with the @code{SSH} (Secure Shell) package, for doing
-this.
+will generate a suitable DSA key, and extract the public part. You should
+install the public key on all of your client computers, writable only by
+root. The private key should be only on the server, and readable or writable
+only by root.
-Being able to read a key file enables a user to assume root privileges. The
-author recommends that only the super-user be able to read key files.
-
-@menu
-* Invoking keygen:: How to use the @code{keygen} program
-@end menu
-
-
-@node Invoking keygen, , Setting up keys, Setting up keys
-@subsubsection Invoking @code{keygen}
+You can also use elliptic-curve DSA. The key-generation runes are more
+complicated in this case. For example,
@example
-keygen [@var{option}@dots{}]
+key -k /etc/become/become.key add -aec -Cnist-p256 -e"now + 1 year" \
+ become sig=ecdsa hash=sha256
@end example
+The @code{hash=sha256} is not required, but it's good to have a hash function
+as strong as your curve. See the manpage for @code{key} for more details
+about generating elliptic curve keys, and for the kinds of curves supported.
-By default, @code{keygen} generates a 128-bit key, and writes it to standard
-output in a hexadecimal format. This behaviour can be modified by passing
-options:
-
-@table @code
-@item -h
-@itemx --help
-Write a summary of @code{keygen}'s usage instructions to standard output and
-exits.
-
-@item -b @var{bits}
-@itemx --bits=@var{bits}
-Generate a @var{bits}-bit key, instead of the default 128 bits.
-
-@item -o @var{file}
-@itemx --output=@var{file}
-Write the key to @var{file} instead of standard output.
-
-@item -f @var{format}
-@itemx --format=@var{format}
-Set the format in which @code{keygen} outputs the generated key. If the
-@var{format} is @samp{hex} (or @samp{tx}), the key is output in Become's
-hexadecimal format; @samp{binary} writes the key as a raw binary dump; and
-@samp{base64} writes the key using the Base64 encoding.
-@end table
-
-
+If you have multiple servers, they can all have different private keys.
+You'll need to put all of the public keys in the
+@file{/etc/become/become.pubkey} file.
-@node Random number files, Issuing a new key, Setting up keys, Networked configuration
-@subsection Random number files
-Become uses random numbers to generate session keys when it's communicating
-with a server. When it's finished, it stores the state of its random number
-generator in a file, usually @code{/etc/become/become.random}. If this file
-doesn't exist, Become creates it automatically, using noise collected from
-the environment. It's probably not worth your while creating randomness
-files by hand.
-
-
-@node Issuing a new key, , Random number files, Networked configuration
+@node Issuing a new key, , Setting up keys, Networked configuration
@subsection Issuing a new key
When you're sending out a new key, you run a risk of disrupting service. The
server reads a new key; the clients still have the old one.
-The author's recommendation is to run two servers. Update the key on one.
-Then send the new key to all of the clients. Finally, update the key on the
-other server. Because of the way Become works, a client will always get a
-response from one of the servers, depending on whether the new key has
-reached it yet.
-
-A similar method is handy if Become's protocol ever changes. (This is quite
-likely at the moment. The current protocol doesn't include any version
-information, and the MAC isn't as good as it could be.)
+We used to recommend running two servers. Now, however, you can generate the
+new key, install the new public key on the clients in addition to the old
+one, and then install the new private key on the server. The clients try all
+valid public keys when attempting to authenticate a response, so this
+approach will work.
@c --------------------------------------------------------------------------
The @var{command} name is used both as the command to execute and passed to
the command as @code{argv[0]}. It is not possible to specify an alternative
-calue to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
+value to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
passed as @code{argv[1]} upwards.
If no @var{command} is given, a shell is invoked; the particulars of the
@item -f @var{file}
@itemx --config-file=@var{file}
-Read configuration from @var{file}, instead of the default (usually
-@file{/etc/become/become.conf}).
+Read configuration from @var{file}, instead of the default (set at
+compile time, usually @file{/etc/become/become.conf}).
@end table
The syntax of the configuration file is described in @ref{The configuration
@c @unnumbered Concept index
@c @printindex cp
@c
-@c @contents
+@contents
@bye
~mdw / become / blobdiff