Tribblix: manual page: gss_inquire

GSS_INQUIRE_CONTEXT(3GSS) Generic Security Services API Library Functions

NAME

gss_inquire_context - obtain information about a security context

SYNOPSIS

cc [ flag... ] file... -lgss [ library... ]
#include <gssapi/gssapi.h>

OM_uint32 gss_inquire_context(OM_uint32 *minor_status,
const gss_ctx_id_t context_handle,gss_name_t *src_name,
gss_name_t *targ_name, OM_uint32 *lifetime_rec,
gss_OID *mech_type, OM_uint32 *ctx_flags,
int *locally_initiated, int *open);

DESCRIPTION

The gss_inquire_context() 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.

PARAMETERS

The parameter descriptions for gss_inquire_context() are as follows:

minor_status
A mechanism-specific status code.

context_handle
A handle that refers to the security context.

src_name
The name of the context initiator. If the
context was established using anonymous
authentication, and if the application invoking
gss_inquire_context() 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
gss_release_name(). Specify NULL if the
parameter is not required.

targ_name
The name of the context acceptor. Storage
associated with this name must be freed by the
application after use with a call to
gss_release_name(). If the context acceptor did
not authenticate itself, and if the initiator
did not specify a target name in its call to
gss_init_sec_context(), the value GSS_C_NO_NAME
is returned. Specify NULL if the parameter is
not required.

lifetime_rec
The number of seconds for which the context will
remain valid. If the context has expired, this
parameter will be set to zero. Specify NULL if
the parameter is not required.

mech_type
The security mechanism providing the context.
The returned OID 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 NULL if
the parameter is not required.

ctx_flags
Contains various independent flags, each of
which indicates that the context supports (or is
expected to support, if ctx_open is false) a
specific service option. If not needed, specify
NULL. Symbolic names are provided for each
flag, and the symbolic names corresponding to
the required flags should be logically ANDed
with the ret_flags value to test whether a given
option is supported by the context. The flags
are:

GSS_C_DELEG_FLAG
If true, credentials
were delegated from the
initiator to the
acceptor. If false, no
credentials were
delegated.

GSS_C_MUTUAL_FLAG
If true, the acceptor
was authenticated to
the initiator. If
false, the acceptor did
not authenticate
itself.

GSS_C_REPLAY_FLAG
If true, the replay of
protected messages will
be detected. If false,
replayed messages will
not be detected.

GSS_C_SEQUENCE_FLAG
If true, out-of-
sequence protected
messages will be
detected. If false,
out-of-sequence
messages will not be
detected.

GSS_C_CONF_FLAG
If true, confidential
service may be invoked
by calling the
gss_wrap(3GSS) routine.
If false, no
confidential service is
available through
gss_wrap(). gss_wrap()
provides message
encapsulation, data-
origin authentication,
and integrity services
only.

GSS_C_INTEG_FLAG
If true, integrity
service can be invoked
by calling either the
gss_get_mic() or the
gss_wrap() routine. If
false, per-message
integrity service is
unavailable.

GSS_C_ANON_FLAG
If true, the
initiator's identity is
not revealed to the
acceptor. The src_name
parameter, if
requested, contains an
anonymous internal
name. If false, the
initiator has been
authenticated normally.

GSS_C_PROT_READY_FLAG
If true, the protection
services, as specified
by the states of the
GSS_C_CONF_FLAG and
GSS_C_INTEG_FLAG, are
available for use. If
false, they are
available only if the
context is fully
established, that is,
if the open parameter
is non-zero.

GSS_C_TRANS_FLAG
If true, resultant
security context can be
transferred to other
processes through a
call to
gss_export_sec_context().
If false, the security
context is not
transferable.

locally_initiated
Non-zero if the invoking application is the
context initiator. Specify NULL if the parameter
is not required.

open
Non-zero if the context is fully established;
zero if a context-establishment token is
expected from the peer application. Specify NULL
if the parameter is not required.

ERRORS

gss_inquire_context() returns one of the following status codes:

GSS_S_COMPLETE
Successful completion.

GSS_S_NO_CONTEXT
The referenced context could not be accessed.

GSS_S_FAILURE
The underlying mechanism detected an error for
which no specific GSS status code is defined.
The mechanism-specific status code reported by
means of the minor_status parameter details the
error condition.