share/man/man5/krb5envvar.5

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KRB5ENVVAR 5 "Feb 13, 2008"
   7 .SH NAME
   8 krb5envvar \- Kerberos environment variables
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 The Kerberos mechanism provides a number of environment variables to configure
  13 different behavior in order to meet applications' needs. Environment variables
  14 used within the Kerberos mechanism are:
  15 .sp
  16 .ne 2
  17 .na
  18 \fB\fBKRB5_KTNAME\fR\fR
  19 .ad
  20 .sp .6
  21 .RS 4n
  22 Used by the mechanism to specify the location of the key table file. The
  23 variable can be set to the following value:
  24 .sp
  25 .in +2
  26 .nf
  27 [[\fI<kt type>\fR:]\fI<file name>\fR]
  28 .fi
  29 .in -2
  30
  31 where \fI<kt type>\fR can be \fBFILE\fR or \fBWRFILE\fR. \fBFILE\fR is for read
  32 operations; \fBWRFILE\fR is for write operations. \fI<file name>\fR is the
  33 location of the \fBkeytab\fR file.
  34 .sp
  35 r
  36 .sp
  37 If \fBKRB5_KTNAME\fR is not defined, the default value is:
  38 .sp
  39 .in +2
  40 .nf
  41 FILE:/etc/krb5/krb5.keytab
  42 .fi
  43 .in -2
  44
  45 The \fBkeytab\fR file is used to store credentials persistently and is used
  46 commonly for service daemons.
  47 .sp
  48 Specifying the \fBFILE\fR type assumes that the subsequent operations on the
  49 associated file are readable by the invoking process. Care must be taken to
  50 ensure that the file is readable only by the set of principals that need to
  51 retrieve their unencrypted keys.
  52 .sp
  53 The \fBWRFILE\fR type is used by the \fBkadmin\fR(8) command. Specifying this
  54 type allows the administrator to designate an alternate \fBkeytab\fR file to
  55 write to without using extra command line arguments for file location.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBKRB5CCNAME\fR\fR
  62 .ad
  63 .sp .6
  64 .RS 4n
  65 Used by the mechanism to specify the location of the credential cache. The
  66 variable can be set to the following value:
  67 .sp
  68 .in +2
  69 .nf
  70 [[\fI<cc type>\fR:]\fI<file name>\fR]
  71 .fi
  72 .in -2
  73
  74 where \fI<cc type>\fR can be \fBFILE\fR or \fBMEMORY\fR. \fI<file name>\fR is
  75 the location of the principal's credential cache.
  76 .sp
  77 If \fBKRB5CCNAME\fR is not defined, the default value is:
  78 .sp
  79 .in +2
  80 .nf
  81 FILE:/tmp/krb5cc_\fI<uid>\fR
  82 .fi
  83 .in -2
  84
  85 where \fI<uid>\fR is the user id of the process that created the cache file.
  86 .sp
  87 The credential cache file is used to store tickets that have been granted to
  88 the principal.
  89 .sp
  90 Specifying the \fBFILE\fR types assumes that subsequent operations on the
  91 associated file are readable and writable by the invoking process. Care must be
  92 taken to ensure that the file is accessible only by the set of principals that
  93 need to access their credentials. If the credential file is in a directory to
  94 which other users have write access, you need to set that directory's sticky
  95 bit (see \fBchmod\fR(1)).
  96 .sp
  97 The \fBMEMORY\fR credential cache type is used only in special cases, such as
  98 when making a temporary cache for the life of the invoking process.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBKRB5RCNAME\fR\fR
 105 .ad
 106 .sp .6
 107 .RS 4n
 108 Used by the mechanism to specify the type and location of the replay cache. The
 109 variable can be set to the following value:
 110 .sp
 111 .in +2
 112 .nf
 113 [[\fI<rc type>\fR:]\fI<file name>\fR]
 114 .fi
 115 .in -2
 116
 117 where \fI<rc type>\fR can be either \fBFILE\fR, \fBMEMORY\fR, or \fBNONE\fR.
 118 \fI<file name>\fR is relevant only when specifying the replay cache file type.
 119 .sp
 120 If not defined, the default value is:
 121 .sp
 122 .in +2
 123 .nf
 124 FILE:/var/krb5/rcache/root/rc_\fI<service>\fR
 125 .fi
 126 .in -2
 127
 128 \&...if the process is owned by root, or:
 129 .sp
 130 .in +2
 131 .nf
 132 FILE:/var/krb5/rcache/rc_\fI<service>\fR
 133 .fi
 134 .in -2
 135
 136 \&...if the process is owned by a user other than root. \fI<service>\fR is the
 137 service process name associated with the replay cache file.
 138 .sp
 139 The replay cache is used by Kerberos to detect the replay of authentication
 140 data. This prevents people who capture authentication messages on the network
 141 from authenticating to the server by resending these messages.
 142 .sp
 143 When specifying the \fBFILE\fR replay cache type, care must be taken to prevent
 144 the replay cache file from being deleted by another user. Make sure that every
 145 directory in the replay cache path is either writable only by the owner of the
 146 replay cache or that the sticky bit ("\fBt\fR") is set on every directory in
 147 the replay cache path to which others have write permission.
 148 .sp
 149 When specifying the \fBMEMORY\fR replay cache type you need to weigh the
 150 trade-off of performance against the slight security risk created by using a
 151 non-persistent cache. The risk occurs during system reboots when the following
 152 condition obtains:
 153 .RS +4
 154 .TP
 155 .ie t \(bu
 156 .el o
 157 The duration from the last write to the replay cache before reboot to the point
 158 when the Kerberized server applications are running is less than the Kerberos
 159 clockskew (see \fBkrb5.conf\fR(4)).
 160 .RE
 161 When specifying the \fBNONE\fR replay cache time you need to understand that
 162 this disables the replay cache, and all security risks that this presents. This
 163 includes all the risks outlined in this section of the man page.
 164 .sp
 165 Under this condition, the server applications can accept a replay of Kerberos
 166 authentication data (up to the difference between the time of the last write
 167 and the clockskew). Typically, this is a small window of time. If the server
 168 applications take longer than the clockskew to start accepting connections
 169 there is no replay risk.
 170 .sp
 171 The risk described above is the same when using \fBFILE\fR replay cache types
 172 when the replay cache resides on swap file systems, such as \fB/tmp\fR and
 173 \fB/var/run\fR.
 174 .sp
 175 The performance improvement in \fBMEMORY\fR replay cache types over \fBFILE\fR
 176 types is derived from the absence of disk I/O. This is true even if the
 177 \fBFILE\fR replay cache is on a memory-backed file system, such as swap
 178 (\fB/tmp\fR and \fB/var/run\fR).
 179 .sp
 180 Note that \fBMEMORY\fR-type caches are per-process caches,  therefore use of
 181 these types of caches must be carefully considered. One  example of where
 182 \fBMEMORY\fR-type caches can be problematic  is when an application uses  more
 183 than one process for establishing security contexts. In such a case, memory
 184 replay caches are not shared across the processes, thus  allowing potential for
 185 replay attacks.
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fBKRB5_CONFIG\fR
 192 .ad
 193 .sp .6
 194 .RS 4n
 195 Allows you to change the default location of the \fB/etc/krb5/krb5.conf\fR file
 196 to enable the Kerberos library code to read configuration parameters from
 197 another file specified by KRB5_CONFIG. For example (using kinit from
 198 \fBksh\fR(1)):
 199 .sp
 200 .in +2
 201 .nf
 202  KRB5_CONFIG=/var/tmp/krb5.conf kinit
 203 .fi
 204 .in -2
 205
 206 .RE
 207
 208 .SH ATTRIBUTES
 209 .sp
 210 .LP
 211 See \fBattributes\fR(5) for a description of the following attributes:
 212 .sp
 213
 214 .sp
 215 .TS
 216 box;
 217 c | c
 218 l | l .
 219 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 220 _
 221 Interface Stability     Uncommitted
 222 .TE
 223
 224 .SH SEE ALSO
 225 .sp
 226 .LP
 227 \fBchmod\fR(1), \fBkinit\fR(1), \fBklist\fR(1), \fBksh\fR(1), \fBkadmin\fR(8),
 228 \fBkadmind\fR(8), \fBkrb5.conf\fR(4), \fBattributes\fR(5), \fBkerberos\fR(5)