third_party/heimdal/kdc/kdc.8

   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 .Oo Fl P Ar portspec \*(Ba Xo
  51 .Fl Fl ports= Ns Ar portspec
  52 .Xc
  53 .Oc
  54 .Op Fl Fl detach
  55 .Op Fl Fl disable-des
  56 .Op Fl Fl addresses= Ns Ar list of addresses
  57 .Ek
  58 .Sh DESCRIPTION
  59 .Nm
  60 serves requests for tickets.
  61 When it starts, it first checks the flags passed, any options that are
  62 not specified with a command line flag are taken from a config file,
  63 or from a default compiled-in value.
  64 .Pp
  65 Options supported:
  66 .Bl -tag -width Ds
  67 .It Fl c Ar file , Fl Fl config-file= Ns Ar file
  68 Specifies the location of the config file, the default is
  69 .Pa /var/heimdal/kdc.conf .
  70 This is the only value that can't be specified in the config file.
  71 .It Fl p , Fl Fl no-require-preauth
  72 Turn off the requirement for pre-autentication in the initial AS-REQ
  73 for all principals.
  74 The use of pre-authentication makes it more difficult to do offline
  75 password attacks.
  76 You might want to turn it off if you have clients
  77 that don't support pre-authentication.
  78 Since the version 4 protocol doesn't support any pre-authentication,
  79 serving version 4 clients is just about the same as not requiring
  80 pre-athentication.
  81 The default is to require pre-authentication.
  82 Adding the require-preauth per principal is a more flexible way of
  83 handling this.
  84 .It Fl Fl max-request= Ns Ar size
  85 Gives an upper limit on the size of the requests that the kdc is
  86 willing to handle.
  87 .It Fl H , Fl Fl enable-http
  88 Makes the kdc listen on port 80 and handle requests encapsulated in HTTP.
  89 .It Fl P Ar portspec , Fl Fl ports= Ns Ar portspec
  90 Specifies the set of ports the KDC should listen on.
  91 It is given as a
  92 white-space separated list of ports.
  93 A port value of
  94 .Sq +
  95 indicates that the standard ports should be used.
  96 Other values should be service names or port numbers as resolved by
  97 .Xr getservbyname 3
  98 (e.g.,
  99 .Dq kerberos/udp ,
 100 .Dq kerberos/tcp ,
 101 .Dq 8088/udp ,
 102 etc.), or plain numeric port numbers (e.g.,
 103 .Dq 9088
 104 ).
 105 Plain numeric port numbers will be used with both UDP and TCP.
 106 See also the
 107 .Dq [kdc] ports
 108 configuration parameter discussion in
 109 .Xr krb5.conf 5 .
 110 .It Fl Fl addresses= Ns Ar list of addresses
 111 The list of addresses to listen for requests on.
 112 By default, the kdc will listen on all the locally configured
 113 addresses.
 114 If only a subset is desired, or the automatic detection fails, this
 115 option might be used.
 116 .It Fl Fl detach
 117 detach from pty and run as a daemon.
 118 .It Fl Fl disable-des
 119 disable all des encryption types, makes the kdc not use them.
 120 .El
 121 .Pp
 122 All activities are logged to one or more destinations, see
 123 .Xr krb5.conf 5 ,
 124 and
 125 .Xr krb5_openlog 3 .
 126 The entity used for logging is
 127 .Nm kdc .
 128 .Sh CONFIGURATION FILE
 129 The configuration file has the same syntax as
 130 .Xr krb5.conf 5 ,
 131 but will be read before
 132 .Pa /etc/krb5.conf ,
 133 so it may override settings found there.
 134 Options specific to the KDC only are found in the
 135 .Dq [kdc]
 136 section.
 137 All the command-line options can preferably be added in the
 138 configuration file.
 139 The only difference is the pre-authentication flag, which has to be
 140 specified as:
 141 .Pp
 142 .Dl require-preauth = no
 143 .Pp
 144 (in fact you can specify the option as
 145 .Fl Fl require-preauth=no ) .
 146 .Pp
 147 And there are some configuration options which do not have
 148 command-line equivalents:
 149 .Bl -tag -width "xxx" -offset indent
 150 .It Li enable-digest = Va boolean
 151 turn on support for digest processing in the KDC.
 152 The default is FALSE.
 153 .It Li check-ticket-addresses = Va boolean
 154 Check the addresses in the ticket when processing TGS requests.
 155 The default is TRUE.
 156 .It Li allow-null-ticket-addresses = Va boolean
 157 Permit tickets with no addresses.
 158 This option is only relevant when check-ticket-addresses is TRUE.
 159 .It Li allow-anonymous = Va boolean
 160 Permit anonymous tickets with no addresses.
 161 .It Li historical_anon_realm = Va boolean
 162 Enables pre-7.0 non-RFC-comformant KDC behavior.
 163 With this option set to
 164 .Li true
 165 the client realm in anonymous pkinit AS replies will be the requested realm,
 166 rather than the RFC-conformant
 167 .Li WELLKNOWN:ANONYMOUS
 168 realm.
 169 This can have a security impact on servers that expect to grant access to
 170 anonymous-but-authenticated to the KDC users of the realm in question:
 171 they would also grant access to unauthenticated anonymous users.
 172 As such, it is not recommend to set this option to
 173 .Li true.
 174 .It Li max-kdc-datagram-reply-length = Va number
 175 Maximum packet size the UDP rely that the KDC will transmit, instead
 176 the KDC sends back a reply telling the client to use TCP instead.
 177 .It Li transited-policy = Li always-check \*(Ba \
 178 Li allow-per-principal | Li always-honour-request
 179 This controls how KDC requests with the
 180 .Li disable-transited-check
 181 flag are handled. It can be one of:
 182 .Bl -tag -width "xxx" -offset indent
 183 .It Li always-check
 184 Always check transited encoding, this is the default.
 185 .It Li allow-per-principal
 186 Currently this is identical to
 187 .Li always-check .
 188 In a future release, it will be possible to mark a principal as able
 189 to handle unchecked requests.
 190 .It Li always-honour-request
 191 Always do what the client asked.
 192 In a future release, it will be possible to force a check per
 193 principal.
 194 .El
 195 .It encode_as_rep_as_tgs_rep = Va boolean
 196 Encode AS-Rep as TGS-Rep to be bug-compatible with old DCE code.
 197 The Heimdal clients allow both.
 198 .It kdc_warn_pwexpire = Va time
 199 How long before password/principal expiration the KDC should start
 200 sending out warning messages.
 201 .El
 202 .Pp
 203 The configuration file is only read when the
 204 .Nm
 205 is started.
 206 If changes made to the configuration file are to take effect, the
 207 .Nm
 208 needs to be restarted.
 209 .Pp
 210 An example of a config file:
 211 .Bd -literal -offset indent
 212 [kdc]
 213         require-preauth = no
 214 .Ed
 215 .Sh BUGS
 216 If the machine running the KDC has new addresses added to it, the KDC
 217 will have to be restarted to listen to them.
 218 The reason it doesn't just listen to wildcarded (like INADDR_ANY)
 219 addresses, is that the replies has to come from the same address they
 220 were sent to, and most OS:es doesn't pass this information to the
 221 application.
 222 If your normal mode of operation require that you add and remove
 223 addresses, the best option is probably to listen to a wildcarded TCP
 224 socket, and make sure your clients use TCP to connect.
 225 For instance, this will listen to IPv4 TCP port 88 only:
 226 .Bd -literal -offset indent
 227 kdc --addresses=0.0.0.0 --ports="88/tcp"
 228 .Ed
 229 .Pp
 230 There should be a way to specify protocol, port, and address triplets,
 231 not just addresses and protocol, port tuples.
 232 .Sh SEE ALSO
 233 .Xr kinit 1 ,
 234 .Xr krb5.conf 5,
 235 .Xr getservbyname 3