\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
@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 --------------------------------------------------
* Administering Become:: How to maintain Become
* Invoking Become:: Reference to Become's command line options
+@detailmenu
--- The Detailed Node Listing ---
Becoming someone else
* 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 --------------------------------------------------------------------------
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
@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.
+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 --------------------------------------------------------------------------
~mdw / become / blobdiff