1.\" Copyright (c) 2003 - 2005 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 April 24, 2005 35.Dt KRB5_SET_DEFAULT_REALM 3 36.Os HEIMDAL 37.Sh NAME 38.Nm krb5_copy_host_realm , 39.Nm krb5_free_host_realm , 40.Nm krb5_get_default_realm , 41.Nm krb5_get_default_realms , 42.Nm krb5_get_host_realm , 43.Nm krb5_set_default_realm 44.Nd default and host realm read and manipulation routines 45.Sh LIBRARY 46Kerberos 5 Library (libkrb5, -lkrb5) 47.Sh SYNOPSIS 48.In krb5.h 49.Ft krb5_error_code 50.Fo krb5_copy_host_realm 51.Fa "krb5_context context" 52.Fa "const krb5_realm *from" 53.Fa "krb5_realm **to" 54.Fc 55.Ft krb5_error_code 56.Fo krb5_free_host_realm 57.Fa "krb5_context context" 58.Fa "krb5_realm *realmlist" 59.Fc 60.Ft krb5_error_code 61.Fo krb5_get_default_realm 62.Fa "krb5_context context" 63.Fa "krb5_realm *realm" 64.Fc 65.Ft krb5_error_code 66.Fo krb5_get_default_realms 67.Fa "krb5_context context" 68.Fa "krb5_realm **realm" 69.Fc 70.Ft krb5_error_code 71.Fo krb5_get_host_realm 72.Fa "krb5_context context" 73.Fa "const char *host" 74.Fa "krb5_realm **realms" 75.Fc 76.Ft krb5_error_code 77.Fo krb5_set_default_realm 78.Fa "krb5_context context" 79.Fa "const char *realm" 80.Fc 81.Sh DESCRIPTION 82.Fn krb5_copy_host_realm 83copies the list of realms from 84.Fa from 85to 86.Fa to . 87.Fa to 88should be freed by the caller using 89.Fa krb5_free_host_realm . 90.Pp 91.Fn krb5_free_host_realm 92frees all memory allocated by 93.Fa realmlist . 94.Pp 95.Fn krb5_get_default_realm 96returns the first default realm for this host. 97The realm returned should be freed with 98.Fn free . 99.Pp 100.Fn krb5_get_default_realms 101returns a 102.Dv NULL 103terminated list of default realms for this context. 104Realms returned by 105.Fn krb5_get_default_realms 106should be freed with 107.Fn krb5_free_host_realm . 108.Pp 109.Fn krb5_get_host_realm 110returns a 111.Dv NULL 112terminated list of realms for 113.Fa host 114by looking up the information in the 115.Li [domain_realm] 116in 117.Pa krb5.conf 118or in 119.Li DNS . 120If the mapping in 121.Li [domain_realm] 122results in the string 123.Li dns_locate , 124DNS is used to lookup the realm. 125.Pp 126When using 127.Li DNS 128to a resolve the domain for the host a.b.c, 129.Fn krb5_get_host_realm 130looks for a 131.Dv TXT 132resource record named 133.Li _kerberos.a.b.c , 134and if not found, it strips off the first component and tries a again 135(_kerberos.b.c) until it reaches the root. 136.Pp 137If there is no configuration or DNS information found, 138.Fn krb5_get_host_realm 139assumes it can use the domain part of the 140.Fa host 141to form a realm. 142Caller must free 143.Fa realmlist 144with 145.Fn krb5_free_host_realm . 146.Pp 147.Fn krb5_set_default_realm 148sets the default realm for the 149.Fa context . 150If 151.Dv NULL 152is used as a 153.Fa realm , 154the 155.Li [libdefaults]default_realm 156stanza in 157.Pa krb5.conf 158is used. 159If there is no such stanza in the configuration file, the 160.Fn krb5_get_host_realm 161function is used to form a default realm. 162.Sh SEE ALSO 163.Xr free 3 , 164.Xr krb5.conf 5 165