crypto/external/bsd/heimdal/dist/lib/krb5/krb5_init_context.3

   1 .\"     $NetBSD: krb5_init_context.3,v 1.3 2014/04/24 13:45:34 pettai Exp $
   2 .\"
   3 .\" Copyright (c) 2001 - 2004 Kungliga Tekniska Högskolan
   4 .\" (Royal Institute of Technology, Stockholm, Sweden).
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" 3. Neither the name of the Institute nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" Id
  35 .\"
  36 .Dd December  8, 2004
  37 .Dt KRB5_CONTEXT 3
  38 .Os
  39 .Sh NAME
  40 .Nm krb5_add_et_list ,
  41 .Nm krb5_add_extra_addresses ,
  42 .Nm krb5_add_ignore_addresses ,
  43 .Nm krb5_context ,
  44 .Nm krb5_free_config_files ,
  45 .Nm krb5_free_context ,
  46 .Nm krb5_get_default_config_files ,
  47 .Nm krb5_get_dns_canonize_hostname ,
  48 .Nm krb5_get_extra_addresses ,
  49 .Nm krb5_get_fcache_version ,
  50 .Nm krb5_get_ignore_addresses ,
  51 .Nm krb5_get_kdc_sec_offset ,
  52 .Nm krb5_get_max_time_skew ,
  53 .Nm krb5_get_use_admin_kdc
  54 .Nm krb5_init_context ,
  55 .Nm krb5_init_ets ,
  56 .Nm krb5_prepend_config_files ,
  57 .Nm krb5_prepend_config_files_default ,
  58 .Nm krb5_set_config_files ,
  59 .Nm krb5_set_dns_canonize_hostname ,
  60 .Nm krb5_set_extra_addresses ,
  61 .Nm krb5_set_fcache_version ,
  62 .Nm krb5_set_ignore_addresses ,
  63 .Nm krb5_set_max_time_skew ,
  64 .Nm krb5_set_use_admin_kdc ,
  65 .Nd create, modify and delete krb5_context structures
  66 .Sh LIBRARY
  67 Kerberos 5 Library (libkrb5, -lkrb5)
  68 .Sh SYNOPSIS
  69 .In krb5/krb5.h
  70 .Pp
  71 .Li "struct krb5_context;"
  72 .Pp
  73 .Ft krb5_error_code
  74 .Fo krb5_init_context
  75 .Fa "krb5_context *context"
  76 .Fc
  77 .Ft void
  78 .Fo krb5_free_context
  79 .Fa "krb5_context context"
  80 .Fc
  81 .Ft void
  82 .Fo krb5_init_ets
  83 .Fa "krb5_context context"
  84 .Fc
  85 .Ft krb5_error_code
  86 .Fo krb5_add_et_list
  87 .Fa "krb5_context context"
  88 .Fa "void (*func)(struct et_list **)"
  89 .Fc
  90 .Ft krb5_error_code
  91 .Fo krb5_add_extra_addresses
  92 .Fa "krb5_context context"
  93 .Fa "krb5_addresses *addresses"
  94 .Fc
  95 .Ft krb5_error_code
  96 .Fo krb5_set_extra_addresses
  97 .Fa "krb5_context context"
  98 .Fa "const krb5_addresses *addresses"
  99 .Fc
 100 .Ft krb5_error_code
 101 .Fo krb5_get_extra_addresses
 102 .Fa "krb5_context context"
 103 .Fa "krb5_addresses *addresses"
 104 .Fc
 105 .Ft krb5_error_code
 106 .Fo krb5_add_ignore_addresses
 107 .Fa "krb5_context context"
 108 .Fa "krb5_addresses *addresses"
 109 .Fc
 110 .Ft krb5_error_code
 111 .Fo krb5_set_ignore_addresses
 112 .Fa "krb5_context context"
 113 .Fa "const krb5_addresses *addresses"
 114 .Fc
 115 .Ft krb5_error_code
 116 .Fo krb5_get_ignore_addresses
 117 .Fa "krb5_context context"
 118 .Fa "krb5_addresses *addresses"
 119 .Fc
 120 .Ft krb5_error_code
 121 .Fo krb5_set_fcache_version
 122 .Fa "krb5_context context"
 123 .Fa "int version"
 124 .Fc
 125 .Ft krb5_error_code
 126 .Fo krb5_get_fcache_version
 127 .Fa "krb5_context context"
 128 .Fa "int *version"
 129 .Fc
 130 .Ft void
 131 .Fo krb5_set_dns_canonize_hostname
 132 .Fa "krb5_context context"
 133 .Fa "krb5_boolean flag"
 134 .Fc
 135 .Ft krb5_boolean
 136 .Fo krb5_get_dns_canonize_hostname
 137 .Fa "krb5_context context"
 138 .Fc
 139 .Ft krb5_error_code
 140 .Fo krb5_get_kdc_sec_offset
 141 .Fa "krb5_context context"
 142 .Fa "int32_t *sec"
 143 .Fa "int32_t *usec"
 144 .Fc
 145 .Ft krb5_error_code
 146 .Fo krb5_set_config_files
 147 .Fa "krb5_context context"
 148 .Fa "char **filenames"
 149 .Fc
 150 .Ft krb5_error_code
 151 .Fo krb5_prepend_config_files
 152 .Fa "const char *filelist"
 153 .Fa "char **pq"
 154 .Fa "char ***ret_pp"
 155 .Fc
 156 .Ft krb5_error_code
 157 .Fo krb5_prepend_config_files_default
 158 .Fa "const char *filelist"
 159 .Fa "char ***pfilenames"
 160 .Fc
 161 .Ft krb5_error_code
 162 .Fo krb5_get_default_config_files
 163 .Fa "char ***pfilenames"
 164 .Fc
 165 .Ft void
 166 .Fo krb5_free_config_files
 167 .Fa "char **filenames"
 168 .Fc
 169 .Ft void
 170 .Fo krb5_set_use_admin_kdc
 171 .Fa "krb5_context context"
 172 .Fa "krb5_boolean flag"
 173 .Fc
 174 .Ft krb5_boolean
 175 .Fo krb5_get_use_admin_kdc
 176 .Fa "krb5_context context"
 177 .Fc
 178 .Ft time_t
 179 .Fo krb5_get_max_time_skew
 180 .Fa "krb5_context context"
 181 .Fc
 182 .Ft krb5_error_code
 183 .Fo krb5_set_max_time_skew
 184 .Fa "krb5_context context"
 185 .Fa "time_t time"
 186 .Fc
 187 .Sh DESCRIPTION
 188 The
 189 .Fn krb5_init_context
 190 function initializes the
 191 .Fa context
 192 structure and reads the configuration file
 193 .Pa /etc/krb5.conf .
 194 .Pp
 195 The structure should be freed by calling
 196 .Fn krb5_free_context
 197 when it is no longer being used.
 198 .Pp
 199 .Fn krb5_init_context
 200 returns 0 to indicate success.
 201 Otherwise an errno code is returned.
 202 Failure means either that something bad happened during initialization
 203 (typically
 204 .Bq ENOMEM )
 205 or that Kerberos should not be used
 206 .Bq ENXIO .
 207 .Pp
 208 .Fn krb5_init_ets
 209 adds all
 210 .Xr com_err 3
 211 libs to
 212 .Fa context .
 213 This is done by
 214 .Fn krb5_init_context .
 215 .Pp
 216 .Fn krb5_add_et_list
 217 adds a
 218 .Xr com_err 3
 219 error-code handler
 220 .Fa func
 221 to the specified
 222 .Fa context .
 223 The error handler must generated by the the re-rentrant version of the
 224 .Xr compile_et 1
 225 program.
 226 .Fn krb5_add_extra_addresses
 227 add a list of addresses that should be added when requesting tickets.
 228 .Pp
 229 .Fn krb5_add_ignore_addresses
 230 add a list of addresses that should be ignored when requesting tickets.
 231 .Pp
 232 .Fn krb5_get_extra_addresses
 233 get the list of addresses that should be added when requesting tickets.
 234 .Pp
 235 .Fn krb5_get_ignore_addresses
 236 get the list of addresses that should be ignored when requesting tickets.
 237 .Pp
 238 .Fn krb5_set_ignore_addresses
 239 set the list of addresses that should be ignored when requesting tickets.
 240 .Pp
 241 .Fn krb5_set_extra_addresses
 242 set the list of addresses that should be added when requesting tickets.
 243 .Pp
 244 .Fn krb5_set_fcache_version
 245 sets the version of file credentials caches that should be used.
 246 .Pp
 247 .Fn krb5_get_fcache_version
 248 gets the version of file credentials caches that should be used.
 249 .Pp
 250 .Fn krb5_set_dns_canonize_hostname
 251 sets if the context is configured to canonicalize hostnames using DNS.
 252 .Pp
 253 .Fn krb5_get_dns_canonize_hostname
 254 returns if the context is configured to canonicalize hostnames using DNS.
 255 .Pp
 256 .Fn krb5_get_kdc_sec_offset
 257 returns the offset between the localtime and the KDC's time.
 258 .Fa sec
 259 and
 260 .Fa usec
 261 are both optional argument and
 262 .Dv NULL
 263 can be passed in.
 264 .Pp
 265 .Fn krb5_set_config_files
 266 set the list of configuration files to use and re-initialize the
 267 configuration from the files.
 268 .Pp
 269 .Fn krb5_prepend_config_files
 270 parse the
 271 .Fa filelist
 272 and prepend the result to the already existing list
 273 .Fa pq
 274 The result is returned in
 275 .Fa ret_pp
 276 and should be freed with
 277 .Fn krb5_free_config_files .
 278 .Pp
 279 .Fn krb5_prepend_config_files_default
 280 parse the
 281 .Fa filelist
 282 and append that to the default
 283 list of configuration files.
 284 .Pp
 285 .Fn krb5_get_default_config_files
 286 get a list of default configuration files.
 287 .Pp
 288 .Fn krb5_free_config_files
 289 free a list of configuration files returned by
 290 .Fn krb5_get_default_config_files ,
 291 .Fn krb5_prepend_config_files_default ,
 292 or
 293 .Fn krb5_prepend_config_files .
 294 .Pp
 295 .Fn krb5_set_use_admin_kdc
 296 sets if all KDC requests should go admin KDC.
 297 .Pp
 298 .Fn krb5_get_use_admin_kdc
 299 gets if all KDC requests should go admin KDC.
 300 .Pp
 301 .Fn krb5_get_max_time_skew
 302 and
 303 .Fn krb5_set_max_time_skew
 304 get and sets the maximum allowed time skew between client and server.
 305 .Sh SEE ALSO
 306 .Xr errno 2 ,
 307 .Xr krb5 3 ,
 308 .Xr krb5_config 3 ,
 309 .Xr krb5_context 3 ,
 310 .Xr kerberos 8