crypto/heimdal/lib/krb5/krb5_init_context.3

   1 .\" Copyright (c) 2001 - 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 December  8, 2004
  35 .Dt KRB5_CONTEXT 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_add_et_list ,
  39 .Nm krb5_add_extra_addresses ,
  40 .Nm krb5_add_ignore_addresses ,
  41 .Nm krb5_context ,
  42 .Nm krb5_free_config_files ,
  43 .Nm krb5_free_context ,
  44 .Nm krb5_get_default_config_files ,
  45 .Nm krb5_get_dns_canonize_hostname ,
  46 .Nm krb5_get_extra_addresses ,
  47 .Nm krb5_get_fcache_version ,
  48 .Nm krb5_get_ignore_addresses ,
  49 .Nm krb5_get_kdc_sec_offset ,
  50 .Nm krb5_get_max_time_skew ,
  51 .Nm krb5_get_use_admin_kdc
  52 .Nm krb5_init_context ,
  53 .Nm krb5_init_ets ,
  54 .Nm krb5_prepend_config_files ,
  55 .Nm krb5_prepend_config_files_default ,
  56 .Nm krb5_set_config_files ,
  57 .Nm krb5_set_dns_canonize_hostname ,
  58 .Nm krb5_set_extra_addresses ,
  59 .Nm krb5_set_fcache_version ,
  60 .Nm krb5_set_ignore_addresses ,
  61 .Nm krb5_set_max_time_skew ,
  62 .Nm krb5_set_use_admin_kdc ,
  63 .Nd create, modify and delete krb5_context structures
  64 .Sh LIBRARY
  65 Kerberos 5 Library (libkrb5, -lkrb5)
  66 .Sh SYNOPSIS
  67 .In krb5.h
  68 .Pp
  69 .Li "struct krb5_context;"
  70 .Pp
  71 .Ft krb5_error_code
  72 .Fo krb5_init_context
  73 .Fa "krb5_context *context"
  74 .Fc
  75 .Ft void
  76 .Fo krb5_free_context
  77 .Fa "krb5_context context"
  78 .Fc
  79 .Ft void
  80 .Fo krb5_init_ets
  81 .Fa "krb5_context context"
  82 .Fc
  83 .Ft krb5_error_code
  84 .Fo krb5_add_et_list
  85 .Fa "krb5_context context"
  86 .Fa "void (*func)(struct et_list **)"
  87 .Fc
  88 .Ft krb5_error_code
  89 .Fo krb5_add_extra_addresses
  90 .Fa "krb5_context context"
  91 .Fa "krb5_addresses *addresses"
  92 .Fc
  93 .Ft krb5_error_code
  94 .Fo krb5_set_extra_addresses
  95 .Fa "krb5_context context"
  96 .Fa "const krb5_addresses *addresses"
  97 .Fc
  98 .Ft krb5_error_code
  99 .Fo krb5_get_extra_addresses
 100 .Fa "krb5_context context"
 101 .Fa "krb5_addresses *addresses"
 102 .Fc
 103 .Ft krb5_error_code
 104 .Fo krb5_add_ignore_addresses
 105 .Fa "krb5_context context"
 106 .Fa "krb5_addresses *addresses"
 107 .Fc
 108 .Ft krb5_error_code
 109 .Fo krb5_set_ignore_addresses
 110 .Fa "krb5_context context"
 111 .Fa "const krb5_addresses *addresses"
 112 .Fc
 113 .Ft krb5_error_code
 114 .Fo krb5_get_ignore_addresses
 115 .Fa "krb5_context context"
 116 .Fa "krb5_addresses *addresses"
 117 .Fc
 118 .Ft krb5_error_code
 119 .Fo krb5_set_fcache_version
 120 .Fa "krb5_context context"
 121 .Fa "int version"
 122 .Fc
 123 .Ft krb5_error_code
 124 .Fo krb5_get_fcache_version
 125 .Fa "krb5_context context"
 126 .Fa "int *version"
 127 .Fc
 128 .Ft void
 129 .Fo krb5_set_dns_canonize_hostname
 130 .Fa "krb5_context context"
 131 .Fa "krb5_boolean flag"
 132 .Fc
 133 .Ft krb5_boolean
 134 .Fo krb5_get_dns_canonize_hostname
 135 .Fa "krb5_context context"
 136 .Fc
 137 .Ft krb5_error_code
 138 .Fo krb5_get_kdc_sec_offset
 139 .Fa "krb5_context context"
 140 .Fa "int32_t *sec"
 141 .Fa "int32_t *usec"
 142 .Fc
 143 .Ft krb5_error_code
 144 .Fo krb5_set_config_files
 145 .Fa "krb5_context context"
 146 .Fa "char **filenames"
 147 .Fc
 148 .Ft krb5_error_code
 149 .Fo krb5_prepend_config_files
 150 .Fa "const char *filelist"
 151 .Fa "char **pq"
 152 .Fa "char ***ret_pp"
 153 .Fc
 154 .Ft krb5_error_code
 155 .Fo krb5_prepend_config_files_default
 156 .Fa "const char *filelist"
 157 .Fa "char ***pfilenames"
 158 .Fc
 159 .Ft krb5_error_code
 160 .Fo krb5_get_default_config_files
 161 .Fa "char ***pfilenames"
 162 .Fc
 163 .Ft void
 164 .Fo krb5_free_config_files
 165 .Fa "char **filenames"
 166 .Fc
 167 .Ft void
 168 .Fo krb5_set_use_admin_kdc
 169 .Fa "krb5_context context"
 170 .Fa "krb5_boolean flag"
 171 .Fc
 172 .Ft krb5_boolean
 173 .Fo krb5_get_use_admin_kdc
 174 .Fa "krb5_context context"
 175 .Fc
 176 .Ft time_t
 177 .Fo krb5_get_max_time_skew
 178 .Fa "krb5_context context"
 179 .Fc
 180 .Ft krb5_error_code
 181 .Fo krb5_set_max_time_skew
 182 .Fa "krb5_context context"
 183 .Fa "time_t time"
 184 .Fc
 185 .Sh DESCRIPTION
 186 The
 187 .Fn krb5_init_context
 188 function initializes the
 189 .Fa context
 190 structure and reads the configuration file
 191 .Pa /etc/krb5.conf .
 192 .Pp
 193 The structure should be freed by calling
 194 .Fn krb5_free_context
 195 when it is no longer being used.
 196 .Pp
 197 .Fn krb5_init_context
 198 returns 0 to indicate success.
 199 Otherwise an errno code is returned.
 200 Failure means either that something bad happened during initialization
 201 (typically
 202 .Bq ENOMEM )
 203 or that Kerberos should not be used
 204 .Bq ENXIO .
 205 .Pp
 206 .Fn krb5_init_ets
 207 adds all
 208 .Xr com_err 3
 209 libs to
 210 .Fa context .
 211 This is done by
 212 .Fn krb5_init_context .
 213 .Pp
 214 .Fn krb5_add_et_list
 215 adds a
 216 .Xr com_err 3
 217 error-code handler
 218 .Fa func
 219 to the specified
 220 .Fa context .
 221 The error handler must generated by the the re-rentrant version of the
 222 .Xr compile_et 1
 223 program.
 224 .Fn krb5_add_extra_addresses
 225 add a list of addresses that should be added when requesting tickets.
 226 .Pp
 227 .Fn krb5_add_ignore_addresses
 228 add a list of addresses that should be ignored when requesting tickets.
 229 .Pp
 230 .Fn krb5_get_extra_addresses
 231 get the list of addresses that should be added when requesting tickets.
 232 .Pp
 233 .Fn krb5_get_ignore_addresses
 234 get the list of addresses that should be ignored when requesting tickets.
 235 .Pp
 236 .Fn krb5_set_ignore_addresses
 237 set the list of addresses that should be ignored when requesting tickets.
 238 .Pp
 239 .Fn krb5_set_extra_addresses
 240 set the list of addresses that should be added when requesting tickets.
 241 .Pp
 242 .Fn krb5_set_fcache_version
 243 sets the version of file credentials caches that should be used.
 244 .Pp
 245 .Fn krb5_get_fcache_version
 246 gets the version of file credentials caches that should be used.
 247 .Pp
 248 .Fn krb5_set_dns_canonize_hostname
 249 sets if the context is configured to canonicalize hostnames using DNS.
 250 .Pp
 251 .Fn krb5_get_dns_canonize_hostname
 252 returns if the context is configured to canonicalize hostnames using DNS.
 253 .Pp
 254 .Fn krb5_get_kdc_sec_offset
 255 returns the offset between the localtime and the KDC's time.
 256 .Fa sec
 257 and
 258 .Fa usec
 259 are both optional argument and
 260 .Dv NULL
 261 can be passed in.
 262 .Pp
 263 .Fn krb5_set_config_files
 264 set the list of configuration files to use and re-initialize the
 265 configuration from the files.
 266 .Pp
 267 .Fn krb5_prepend_config_files
 268 parse the
 269 .Fa filelist
 270 and prepend the result to the already existing list
 271 .Fa pq
 272 The result is returned in
 273 .Fa ret_pp
 274 and should be freed with
 275 .Fn krb5_free_config_files .
 276 .Pp
 277 .Fn krb5_prepend_config_files_default
 278 parse the
 279 .Fa filelist
 280 and append that to the default
 281 list of configuration files.
 282 .Pp
 283 .Fn krb5_get_default_config_files
 284 get a list of default configuration files.
 285 .Pp
 286 .Fn krb5_free_config_files
 287 free a list of configuration files returned by
 288 .Fn krb5_get_default_config_files ,
 289 .Fn krb5_prepend_config_files_default ,
 290 or
 291 .Fn krb5_prepend_config_files .
 292 .Pp
 293 .Fn krb5_set_use_admin_kdc
 294 sets if all KDC requests should go admin KDC.
 295 .Pp
 296 .Fn krb5_get_use_admin_kdc
 297 gets if all KDC requests should go admin KDC.
 298 .Pp
 299 .Fn krb5_get_max_time_skew
 300 and
 301 .Fn krb5_set_max_time_skew
 302 get and sets the maximum allowed time skew between client and server.
 303 .Sh SEE ALSO
 304 .Xr errno 2 ,
 305 .Xr krb5 3 ,
 306 .Xr krb5_config 3 ,
 307 .Xr krb5_context 3 ,
 308 .Xr kerberos 8