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