X-Git-Url: https://git.distorted.org.uk/~mdw/become/blobdiff_plain/10bc033fb9d7a29c5e0b4f05c46e40cc10e081b3..b0f66028a9a17a845590a4fe737a4f5e46f6b778:/manual/become.texi diff --git a/manual/become.texi b/manual/become.texi index cdf6ef1..6097465 100644 --- a/manual/become.texi +++ b/manual/become.texi @@ -1,6 +1,6 @@ \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.7 2003/11/29 23:39:16 mdw Exp $ @c @c Documentation for `become' @c @@ -10,6 +10,16 @@ @c ----- Revision history --------------------------------------------------- @c @c $Log: become.texi,v $ +@c Revision 1.7 2003/11/29 23:39:16 mdw +@c Debianization. +@c +@c Revision 1.6 2003/10/26 11:57:46 mdw +@c Fix key reloading core dumps. Change advice on keys. +@c +@c Revision 1.5 2003/10/12 00:14:49 mdw +@c Major overhaul. Now uses DSA signatures rather than the bogus symmetric +@c encrypt-and-hope thing. Integrated with mLib and Catacomb. +@c @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, @@ -40,9 +50,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 +148,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 +213,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 +938,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 +1490,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 +1520,47 @@ 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-dsa +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. - -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 +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. +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 Invoking keygen, , Setting up keys, Setting up keys -@subsubsection Invoking @code{keygen} -@example -keygen [@var{option}@dots{}] -@end example - -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 - - - -@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 --------------------------------------------------------------------------