'\" 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 "17 Jan 2003" "SunOS 5.11" "Generic Security Services API Library Functions"
.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
.mk
.na
\fB\fIminor_status\fR\fR
.ad
.RS 21n
.rt  
A mechanism-specific status code.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fIsrc_name\fR\fR
.ad
.RS 21n
.rt  
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
.mk
.na
\fB\fItarg_name\fR\fR
.ad
.RS 21n
.rt  
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
.mk
.na
\fB\fIlifetime_rec\fR\fR
.ad
.RS 21n
.rt  
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
.mk
.na
\fB\fImech_type\fR\fR
.ad
.RS 21n
.rt  
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
.mk
.na
\fB\fIctx_flags\fR\fR
.ad
.RS 21n
.rt  
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
.mk
.na
\fB\fBGSS_C_DELEG_FLAG\fR\fR
.ad
.RS 25n
.rt  
If true, credentials were delegated from the initiator to the acceptor. If
false, no credentials were delegated.
.RE

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

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

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

.sp
.ne 2
.mk
.na
\fB\fBGSS_C_CONF_FLAG\fR\fR
.ad
.RS 25n
.rt  
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
.mk
.na
\fB\fBGSS_C_INTEG_FLAG\fR\fR
.ad
.RS 25n
.rt  
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
.mk
.na
\fB\fBGSS_C_ANON_FLAG\fR\fR
.ad
.RS 25n
.rt  
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
.mk
.na
\fB\fBGSS_C_PROT_READY_FLAG\fR\fR
.ad
.RS 25n
.rt  
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
.mk
.na
\fB\fBGSS_C_TRANS_FLAG\fR\fR
.ad
.RS 25n
.rt  
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
.mk
.na
\fB\fIlocally_initiated\fR\fR
.ad
.RS 21n
.rt  
Non-zero if the invoking application is the context initiator. Specify
\fBNULL\fR if the parameter is not required.
.RE

.sp
.ne 2
.mk
.na
\fB\fIopen\fR\fR
.ad
.RS 21n
.rt  
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
.mk
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 20n
.rt  
Successful completion.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 20n
.rt  
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
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.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