1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
=for stopwords
wallet-rekey rekey rekeying keytab -hv Heimdal remctl remctld PKINIT kinit
appdefaults Allbery
=head1 NAME
wallet-rekey - Client for rekeying a Kerberos keytab using wallet
=head1 SYNOPSIS
B<wallet-rekey> [B<-hv>] [B<-c> I<command>] [B<-k> I<principal>]
[B<-p> I<port>] [B<-s> I<server>] [B<-u> I<principal>] [I<keytab> ...]
=head1 DESCRIPTION
B<wallet-rekey> is a specialized client for the wallet system used to
rekey a Kerberos keytab by downloading new keytab objects from wallet for
each principal found in the keytab. For each keytab file listed on the
command line, it walks through the principals in that keytab, finds all
from the local default realm, requests new wallet keytab objects for each
principal (removing the realm when naming the keytab), and merges the new
keys into the keytab.
If an error occurs before any new keys were downloaded, B<wallet-rekey>
aborts. If some new keys were successfully downloaded, B<wallet-rekey>
warns about errors but continues to rekey all principals that it can. In
this case, a copy of the existing keytab prior to the rekeying is saved in
a file named by appending C<.old> to the file name.
If no keytab file name is given on the command line, B<wallet-rekey>
attempts to rekey F</etc/krb5.keytab>, the system default keytab file.
The new keys are merged into the existing keytab file, but old keys are
not removed. This means that, over time, the keytab will grow and
accumulate old keys, which eventually should no longer be honored.
Administrators may want to run:
kadmin -q 'ktremove -k <keytab> <principal> old'
for MIT Kerberos, where <keytab> is the path to the keytab and <principal>
is a principal in the keytab (repeating the command for each principal)
or:
ktutil -k <keytab> purge
for Heimdal. This functionality will eventually be provided by
B<wallet-rekey> directly.
=head1 OPTIONS
=over 4
=item B<-c> I<command>
The command prefix (remctl type) to use. Normally this is an internal
implementation detail and the default (C<wallet>) should be fine. It may
sometimes be useful to use a different prefix for testing a different
version of the wallet code on the server. This option can also be set in
F<krb5.conf>; see L<CONFIGURATION> below.
=item B<-k> I<principal>
The service principal of the wallet server. The default is to use the
C<host> principal for the wallet server. The principal chosen must match
one of the keys in the keytab used by B<remctld> on the wallet server.
This option can also be set in F<krb5.conf>; see L<CONFIGURATION> below.
=item B<-h>
Display a brief summary of options and exit. All other valid options and
commands are ignored.
=item B<-p> I<port>
The port to connect to on the wallet server. The default is the default
remctl port. This option can also be set in F<krb5.conf>; see
L<CONFIGURATION> below.
=item B<-s> I<server>
The wallet server to connect to. The default may be set when compiling
the wallet client. If it isn't, either B<-s> must be given or the server
must be set in F<krb5.conf>. See L<CONFIGURATION> below.
=item B<-u> I<principal>
Rather than using the user's existing ticket cache for authentication,
authenticate as I<principal> first and use those credentials for
authentication to the wallet server. B<wallet> will prompt for the
password for I<principal>. Non-password authentication methods such as
PKINIT aren't supported; to use those, run B<kinit> first and use an
existing ticket cache.
=item B<-v>
Display the version of the B<wallet> client and exit. All other valid
options and commands are ignored.
=back
=head1 CONFIGURATION
The wallet system, including B<wallet-rekey>, can optionally be configured
in the system F<krb5.conf>. It will read the default F<krb5.conf> file
for the Kerberos libraries with which it was compiled. To set an option,
put the option in the [appdefaults] section. B<wallet-rekey> will look
for options either at the top level of the [appdefaults] section or in a
subsection named C<wallet>. For example, the following fragment of a
F<krb5.conf> file would set the default port to 4373 and the default
server to C<wallet.example.org>.
[appdefaults]
wallet_port = 4373
wallet = {
wallet_server = wallet.example.org
}
The supported options are:
=over 4
=item wallet_principal
The service principal of the wallet server. The default is to use the
C<host> principal for the wallet server. The principal chosen must match
one of the keys in the keytab used by B<remctld> on the wallet server.
The B<-k> command-line option overrides this setting.
=item wallet_port
The port to connect to on the wallet server. The default is the default
remctl port. The B<-p> command-line option overrides this setting.
=item wallet_server
The wallet server to connect to. The B<-s> command-line option overrides
this setting. The default may be set when compiling the wallet client.
If it isn't, either B<-s> must be given or this parameter must be present
in in F<krb5.conf>.
=item wallet_type
The command prefix (remctl type) to use. Normally this is an internal
implementation detail and the default (C<wallet>) should be fine. It may
sometimes be useful to use a different prefix for testing a different
version of the wallet code on the server. The B<-c> command-line option
overrides this setting.
=back
=head1 AUTHOR
Russ Allbery <rra@stanford.edu>
=head1 COPYRIGHT AND LICENSE
Copyright 2010, 2013 The Board of Trustees of the Leland Stanford Junior
University
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved. This file is offered as-is, without any
warranty.
=head1 SEE ALSO
kadmin(8), kinit(1), krb5.conf(5), remctl(1), remctld(8), wallet(1)
This program is part of the wallet system. The current version is available
from L<http://www.eyrie.org/~eagle/software/wallet/>.
B<wallet-rekey> uses the remctl protocol. For more information about
remctl, see L<http://www.eyrie.org/~eagle/software/remctl/>.
=cut
|
