crypto/heimdal-0.6.3/lib/krb5/krb5_set_default_realm.3

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