'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH GSS_INQUIRE_CONTEXT 3GSS "Jan 17, 2003"
.SH NAME
gss_inquire_context \- obtain information about a security context
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_inquire_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR,\fBgss_name_t *\fR\fIsrc_name\fR,
     \fBgss_name_t *\fR\fItarg_name\fR, \fBOM_uint32 *\fR\fIlifetime_rec\fR,
     \fBgss_OID *\fR\fImech_type\fR, \fBOM_uint32 *\fR\fIctx_flags\fR,
     \fBint *\fR\fIlocally_initiated\fR, \fBint *\fR\fIopen\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgss_inquire_context()\fR function obtains information about a security
context. The caller must already have obtained a handle that refers to the
context, although the context need not be fully established.
.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_inquire_context()\fR are as follows:
.sp
.ne 2
.na
\fB\fIminor_status\fR\fR
.ad
.RS 21n
A mechanism-specific status code.
.RE

.sp
.ne 2
.na
\fB\fIcontext_handle\fR\fR
.ad
.RS 21n
A handle that refers to the security context.
.RE

.sp
.ne 2
.na
\fB\fIsrc_name\fR\fR
.ad
.RS 21n
The name of the context initiator. If the context was established using
anonymous authentication, and if the application invoking
\fBgss_inquire_context()\fR is the context acceptor, an anonymous name is
returned.  Storage associated with this name must be freed by the application
after use with a call to \fBgss_release_name()\fR. Specify \fBNULL\fR if the
parameter is not required.
.RE

.sp
.ne 2
.na
\fB\fItarg_name\fR\fR
.ad
.RS 21n
The name of the context acceptor. Storage associated with this name must be
freed by the application after use with a call to \fBgss_release_name()\fR. If
the context acceptor did not authenticate itself, and if the initiator did not
specify a target name in its call to \fBgss_init_sec_context()\fR, the value
\fBGSS_C_NO_NAME\fR is returned. Specify \fBNULL\fR if the parameter is not
required.
.RE

.sp
.ne 2
.na
\fB\fIlifetime_rec\fR\fR
.ad
.RS 21n
The number of seconds for which the context will remain valid. If the context
has expired, this parameter will be set to zero. Specify \fBNULL\fR if the
parameter is not required.
.RE

.sp
.ne 2
.na
\fB\fImech_type\fR\fR
.ad
.RS 21n
The security mechanism providing the context. The returned \fBOID\fR is a
pointer to static storage that should be treated as read-only by the
application; in particular, the application should not attempt to free it.
Specify \fBNULL\fR if the parameter is not required.
.RE

.sp
.ne 2
.na
\fB\fIctx_flags\fR\fR
.ad
.RS 21n
Contains various independent flags, each of which indicates that the context
supports (or is expected to support, if \fBctx_open\fR is false) a specific
service option. If not needed, specify \fBNULL\fR.  Symbolic names are provided
for each flag, and the symbolic names corresponding to the required flags
should be logically \fBAND\fRed with the \fBret_flags\fR value to test whether
a given option is supported by the context.  The flags are:
.sp
.ne 2
.na
\fB\fBGSS_C_DELEG_FLAG\fR\fR
.ad
.RS 25n
If true, credentials were delegated from the initiator to the acceptor. If
false, no credentials were delegated.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_MUTUAL_FLAG\fR\fR
.ad
.RS 25n
If true, the acceptor was authenticated to the initiator. If false, the
acceptor did not authenticate itself.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_REPLAY_FLAG\fR\fR
.ad
.RS 25n
If true, the replay of protected messages will be detected. If false, replayed
messages will not be detected.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_SEQUENCE_FLAG\fR\fR
.ad
.RS 25n
If true, out-of-sequence protected messages will be detected. If false,
out-of-sequence messages will not be detected.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_CONF_FLAG\fR\fR
.ad
.RS 25n
If true, confidential service may be invoked by calling the
\fBgss_wrap\fR(3GSS) routine. If false, no confidential service is available
through \fBgss_wrap()\fR. \fBgss_wrap()\fR provides message encapsulation,
data-origin authentication, and integrity services only.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_INTEG_FLAG\fR\fR
.ad
.RS 25n
If true, integrity service can be invoked by calling either the
\fBgss_get_mic()\fR or the \fBgss_wrap()\fR routine. If false, per-message
integrity service is unavailable.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_ANON_FLAG\fR\fR
.ad
.RS 25n
If true, the initiator's identity is not revealed to the acceptor. The
\fIsrc_name\fR parameter, if requested, contains an anonymous internal name. If
false, the initiator has been authenticated normally.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_PROT_READY_FLAG\fR\fR
.ad
.RS 25n
If true, the protection services, as specified by the states of the
\fBGSS_C_CONF_FLAG\fR and \fBGSS_C_INTEG_FLAG\fR, are available for use. If
false, they are available only if the context is fully established, that is, if
the \fIopen\fR parameter is non-zero.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_TRANS_FLAG\fR\fR
.ad
.RS 25n
If true, resultant security context can be transferred to other processes
through a call to \fBgss_export_sec_context()\fR. If false, the security
context is not transferable.
.RE

.RE

.sp
.ne 2
.na
\fB\fIlocally_initiated\fR\fR
.ad
.RS 21n
Non-zero if the invoking application is the context initiator. Specify
\fBNULL\fR if the parameter is not required.
.RE

.sp
.ne 2
.na
\fB\fIopen\fR\fR
.ad
.RS 21n
Non-zero if the context is fully established; zero if a context-establishment
token is expected from the peer application. Specify \fBNULL\fR if the
parameter is not required.
.RE

.SH ERRORS
.sp
.LP
\fBgss_inquire_context()\fR returns one of the following status codes:
.sp
.ne 2
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 20n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_NO_CONTEXT\fR\fR
.ad
.RS 20n
The referenced context could not be accessed.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 20n
The underlying mechanism detected an error for which no specific \fBGSS\fR
status code is defined.  The mechanism-specific status code reported by means
of the \fIminor_status\fR parameter details the error condition.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5)  for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBgss_accept_sec_context\fR(3GSS), \fBgss_context_time\fR(3GSS),
\fBgss_delete_sec_context\fR(3GSS), \fBgss_export_sec_context\fR(3GSS),
\fBgss_import_sec_context\fR(3GSS), \fBgss_init_sec_context\fR(3GSS),
\fBgss_process_context_token\fR(3GSS), \fBgss_wrap\fR(3GSS),
\fBgss_wrap_size_limit\fR(3GSS), \fBattributes\fR(5)
.sp
.LP
\fISolaris Security for Developers Guide\fR