crypto/external/bsd/heimdal/dist/lib/krb5/krb5_set_default_realm.3

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