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 65Kerberos 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 186The 187.Fn krb5_init_context 188function initializes the 189.Fa context 190structure and reads the configuration file 191.Pa /etc/krb5.conf . 192.Pp 193The structure should be freed by calling 194.Fn krb5_free_context 195when it is no longer being used. 196.Pp 197.Fn krb5_init_context 198returns 0 to indicate success. 199Otherwise an errno code is returned. 200Failure means either that something bad happened during initialization 201(typically 202.Bq ENOMEM ) 203or that Kerberos should not be used 204.Bq ENXIO . 205.Pp 206.Fn krb5_init_ets 207adds all 208.Xr com_err 3 209libs to 210.Fa context . 211This is done by 212.Fn krb5_init_context . 213.Pp 214.Fn krb5_add_et_list 215adds a 216.Xr com_err 3 217error-code handler 218.Fa func 219to the specified 220.Fa context . 221The error handler must generated by the the re-rentrant version of the 222.Xr compile_et 1 223program. 224.Fn krb5_add_extra_addresses 225add a list of addresses that should be added when requesting tickets. 226.Pp 227.Fn krb5_add_ignore_addresses 228add a list of addresses that should be ignored when requesting tickets. 229.Pp 230.Fn krb5_get_extra_addresses 231get the list of addresses that should be added when requesting tickets. 232.Pp 233.Fn krb5_get_ignore_addresses 234get the list of addresses that should be ignored when requesting tickets. 235.Pp 236.Fn krb5_set_ignore_addresses 237set the list of addresses that should be ignored when requesting tickets. 238.Pp 239.Fn krb5_set_extra_addresses 240set the list of addresses that should be added when requesting tickets. 241.Pp 242.Fn krb5_set_fcache_version 243sets the version of file credentials caches that should be used. 244.Pp 245.Fn krb5_get_fcache_version 246gets the version of file credentials caches that should be used. 247.Pp 248.Fn krb5_set_dns_canonize_hostname 249sets if the context is configured to canonicalize hostnames using DNS. 250.Pp 251.Fn krb5_get_dns_canonize_hostname 252returns if the context is configured to canonicalize hostnames using DNS. 253.Pp 254.Fn krb5_get_kdc_sec_offset 255returns the offset between the localtime and the KDC's time. 256.Fa sec 257and 258.Fa usec 259are both optional argument and 260.Dv NULL 261can be passed in. 262.Pp 263.Fn krb5_set_config_files 264set the list of configuration files to use and re-initialize the 265configuration from the files. 266.Pp 267.Fn krb5_prepend_config_files 268parse the 269.Fa filelist 270and prepend the result to the already existing list 271.Fa pq 272The result is returned in 273.Fa ret_pp 274and should be freed with 275.Fn krb5_free_config_files . 276.Pp 277.Fn krb5_prepend_config_files_default 278parse the 279.Fa filelist 280and append that to the default 281list of configuration files. 282.Pp 283.Fn krb5_get_default_config_files 284get a list of default configuration files. 285.Pp 286.Fn krb5_free_config_files 287free a list of configuration files returned by 288.Fn krb5_get_default_config_files , 289.Fn krb5_prepend_config_files_default , 290or 291.Fn krb5_prepend_config_files . 292.Pp 293.Fn krb5_set_use_admin_kdc 294sets if all KDC requests should go admin KDC. 295.Pp 296.Fn krb5_get_use_admin_kdc 297gets if all KDC requests should go admin KDC. 298.Pp 299.Fn krb5_get_max_time_skew 300and 301.Fn krb5_set_max_time_skew 302get 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 309