usr/src/man/man3gss/gss_inquire_context.3gss

   1 '\" te
   2 .\" Copyright (C) 2003, 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 GSS_INQUIRE_CONTEXT 3GSS "Jan 17, 2003"
   7 .SH NAME
   8 gss_inquire_context \- obtain information about a security context
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_inquire_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR,\fBgss_name_t *\fR\fIsrc_name\fR,
  17      \fBgss_name_t *\fR\fItarg_name\fR, \fBOM_uint32 *\fR\fIlifetime_rec\fR,
  18      \fBgss_OID *\fR\fImech_type\fR, \fBOM_uint32 *\fR\fIctx_flags\fR,
  19      \fBint *\fR\fIlocally_initiated\fR, \fBint *\fR\fIopen\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBgss_inquire_context()\fR function obtains information about a security
  26 context. The caller must already have obtained a handle that refers to the
  27 context, although the context need not be fully established.
  28 .SH PARAMETERS
  29 .sp
  30 .LP
  31 The parameter descriptions for \fBgss_inquire_context()\fR are as follows:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIminor_status\fR\fR
  36 .ad
  37 .RS 21n
  38 A mechanism-specific status code.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIcontext_handle\fR\fR
  45 .ad
  46 .RS 21n
  47 A handle that refers to the security context.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIsrc_name\fR\fR
  54 .ad
  55 .RS 21n
  56 The name of the context initiator. If the context was established using
  57 anonymous authentication, and if the application invoking
  58 \fBgss_inquire_context()\fR is the context acceptor, an anonymous name is
  59 returned.  Storage associated with this name must be freed by the application
  60 after use with a call to \fBgss_release_name()\fR. Specify \fBNULL\fR if the
  61 parameter is not required.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fItarg_name\fR\fR
  68 .ad
  69 .RS 21n
  70 The name of the context acceptor. Storage associated with this name must be
  71 freed by the application after use with a call to \fBgss_release_name()\fR. If
  72 the context acceptor did not authenticate itself, and if the initiator did not
  73 specify a target name in its call to \fBgss_init_sec_context()\fR, the value
  74 \fBGSS_C_NO_NAME\fR is returned. Specify \fBNULL\fR if the parameter is not
  75 required.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIlifetime_rec\fR\fR
  82 .ad
  83 .RS 21n
  84 The number of seconds for which the context will remain valid. If the context
  85 has expired, this parameter will be set to zero. Specify \fBNULL\fR if the
  86 parameter is not required.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fImech_type\fR\fR
  93 .ad
  94 .RS 21n
  95 The security mechanism providing the context. The returned \fBOID\fR is a
  96 pointer to static storage that should be treated as read-only by the
  97 application; in particular, the application should not attempt to free it.
  98 Specify \fBNULL\fR if the parameter is not required.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIctx_flags\fR\fR
 105 .ad
 106 .RS 21n
 107 Contains various independent flags, each of which indicates that the context
 108 supports (or is expected to support, if \fBctx_open\fR is false) a specific
 109 service option. If not needed, specify \fBNULL\fR.  Symbolic names are provided
 110 for each flag, and the symbolic names corresponding to the required flags
 111 should be logically \fBAND\fRed with the \fBret_flags\fR value to test whether
 112 a given option is supported by the context.  The flags are:
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBGSS_C_DELEG_FLAG\fR\fR
 117 .ad
 118 .RS 25n
 119 If true, credentials were delegated from the initiator to the acceptor. If
 120 false, no credentials were delegated.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBGSS_C_MUTUAL_FLAG\fR\fR
 127 .ad
 128 .RS 25n
 129 If true, the acceptor was authenticated to the initiator. If false, the
 130 acceptor did not authenticate itself.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBGSS_C_REPLAY_FLAG\fR\fR
 137 .ad
 138 .RS 25n
 139 If true, the replay of protected messages will be detected. If false, replayed
 140 messages will not be detected.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBGSS_C_SEQUENCE_FLAG\fR\fR
 147 .ad
 148 .RS 25n
 149 If true, out-of-sequence protected messages will be detected. If false,
 150 out-of-sequence messages will not be detected.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBGSS_C_CONF_FLAG\fR\fR
 157 .ad
 158 .RS 25n
 159 If true, confidential service may be invoked by calling the
 160 \fBgss_wrap\fR(3GSS) routine. If false, no confidential service is available
 161 through \fBgss_wrap()\fR. \fBgss_wrap()\fR provides message encapsulation,
 162 data-origin authentication, and integrity services only.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBGSS_C_INTEG_FLAG\fR\fR
 169 .ad
 170 .RS 25n
 171 If true, integrity service can be invoked by calling either the
 172 \fBgss_get_mic()\fR or the \fBgss_wrap()\fR routine. If false, per-message
 173 integrity service is unavailable.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBGSS_C_ANON_FLAG\fR\fR
 180 .ad
 181 .RS 25n
 182 If true, the initiator's identity is not revealed to the acceptor. The
 183 \fIsrc_name\fR parameter, if requested, contains an anonymous internal name. If
 184 false, the initiator has been authenticated normally.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBGSS_C_PROT_READY_FLAG\fR\fR
 191 .ad
 192 .RS 25n
 193 If true, the protection services, as specified by the states of the
 194 \fBGSS_C_CONF_FLAG\fR and \fBGSS_C_INTEG_FLAG\fR, are available for use. If
 195 false, they are available only if the context is fully established, that is, if
 196 the \fIopen\fR parameter is non-zero.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBGSS_C_TRANS_FLAG\fR\fR
 203 .ad
 204 .RS 25n
 205 If true, resultant security context can be transferred to other processes
 206 through a call to \fBgss_export_sec_context()\fR. If false, the security
 207 context is not transferable.
 208 .RE
 209
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fIlocally_initiated\fR\fR
 216 .ad
 217 .RS 21n
 218 Non-zero if the invoking application is the context initiator. Specify
 219 \fBNULL\fR if the parameter is not required.
 220 .RE
 221
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fIopen\fR\fR
 226 .ad
 227 .RS 21n
 228 Non-zero if the context is fully established; zero if a context-establishment
 229 token is expected from the peer application. Specify \fBNULL\fR if the
 230 parameter is not required.
 231 .RE
 232
 233 .SH ERRORS
 234 .sp
 235 .LP
 236 \fBgss_inquire_context()\fR returns one of the following status codes:
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBGSS_S_COMPLETE\fR\fR
 241 .ad
 242 .RS 20n
 243 Successful completion.
 244 .RE
 245
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fBGSS_S_NO_CONTEXT\fR\fR
 250 .ad
 251 .RS 20n
 252 The referenced context could not be accessed.
 253 .RE
 254
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fBGSS_S_FAILURE\fR\fR
 259 .ad
 260 .RS 20n
 261 The underlying mechanism detected an error for which no specific \fBGSS\fR
 262 status code is defined.  The mechanism-specific status code reported by means
 263 of the \fIminor_status\fR parameter details the error condition.
 264 .RE
 265
 266 .SH ATTRIBUTES
 267 .sp
 268 .LP
 269 See \fBattributes\fR(5)  for descriptions of the following attributes:
 270 .sp
 271
 272 .sp
 273 .TS
 274 box;
 275 c | c
 276 l | l .
 277 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 278 _
 279 MT-Level        Safe
 280 .TE
 281
 282 .SH SEE ALSO
 283 .sp
 284 .LP
 285 \fBgss_accept_sec_context\fR(3GSS), \fBgss_context_time\fR(3GSS),
 286 \fBgss_delete_sec_context\fR(3GSS), \fBgss_export_sec_context\fR(3GSS),
 287 \fBgss_import_sec_context\fR(3GSS), \fBgss_init_sec_context\fR(3GSS),
 288 \fBgss_process_context_token\fR(3GSS), \fBgss_wrap\fR(3GSS),
 289 \fBgss_wrap_size_limit\fR(3GSS), \fBattributes\fR(5)
 290 .sp
 291 .LP
 292 \fISolaris Security for Developers Guide\fR