lib/krb5/krb5_set_default_realm.3

   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
  46 Kerberos 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
  83 copies the list of realms from
  84 .Fa from
  85 to
  86 .Fa to .
  87 .Fa to
  88 should be freed by the caller using
  89 .Fa krb5_free_host_realm .
  90 .Pp
  91 .Fn krb5_free_host_realm
  92 frees all memory allocated by
  93 .Fa realmlist .
  94 .Pp
  95 .Fn krb5_get_default_realm
  96 returns the first default realm for this host.
  97 The realm returned should be freed with
  98 .Fn krb5_xfree .
  99 .Pp
 100 .Fn krb5_get_default_realms
 101 returns a
 102 .Dv NULL
 103 terminated list of default realms for this context.
 104 Realms returned by
 105 .Fn krb5_get_default_realms
 106 should be freed with
 107 .Fn krb5_free_host_realm .
 108 .Pp
 109 .Fn krb5_get_host_realm
 110 returns a
 111 .Dv NULL
 112 terminated list of realms for
 113 .Fa host
 114 by looking up the information in the
 115 .Li [domain_realm]
 116 in
 117 .Pa krb5.conf
 118 or in
 119 .Li DNS .
 120 If the mapping in
 121 .Li [domain_realm]
 122 results in the string
 123 .Li dns_locate ,
 124 DNS is used to lookup the realm.
 125 .Pp
 126 When using
 127 .Li DNS
 128 to a resolve the domain for the host a.b.c,
 129 .Fn krb5_get_host_realm
 130 looks for a
 131 .Dv TXT
 132 resource record named
 133 .Li _kerberos.a.b.c ,
 134 and if not found, it strips off the first component and tries a again
 135 (_kerberos.b.c) until it reaches the root.
 136 .Pp
 137 If there is no configuration or DNS information found,
 138 .Fn krb5_get_host_realm
 139 assumes it can use the domain part of the
 140 .Fa host
 141 to form a realm.
 142 Caller must free
 143 .Fa realmlist
 144 with
 145 .Fn krb5_free_host_realm .
 146 .Pp
 147 .Fn krb5_set_default_realm
 148 sets the default realm for the
 149 .Fa context .
 150 If
 151 .Dv NULL
 152 is used as a
 153 .Fa realm ,
 154 the
 155 .Li [libdefaults]default_realm
 156 stanza in
 157 .Pa krb5.conf
 158 is used.
 159 If there is no such stanza in the configuration file, the
 160 .Fn krb5_get_host_realm
 161 function is used to form a default realm.
 162 .Sh SEE ALSO
 163 .Xr free 3 ,
 164 .Xr krb5.conf 5