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