1  .\" Copyright (c) 2003 - 2004 Kungliga Tekniska Högskolan
  2  .\" (Royal Institute of Technology, Stockholm, Sweden).
  3  .\" All rights reserved.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\"
  9  .\" 1. Redistributions of source code must retain the above copyright
 10  .\"    notice, this list of conditions and the following disclaimer.
 11  .\"
 12  .\" 2. Redistributions in binary form must reproduce the above copyright
 13  .\"    notice, this list of conditions and the following disclaimer in the
 14  .\"    documentation and/or other materials provided with the distribution.
 15  .\"
 16  .\" 3. Neither the name of the Institute nor the names of its contributors
 17  .\"    may be used to endorse or promote products derived from this software
 18  .\"    without specific prior written permission.
 19  .\"
 20  .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 21  .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22  .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23  .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 24  .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25  .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 26  .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 27  .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 28  .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 29  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 30  .\" SUCH DAMAGE.
 31  .\"
 32  .\" $Id$
 33  .\"
 34  .Dd August 24, 2006
 35  .Dt KDC 8
 36  .Os HEIMDAL
 37  .Sh NAME
 38  .Nm kdc
 39  .Nd Kerberos 5 server
 40  .Sh SYNOPSIS
 41  .Nm
 42  .Bk -words
 43  .Oo Fl c Ar file \*(Ba Xo
 44  .Fl Fl config-file= Ns Ar file
 45  .Xc
 46  .Oc
 47  .Op Fl p | Fl Fl no-require-preauth
 48  .Op Fl Fl max-request= Ns Ar size
 49  .Op Fl H | Fl Fl enable-http
 50  .Op Fl Fl no-524
 51  .Op Fl Fl kerberos4
 52  .Op Fl Fl kerberos4-cross-realm
 53  .Oo Fl r Ar string \*(Ba Xo
 54  .Fl Fl v4-realm= Ns Ar string
 55  .Xc
 56  .Oc
 57  .Op Fl K | Fl Fl kaserver
 58  .Oo Fl P Ar portspec \*(Ba Xo
 59  .Fl Fl ports= Ns Ar portspec
 60  .Xc
 61  .Oc
 62  .Op Fl Fl detach
 63  .Op Fl Fl disable-des
 64  .Op Fl Fl addresses= Ns Ar list of addresses
 65  .Ek
 66  .Sh DESCRIPTION
 67  .Nm
 68  serves requests for tickets.
 69  When it starts, it first checks the flags passed, any options that are
 70  not specified with a command line flag are taken from a config file,
 71  or from a default compiled-in value.
 72  .Pp
 73  Options supported:
 74  .Bl -tag -width Ds
 75  .It Fl c Ar file , Fl Fl config-file= Ns Ar file
 76  Specifies the location of the config file, the default is
 77  .Pa /var/heimdal/kdc.conf .
 78  This is the only value that can't be specified in the config file.
 79  .It Fl p , Fl Fl no-require-preauth
 80  Turn off the requirement for pre-autentication in the initial AS-REQ
 81  for all principals.
 82  The use of pre-authentication makes it more difficult to do offline
 83  password attacks.
 84  You might want to turn it off if you have clients
 85  that don't support pre-authentication.
 86  Since the version 4 protocol doesn't support any pre-authentication,
 87  serving version 4 clients is just about the same as not requiring
 88  pre-athentication.
 89  The default is to require pre-authentication.
 90  Adding the require-preauth per principal is a more flexible way of
 91  handling this.
 92  .It Fl Fl max-request= Ns Ar size
 93  Gives an upper limit on the size of the requests that the kdc is
 94  willing to handle.
 95  .It Fl H , Fl Fl enable-http
 96  Makes the kdc listen on port 80 and handle requests encapsulated in HTTP.
 97  .It Fl Fl no-524
 98  don't respond to 524 requests
 99  .It Fl Fl kerberos4
100  respond to Kerberos 4 requests
101  .It Fl Fl kerberos4-cross-realm
102  respond to Kerberos 4 requests from foreign realms.
103  This is a known security hole and should not be enabled unless you
104  understand the consequences and are willing to live with them.
105  .It Fl r Ar string , Fl Fl v4-realm= Ns Ar string
106  What realm this server should act as when dealing with version 4
107  requests.
108  The database can contain any number of realms, but since the version 4
109  protocol doesn't contain a realm for the server, it must be explicitly
110  specified.
111  The default is whatever is returned by
112  .Fn krb_get_lrealm .
113  This option is only available if the KDC has been compiled with version
114  4 support.
115  .It Fl K , Fl Fl kaserver
116  Enable kaserver emulation (in case it's compiled in).
117  .It Fl P Ar portspec , Fl Fl ports= Ns Ar portspec
118  Specifies the set of ports the KDC should listen on.
119  It is given as a
120  white-space separated list of services or port numbers.
121  .It Fl Fl addresses= Ns Ar list of addresses
122  The list of addresses to listen for requests on.
123  By default, the kdc will listen on all the locally configured
124  addresses.
125  If only a subset is desired, or the automatic detection fails, this
126  option might be used.
127  .It Fl Fl detach
128  detach from pty and run as a daemon.
129  .It Fl Fl disable-des
130  disable add des encryption types, makes the kdc not use them.
131  .El
132  .Pp
133  All activities are logged to one or more destinations, see
134  .Xr krb5.conf 5 ,
135  and
136  .Xr krb5_openlog 3 .
137  The entity used for logging is
138  .Nm kdc .
139  .Sh CONFIGURATION FILE
140  The configuration file has the same syntax as
141  .Xr krb5.conf 5 ,
142  but will be read before
143  .Pa /etc/krb5.conf ,
144  so it may override settings found there.
145  Options specific to the KDC only are found in the
146  .Dq [kdc]
147  section.
148  All the command-line options can preferably be added in the
149  configuration file.
150  The only difference is the pre-authentication flag, which has to be
151  specified as:
152  .Pp
153  .Dl require-preauth = no
154  .Pp
155  (in fact you can specify the option as
156  .Fl Fl require-preauth=no ) .
157  .Pp
158  And there are some configuration options which do not have
159  command-line equivalents:
160  .Bl -tag -width "xxx" -offset indent
161  .It Li enable-digest = Va boolean
162  turn on support for digest processing in the KDC.
163  The default is FALSE.
164  .It Li check-ticket-addresses = Va boolean
165  Check the addresses in the ticket when processing TGS requests.
166  The default is TRUE.
167  .It Li allow-null-ticket-addresses = Va boolean
168  Permit tickets with no addresses.
169  This option is only relevant when check-ticket-addresses is TRUE.
170  .It Li allow-anonymous = Va boolean
171  Permit anonymous tickets with no addresses.
172  .It Li max-kdc-datagram-reply-length = Va number
173  Maximum packet size the UDP rely that the KDC will transmit, instead
174  the KDC sends back a reply telling the client to use TCP instead.
175  .It Li transited-policy = Li always-check \*(Ba \
176  Li allow-per-principal | Li always-honour-request
177  This controls how KDC requests with the
178  .Li disable-transited-check
179  flag are handled. It can be one of:
180  .Bl -tag -width "xxx" -offset indent
181  .It Li always-check
182  Always check transited encoding, this is the default.
183  .It Li allow-per-principal
184  Currently this is identical to
185  .Li always-check .
186  In a future release, it will be possible to mark a principal as able
187  to handle unchecked requests.
188  .It Li always-honour-request
189  Always do what the client asked.
190  In a future release, it will be possible to force a check per
191  principal.
192  .El
193  .It encode_as_rep_as_tgs_rep = Va boolean
194  Encode AS-Rep as TGS-Rep to be bug-compatible with old DCE code.
195  The Heimdal clients allow both.
196  .It kdc_warn_pwexpire = Va time
197  How long before password/principal expiration the KDC should start
198  sending out warning messages.
199  .El
200  .Pp
201  The configuration file is only read when the
202  .Nm
203  is started.
204  If changes made to the configuration file are to take effect, the
205  .Nm
206  needs to be restarted.
207  .Pp
208  An example of a config file:
209  .Bd -literal -offset indent
210  [kdc]
211  	require-preauth = no
212  	v4-realm = FOO.SE
213  .Ed
214  .Sh BUGS
215  If the machine running the KDC has new addresses added to it, the KDC
216  will have to be restarted to listen to them.
217  The reason it doesn't just listen to wildcarded (like INADDR_ANY)
218  addresses, is that the replies has to come from the same address they
219  were sent to, and most OS:es doesn't pass this information to the
220  application.
221  If your normal mode of operation require that you add and remove
222  addresses, the best option is probably to listen to a wildcarded TCP
223  socket, and make sure your clients use TCP to connect.
224  For instance, this will listen to IPv4 TCP port 88 only:
225  .Bd -literal -offset indent
226  kdc --addresses=0.0.0.0 --ports="88/tcp"
227  .Ed
228  .Pp
229  There should be a way to specify protocol, port, and address triplets,
230  not just addresses and protocol, port tuples.
231  .Sh SEE ALSO
232  .Xr kinit 1 ,
233  .Xr krb5.conf 5