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