gss_inquire_context Extract security context information

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 3:...

GSSAPI (Generic Security Services Application...

gss_init_sec_context Establish a security context

gss_inquire_cred Provide calling application with information...

gss_inquire_context -- Extract security context information

C Prototype

OM_uint32 gss_inquire_context(
        OM_uint32          minor_status,
        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 );

Arguments

minor_status
(output) An implementation-specific status code.

context_handle (input) A context handle identifying the context for which information is to be returned.

src_name (output) 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 will be returned. Storage associated with this name must be freed by the application after use with a call to gss_release_name.

targ_name (output) The name of the context target. 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 will be returned. Specify NULL if not required.

lifetime_rec (output) The number of seconds for which the context will remain valid. If the context has expired, this argument will be set to zero. If the implementation does not support credential expiration, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.

mech_type (output) The security mechanism providing the context. The returned OID will be 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 not required.

ctx_flags (output) Contains several independent flags, each of which indicates that the context supports (or is expected to support, if 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

TRUE -- Credentials were delegated from the initiator to the acceptor.FALSE -- No credentials were delegated.

GSS_C_MUTUAL_FLAGTRUE -- The acceptor was authenticated to the initiator.FALSE -- The acceptor did not authenticate itself.

GSS_C_REPLAY_FLAG

TRUE -- Replay of protected messages will be detected.FALSE -- Replay messages will not be detected.

GSS_C_SEQUENCE_FLAG

TRUE -- Out-of-sequence protected messages will be detected.FALSE -- Out-of-sequence messages will not be detected.

GSS_C_CONF_FLAG

TRUE -- Confidentiality service may be invoked by calling the gss_wrap routine.FALSE -- No confidentiality service (via gss_wrap) is available. The gss_wrap routine provides message encapsulation, data-origin authentication, and integrity services only.

GSS_C_INTEG_FLAG

TRUE -- Integrity service may be invoked by calling either the gss_get_mic or gss_wrap routine.FALSE -- Per-message integrity service is unavailable.

GSS_C_ANON_FLAG

TRUE -- The initiator's identity will not be revealed to the acceptor. The src_name argument (if requested) contains an anonymous internal name.FALSE -- The initiator has been authenticated normally.

GSS_C_PROT_READY_FLAG

TRUE -- Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use.FALSE -- Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the context is fully established (that is, if the open argument is nonzero).

GSS_C_TRANS_FLAG

TRUE -- The resultant security context may be transferred to other processes via a call to gss_export_sec_context.FALSE -- The security context is not transferable.

locally_initiated (output)
A Boolean value. Specify NULL if not required.

TRUE if the caller is the context initiator.

FALSE if the caller is the acceptor.

open (output) A Boolean value. Specify NULL if not required.

TRUE if the context is fully established

FALSE if a context-establishment token is expected from the peer application.

Description

This routine is used to extract information describing characteristics of a security context. The caller must already have obtained a handle that refers to the context, although the context need not be fully established.

Return Values

This routine returns one of the following GSS status codes:

GSS_S_COMPLETE
Indicates that the referenced context is valid and that ctx_flags, locally_initiated, and open return values describe the corresponding characteristics of the context. If open is TRUE, lifetime_rec is also returned; if open is TRUE and the context peer's name is known, src_name and targ_name are valid in addition to the values listed previously. The mech_type value must be returned for contexts where open is TRUE and may be returned for contexts where open is FALSE.

GSS_S_NO_CONTEXT
Indicates that no valid context was recognized for the input context_handle provided. Return values other than minor_status are undefined.

gss_init_sec_context Establish a security context

gss_inquire_cred Provide calling application with information...

minor_status (output)		An implementation-specific status code.
context_handle (input)		A context handle identifying the context for which information is to be returned.
src_name (output)		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 will be returned. Storage associated with this name must be freed by the application after use with a call to `gss_release_name`.
targ_name (output)		The name of the context target. 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 will be returned. Specify NULL if not required.
lifetime_rec (output)		The number of seconds for which the context will remain valid. If the context has expired, this argument will be set to zero. If the implementation does not support credential expiration, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.
mech_type (output)		The security mechanism providing the context. The returned OID will be 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 not required.
ctx_flags (output)		Contains several independent flags, each of which indicates that the context supports (or is expected to support, if 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 TRUE -- Credentials were delegated from the initiator to the acceptor.FALSE -- No credentials were delegated. GSS_C_MUTUAL_FLAGTRUE -- The acceptor was authenticated to the initiator.FALSE -- The acceptor did not authenticate itself. GSS_C_REPLAY_FLAG TRUE -- Replay of protected messages will be detected.FALSE -- Replay messages will not be detected. GSS_C_SEQUENCE_FLAG TRUE -- Out-of-sequence protected messages will be detected.FALSE -- Out-of-sequence messages will not be detected. GSS_C_CONF_FLAG TRUE -- Confidentiality service may be invoked by calling the `gss_wrap` routine.FALSE -- No confidentiality service (via `gss_wrap`) is available. The `gss_wrap` routine provides message encapsulation, data-origin authentication, and integrity services only. GSS_C_INTEG_FLAG TRUE -- Integrity service may be invoked by calling either the `gss_get_mic` or `gss_wrap` routine.FALSE -- Per-message integrity service is unavailable. GSS_C_ANON_FLAG TRUE -- The initiator's identity will not be revealed to the acceptor. The `src_name` argument (if requested) contains an anonymous internal name.FALSE -- The initiator has been authenticated normally. GSS_C_PROT_READY_FLAG TRUE -- Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use.FALSE -- Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the context is fully established (that is, if the open argument is nonzero). GSS_C_TRANS_FLAG TRUE -- The resultant security context may be transferred to other processes via a call to `gss_export_sec_context`.FALSE -- The security context is not transferable.
locally_initiated (output)
		A Boolean value. Specify NULL if not required. TRUE if the caller is the context initiator. FALSE if the caller is the acceptor.
open (output)		A Boolean value. Specify NULL if not required. TRUE if the context is fully established FALSE if a context-establishment token is expected from the peer application.