X-Git-Url: https://git.distorted.org.uk/~mdw/become/blobdiff_plain/10bc033fb9d7a29c5e0b4f05c46e40cc10e081b3..ac67be2ec5a39ccfef5bdacd7975e874952eaa33:/manual/become.texi diff --git a/manual/become.texi b/manual/become.texi index cdf6ef1..5944e9a 100644 --- a/manual/become.texi +++ b/manual/become.texi @@ -1,30 +1,12 @@ \input texinfo @c -*-texinfo-*- @c -@c $Id: become.texi,v 1.4 1998/04/23 13:16:14 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.4 1998/04/23 13:16:14 mdw -@c Include `texinice' to produce decent printed output. Add documentation -@c for new `bcquery' program. Various fixes, including spelling mistakes, -@c and some factual inaccuracies. -@c -@c Revision 1.3 1998/01/20 14:37:43 mdw -@c Fix typo. Short form of `--preserve' should be `-e', not `-p'. -@c -@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 @@ -40,9 +22,14 @@ @end iftex @c %**end of header +@dircategory Administration tools +@direntry +* Become: (become). Shared account administration tool +@end direntry + @c ----- Useful macros ------------------------------------------------------ -@set version 1.3 +@set version 1.4 @c ----- Copyright matters -------------------------------------------------- @@ -133,6 +120,7 @@ This file documents Become version @value{version}. * Administering Become:: How to maintain Become * Invoking Become:: Reference to Become's command line options +@detailmenu --- The Detailed Node Listing --- Becoming someone else @@ -197,18 +185,15 @@ 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 -------------------------------------------------------------------------- @@ -925,16 +910,16 @@ when they get there. Only needed on servers or standalone machines. 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 @@ -1477,7 +1462,6 @@ section. @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 @@ -1508,107 +1492,58 @@ Become isn't particularly processor-intensive, and doesn't seem to require 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. +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. -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. - -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 --------------------------------------------------------------------------