gss_init_sec_context(3)gss_init_sec_context(3)NAMEgss_init_sec_context() - establish a security context between the con‐
text initiator and a context acceptor
SYNOPSISDESCRIPTION
The routine is the first step in the establishment of a security con‐
text between the context initiator and the context acceptor. To ensure
the portability of the application, use its default credential by sup‐
plying to the claimant_cred_handle parameter. Specify an explicit cre‐
dential when the application needs an additional credential; for exam‐
ple, to use delegation.
The first time the application calls the routine, specify the
input_token parameter as Calls to the routine can return an out‐
put_token for transfer to the context acceptor. The context acceptor
presents the token to the routine.
If the context initiator does not require a token, sets the length
field of the output_token argument to 0 (zero).
To complete establishing the context, the calling application can
require one or more reply tokens from the context acceptor. If the
application requires reply tokens, the routine returns a status value
of The application calls the routine again when the reply token is
received from the context acceptor and passes the token to the routine
via the input_token parameter.
The values returned by the ret_flags and time_rec parameters are not
defined unless the routine returns the status
If the initial call of fails, the call should not create a context
object, and should leave the value of the context_handle parameter set
to to indicate this.
Input Parameters
claimant_cred_handle Specifies an optional handle for the credential.
To use the default credential, supply The creden‐
tial handle created refers to the DCE default
login context. If no default initiator is
defined, the function will return
target_name Specifies the name of the context acceptor.
mech_type Specifies the security mechanism. Supply to
obtain an implementation specific default.
req_flags Specifies independent flags, each of which
requests that the context support a service
option. The following symbolic names are pro‐
vided to correspond to each flag. The symbolic
names should be logically ORed to form a bit-mask
value.
The True/False values are:
True Credentials were delegated to the
context acceptor.
False No credentials were delegated.
The True/False values are:
True The context acceptor has been asked
to authenticate itself.
False The context initiator has not been
asked to authenticates itself.
The True/False values are:
True Replayed signed or sealed messages
will be detected.
False Replayed messages will not be
detected.
The True/False values are:
True Out-of-sequence signed or sealed
messages will be detected.
False Out-of-sequence signed or sealed
messages will not be detected.
The True/False values are:
True Request that confidentiality service
be made available
False No per-message confidentiality ser‐
vice is required.
The True/False values are:
True Request that integrity service be be
made available
False No per-message integrity service is
required.
The True/False values are:
True Do not reveal the initiator's iden‐
tity to the acceptor.
False Authenticate normally.
time_req Specifies the desired number of seconds for which
the context should remain valid. To specify the
default validity period, use 0 (zero).
input_chan_bindings Specifies the bindings set by the context initia‐
tor. Allows the context initiator to bind the
channel identification information securely to
the security context. If channel bindings are
not used specify
input_token Specifies the token received from the context
acceptor.
The first time the application calls the routine,
you specify Subsequent calls require a token from
the context acceptor.
Input/Output Parameters
context_handle Specifies the context handle for the new context.
The first time the application calls the routine,
you specify Subsequent calls use the value
returned by the first call.
Output Parameters
actual_mech_type Returns the OID of the actual mechanism used.
Specify NULL if not required.
output_token Returns the token to send to the context accep‐
tor. If the length field of the returned buffer
is 0 (zero), no token is sent.
ret_flags Returns six independent flags, each of which
indicates that the context supports a service
option. Specify NULL if not required. The fol‐
lowing symbolic names are provided to correspond
to each flag:
The True/False values are:
True Credentials were delegated to the
context acceptor.
False No credentials were delegated.
The True/False values are:
True The context acceptor has been asked
to authenticate itself.
False The context acceptor has not been
asked to authenticate itself.
The True/False values are:
True Replayed signed or sealed messages
will be detected.
False Replayed messages will not be
detected.
The True/False values are:
True Out-of-sequence signed or sealed
messages will be detected.
False Out-of-sequence signed or sealed
messages will not be detected.
The True/False values are:
True Confidentiality service can be
invoked by calling the routine.
False No confidentiality service is avail‐
able. (Confidentiality can be pro‐
vided using the routine, which pro‐
vides only message encapsulation,
data-origin authentication, and
integrity services.)
The True/False values are:
True Integrity service can be invoked by
calling either the or routine.
False Integrity service for individual
messages is unavailable.
The True/False values are:
True Do not reveal the initiator's iden‐
tity to the acceptor.
False Authenticate normally.
The True/False values are:
True Protection services (as specified by
the states of the and are available
for use if the accompanying major
status is either or
False Protection services(as specified by
the states of the and are available
for use if the accompanying major
status is either
The True/False values are:
True The resultant security context may
be transferred to other processes
False The security context is not is not
transferable
time_rec Returns the number of seconds for which the con‐
text will be valid. If the mechanism does not
support credential expiration, the routine
returns the value If the credential expiration
time is not required, specify NULL.
minor_status Returns a status code from the security mecha‐
nism.
STATUS CODES
The following status codes can be returned:
The routine was completed successfully.
The input_token parameter contains different chan‐
nel bindings from those specified with the
input_chan_bindings parameter.
The target_name parameter contains an invalid or
unsupported name type.
The target_name parameter was incorrectly formed.
Indicates either that the
input_token parameter contains an invalid sig‐
nature or that the input_token parameter con‐
tains a signature that could not be verified.
To complete the context, the
routine must be called again with a token
required from the context acceptor.
The referenced credentials have expired.
Consistency checks performed on the credential failed.
Consistency checks performed on
the input_token parameter failed.
The input_token parameter was already processed.
This is a fatal error that occurs during con‐
text establishment.
The routine failed. See the
minor_status parameter return value for more
information.
The supplied context handle did not refer to a valid
context.
The input_token parameter was too old. This is a
fatal error that occurs during context estab‐
lishment.
The supplied credentials were not valid for context
initiation, or the credential handle did not
reference any credentials.
The specified mechanism is not supported by the provided credential
AUTHOR
was developed by Sun Microsystems, Inc.
SEE ALSOgss_accept_sec_context(3), gss_delete_sec_context(3).
The manpages for DCE-GSSAPI are included with the DCE-CoreTools prod‐
uct. To see those manpages add to
gss_init_sec_context(3)