'\" te

.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

.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

\fI\fR