From: Russ Allbery Date: Mon, 10 May 2010 00:58:33 +0000 (-0700) Subject: Update bos addkey/listkeys and KeyFile man pages for asetkey X-Git-Tag: openafs-devel-1_5_75~256 X-Git-Url: https://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=3015ef6c594fa999c29e390a76c384eed09619d4;hp=5ae464b185115e3537bbef862d893190bb56ab05 Update bos addkey/listkeys and KeyFile man pages for asetkey Clearly prefer asetkey to bos addkey in the KeyFile, bos addkey, and bos listkeys man pages. Reference asetkey list and asetkey delete as alternatives to bos listkeys and bos removekey. Distinguish between Authentication Server cells and Kerberos v5 cells and mention the preferred afs/ principal format. Add some cautions around matching enctypes and salts when synchronizing keys with a v5 KDC. Update man-pages/README for completion of this task, clean up some other wording, and remove some other now-irrelevant information. Change-Id: I29b83a61cbdb08de508bdb313524a307e385044b Reviewed-on: http://gerrit.openafs.org/1938 Reviewed-by: Jeffrey Altman Reviewed-by: Andrew Deason Tested-by: Russ Allbery Reviewed-by: Russ Allbery --- diff --git a/doc/man-pages/README b/doc/man-pages/README index cde7896..e5e8fb5 100644 --- a/doc/man-pages/README +++ b/doc/man-pages/README @@ -180,13 +180,13 @@ Man Page Sections How You Can Help - The OpenAFS man page project is just starting, and a lot of work remains - to be done. Any and all contributions are greatly appreciated. What - follows is a list of the ways that you can help in order of increasing - helpfulness. If you only have time to do something near the top of the - list, please do; every little bit helps. If you have more time and can - do something closer to the bottom of the list, that's even better and - your contribution can be included more rapidly. + A lot of work remains to be done on the OpenAFS man page project. Any + and all contributions are greatly appreciated. What follows is a list + of the ways that you can help in order of increasing helpfulness. If + you only have time to do something near the top of the list, please do; + every little bit helps. If you have more time and can do something + closer to the bottom of the list, that's even better and your + contribution can be included more rapidly. * Point out places OpenAFS behavior has changed since the documentation was written, or point out missing documentation. Please check the @@ -213,11 +213,11 @@ How You Can Help * Provide patches against the POD source that add or correct the documentation of commands or file formats for changes in OpenAFS. - Please send contributions either to the openafs-doc list or as bugs - filed via the bug reporting instructions at . - If you do submit a bug, please send me a note at rra@stanford.edu with - the bug number so that I'm aware of it, as I don't always notice new - bugs. + Please submit contributions to Gerrit or send them either to the + openafs-doc list or as bugs filed via the bug reporting instructions at + . If you do submit a bug, please send me a + note at rra@stanford.edu with the bug number so that I'm aware of it, as + I don't always notice new bugs. You can test your new POD documentation by running the check-pod script in this directory with "prove check-pod". (And check other people's @@ -233,12 +233,6 @@ Known Problems * Some of the documentation in fs getserverprefs needs minor updates to reflect what happens in the dynroot case. - * bos listkeys and the KeyFile man page assume that you're using the - kaserver. - - * bos addkey should be marked deprecated in favor of using asetkey with - a keytab. - * There are lingering references to AFS Development or AFS Product Support in descriptions of options that one should generally not use. Also, all of the manual references refer to the "IBM" manual. @@ -269,19 +263,15 @@ Known Problems * Provide a way to substitute the correct paths into the HTML output from Autoconf results. - * Currently, the man pages are built by regen.sh, which is somewhat - annoying since it takes a long time. Figure out how better to do this - during the release process so that end users don't have to have - pod2man. - * Review the sections used for all man pages against what directories the commands are installed into. (In some cases, it may be better to change the directory than the section of the man page.) * Consider using M4 or similar to operate on POD text before output. - This would allow common options like vos -c,-noa,-l,-v,-e,-nor - to be documented once and automatically included in all vos_ reference - pages, much like the vos.c source includes those arguments as COMMONPARMS. + This would allow common options like vos -c,-noa,-l,-v,-e,-nor to be + documented once and automatically included in all vos_ reference + pages, much like the vos.c source includes those arguments as + COMMONPARMS. * Check that suite intro pages mention all subcommands diff --git a/doc/man-pages/pod5/KeyFile.pod b/doc/man-pages/pod5/KeyFile.pod index df35f80..875be0e 100644 --- a/doc/man-pages/pod5/KeyFile.pod +++ b/doc/man-pages/pod5/KeyFile.pod @@ -11,41 +11,72 @@ perform privileged actions only for clients that possess a ticket encrypted with one of the keys from the file. The file must reside in the F directory on every server machine. For more detailed information on mutual authentication and server encryption keys, see the -I. +I. Each key has a corresponding a key version number that distinguishes it from the other keys. The tickets that clients present are also marked with a key version number to tell the server process which key to use to decrypt it. The F file must always include a key with the same -key version number and contents as the key currently listed for the C -entry in the Authentication Database. - -The F file is in binary format, so always use the appropriate -commands from the B command suite to administer it: +key version number and contents as the key currently listed for the +C> principal in the associated Kerberos v5 realm or +Authentication Database. (The principal C may be used if the cell and +realm names are the same, but adding the cell name to the principal is +recommended even in this case. C must be used as the principal name +if the cell uses the Authentication Server rather than a Kerberos v5 +realm.) The key must be a DES key; no stronger encryption type is +supported. + +The F file is in binary format, so always use either the +B command or the appropriate commands from the B command +suite to administer it: =over 4 =item * -The B command to define a new key. +The B or B command to add a new key. =item * -The B command to display the keys. +The B or B command to display the keys. =item * -The B command to remove a key from the file. +The B or B command to remove a key from the +file. =back +The B commands must be run on the same server as the F +file to update. The B commands may be run remotely. Normally, new +keys should be added from a Kerberos v5 keytab using B. +B is normally only used if the Authentication Server is in use +instead of a Kerberos v5 realm. + In cells that use the Update Server to distribute the contents of the F directory, it is customary to edit only the copy of the file stored on the system control machine. Otherwise, edit the file on each server machine individually. +=head1 CAUTIONS + +The most common error caused by changes to F is to add a key that +does not match the corresponding key for the Kerberos v5 principal or +Authentication Server database entry. Both the key and the key version +number must match the key for the corresponding principal, either +C> or C, in the Kerberos v5 realm or Authentication +Database. For a Kerberos v5 realm, that principal must only have DES +encryption types in the Kerberos KDC. + +In the unusual case of using B to add a key with a known +password matching a password used to generate Kerberos v5 keys, the keys +in the Kerberos v5 KDC database must use C salt, not the default +Kerberos v5 salt. The salt doesn't matter for the more normal procedure of +extracting a keytab and then adding the key using B. + =head1 SEE ALSO +L, L, L, L, @@ -53,12 +84,13 @@ L, L, L -I +The I at +L. =head1 COPYRIGHT IBM Corporation 2000. All Rights Reserved. -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. +This documentation is covered by the IBM Public License Version 1.0. It +was converted from HTML to POD by software written by Chas Williams and +Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/bos_addkey.pod b/doc/man-pages/pod8/bos_addkey.pod index 5f51b2e..2678d09 100644 --- a/doc/man-pages/pod8/bos_addkey.pod +++ b/doc/man-pages/pod8/bos_addkey.pod @@ -23,9 +23,18 @@ B S<<< B<-s> > >>> S<<< [B<-ke> >] >>> The B command constructs a server encryption key from the text string provided, assigns it the key version number specified with the B<-kvno> argument, and adds it to the F file on the -machine specified with the B<-server> argument. Be sure to use the B or B command to add the same key to the C -entry in the Authentication Database. +machine specified with the B<-server> argument. + +Normally, B should be used instead of this command; see +L for more details. The primary use of B is for +cells that are still using the Authentication Server instead of a Kerberos +v5 KDC. It may, however, also be useful in unusual circumstances where a +key needs to be added based on a known password rather than via a Kerberos +v5 keytab. + +When using B with an AFS cell that uses the Authentication +Server, be sure to use the B or B command to +add the same key to the C entry in the Authentication Database. Do not use the B<-key> argument, which echoes the password string visibly on the screen. If the argument is omitted, the BOS Server prompts for the @@ -41,6 +50,15 @@ with a server process because the current key is overwritten with a new key. Use the B command to display the key version numbers in the F file. +=head1 CAUTIONS + +In the unusual case of using B to add a key with a known +password matching a password used to generate Kerberos v5 keys, the key in +the Kerberos v5 KDC database must have only the DES encryption type and +must use C salt, not the default Kerberos v5 salt. Otherwise, the +key generated by B will not match the key generated by the +Kerberos v5 KDC. + =head1 OPTIONS =over 4 @@ -127,6 +145,7 @@ included. L, L, +L, L, L, L @@ -135,6 +154,6 @@ L IBM Corporation 2000. All Rights Reserved. -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. +This documentation is covered by the IBM Public License Version 1.0. It +was converted from HTML to POD by software written by Chas Williams and +Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/bos_listkeys.pod b/doc/man-pages/pod8/bos_listkeys.pod index 772f59b..0406d3c 100644 --- a/doc/man-pages/pod8/bos_listkeys.pod +++ b/doc/man-pages/pod8/bos_listkeys.pod @@ -20,10 +20,14 @@ B S<<< B<-se> > >>> [B<-sh>] S<<< [B<-c> command formats and displays the list of server encryption keys from the F file on the server -machine named by the B<-server> argument. +machine named by the B<-server> argument. It is equivalent to B, but can be run remotely. -To edit the list of keys, use the B and B -commands. +To edit the list of keys, use the B command; see L +for more information. You can also remove keys remotely using the B command. If you are using the Authentication Server +(B) rather than a Kerberos v5 KDC, use the B command +instead of B to add a new key. =head1 CAUTIONS @@ -42,12 +46,15 @@ file. Identify the machine by IP address or its host name (either fully-qualified or abbreviated unambiguously). For details, see L. For consistent performance in the cell, the output must be the same on -every server machine. The B reference page explains how to -keep the machines synchronized. +every server machine. L explains how to keep the machines +synchronized. =item B<-showkey> -Displays the octal digits that constitute each key. +Displays the octal digits that constitute each key. Anyone who has access +to the resulting output will have complete access to the AFS cell and will +be able to impersonate the AFS cell to any client, so be very careful when +using this option. =item B<-cell> > @@ -130,6 +137,7 @@ included. L, L, +L, L, L, L, @@ -139,6 +147,6 @@ L IBM Corporation 2000. All Rights Reserved. -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. +This documentation is covered by the IBM Public License Version 1.0. It +was converted from HTML to POD by software written by Chas Williams and +Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.