| Previous | Contents | Index |
Checks the number of seconds for which the context will remain valid.
OM_uint32 gss_context_time(
minor _status,
context _handle,
time _rec )
Argument Data Type Access minor_status OM_uint32 write context_handle gss_ctx_id_t read time_rec OM_uint32 write
#include <DCE/GSSAPI.H>
OM_uint32 gss_context_time (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
OM_uint32 *time_rec)
minor_status
Returns a status code from the security mechanism.context_handle
Specifies the context to be checked.time_rec
Returns the number of seconds that the context will remain valid. Returns a zero if the context has already expired.
The gss_context_time() routine checks the number of seconds for which the context will remain valid.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_CONTEXT_EXPIRED The context has already expired. GSS_S_CREDENTIALS_EXPIRED The context is recognized but the associated credentials have expired. GSS_S_NO_CONTEXT The context identified in the context_handle parameter was not valid. GSS_S_FAILURE The routine failed. See the minor_status parameter return value for more information.
None.
Deletes a security context.
OM_uint32 gss_delete_sec_context(
minor _status,
context _handle,
output _token_buffer )
Argument Data Type Access minor_status OM_uint32 write context_handle gss_ctx_id_t read/write output_token_buffer gss_buffer_t write
#include <DCE/GSSAPI.H>
OM_uint32 gss_accept_delete_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_buffer_t output_token_buffer)
minor_status
Returns a status code from the security mechanism.context_handle
Returns the context handle for the context to delete.output_token_buffer
Returns a token to tell the application to delete the context.
The gss_delete_sec_context() routine deletes a security context. It also deletes the local data structures associated with the security context. When it deletes the context, the routine can generate a token. The application passes the token to the context acceptor. The context acceptor then passes the token to the gss_process_context_token() routine, telling it to delete the context and all associated local data structures.When the context is deleted, the applications cannot use the context_handle parameter for additional security services.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_FAILURE The routine failed. See the minor_status parameter return value for more information. GSS_S_NO_CONTEXT The supplied context handle did not refer to a valid context.
gss_accept_sec_context(3gss)
gss_init_sec_context(3gss)
gss_process_context_token(3gss)
Provides to an application the textual representation of an opaque internal name.
OM_uint32 gss_display_name(
minor _status,
input _name,
output _name_buffer,
output _name_type )
Argument Data Type Access minor_status OM_uint32 write input_name gss_name_t read output_name_buffer gss_buffer_t write output_name_type gss_OID write
#include <DCE/GSSAPI.H>
OM_uint32 gss_display_name (
OM_uint32 *minor_status,
gss_name_t input_name,
gss_buffer_t output_name_buffer,
gss_OID *output_name_type)
minor_status
Returns a status code from the security mechanism.input_name
Specifies the name to convert to text.output_name_buffer
Returns the name as a character string.output_name_type
Returns the type of name to display as a pointer to static storage. The application should treat this as read only.
The gss_display_name() routine provides an application with the text form of an opaque internal name. The application can use the text to display the name but not to print it.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_BAD_NAMETYPE The name passed by the input_name parameter is recognized. GSS_S_BAD_NAME An invalid name was passed by the input_name parameter. GSS_S_FAILURE The routine failed. Check the minor status for details.
gss_compare_name(3gss)
gss_import_name(3gss)
gss_release_name(3gss)
Provides an application with the textual representation of a GSS API status code that can be displayed to a user or used for logging.
OM_uint32 gss_display_status(
minor _status,
status _value,
status _type,
mech _type,
message _context,
status _string )
Argument Data Type Access minor_status OM_uint32 write status_value int read status_type int read mech_type gss_OID read message_context int read/write status_string gss_buffer_t write
#include <DCE/GSSAPI.H>
OM_uint32 gss_display_status (
OM_uint32 *minor_status,
int status_value,
int status_type,
gss_OID mech_type,
int *message_context,
gss_buffer_t status_string)
minor_status
Returns a status code from the security mechanism.status_value
Specifies the status value to convert.status_type
Specify one of the following status types:
- GSS_C_GSS_CODE
Major status; a GSS status code.- GSS_C_MECH_CODE
Minor status; either DCE Security or Kerberos status code.mech_type
Specifies the security mechanism. To use DCE Security, specify either of the following:
- GSS_C_OID_DCE_KRBV5_DES
- GSS_C_NULL_OID_SET
To use Kerberos, specify GSS_C_OID_KRBV5_DES.
message_context
Indicates whether the status code has multiple messages to read.The first time an application calls the routine, initialize the parameter to zero. The routine returns the first message. If there are more messages, the routine sets the parameter to a nonzero value. The application calls the routine repeatedly to get the next message, until the message_context parameter is zero again.
status_string
Returns the status value as a text message.
The gss_dislay_status() routine provides the context initiator with a textual representation of a status code, so the application can display the message to a user or log the message. Because some status values can indicate more than one error, the routine enables the calling application to process status codes with multiple messages.The message_context parameter indicates which error message the application should extract from the status_value parameter. The first time an application calls the routine, it should initialize the message_context parameter to zero and return the first message. If there are additional messages to read, the gss_display_status() routine returns a nonzero value. The application can call gss_display_status() repeatedly to generate a single text string for each call.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_BAD_MECH The translation requires a mechanism that is unsupported or unavailable. GSS_S_BAD_STATUS Indicates either the status value was not recognized or the status type was something other than GSS_C_GSS_CODE or GSS_C_MECH_CODE. GSS_S_FAILURE The routine failed. Check the minor status for details.
None.
Converts a printable name to an internal form.
OM_uint32 gss_import_name(
minor _status,
input _buffer_name,
input _name_type,
output _name )
Argument Data Type Access minor_status OM_uint32 write input_buffer_name gss_buffer_t read input_name_type gss_OID read output_name gss_name_t write
#include <DCE/GSSAPI.H>
OM_uint32 gss_import_name (
OM_uint32 *minor_status,
gss_buffer_t input_buffer_name,
gss_OID input_name_type,
gss_name_t *output_name)
minor_status
Returns a status code from the security mechanism.input_buffer_name
Specifies the buffer containing the printable name to convert.input_name_type
Specifies the object identifier for the type of printable name. Specify GSS_C_NULL_OID to use the DCE name.You can explicitly request the DCE name using GSS_C_OID_DCE_NAME. To help ensure portability of your application, use the default, GSS_C_NULL_OID.
output_name
Returns the name in an internal form.
The gss_import_name() routine converts a printable name to an internal form.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_BAD_NAMETYPE The name passed by the input_name parameter is not recognized. GSS_S_BAD_NAME The routine could not interpret the input_name parameter as a name of the type specified. GSS_S_FAILURE Check the minor status for details.
gss_compare_name(3gss)
gss_display_name(3gss)
gss_release_name(3gss)
Allows an application to determine which underlying security mechanisms are available.
OM_uint32 gss_indicate_mechs(
minor _status,
mech _set )
Argument Data Type Access minor_status OM_uint32 write mech_set gss_OID_set write
#include <DCE/GSSAPI.H>
OM_uint32 gss_indicate_mechs (
OM_uint32 *minor_status,
gss_OID_set *mech_set)
minor_status
Returns a status code from the security mechanism.mech_set
Returns the set of supported security mechanisms. The value of gss_OID_set is a pointer to a static storage and should be treated as read only by the context initiator.
The gss_indicate_mechs() routine enables an application to determine which underlying security mechanisms are available. These are DCE Security and Kerberos Version 5.To check that a specific security mechanism is available, use the gssdce_test_oid_set_member() routine.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_FAILURE The routine failed. Check the minor status for details.
gss_test_oid_set_member(3gss)
Establishes a security context between the context initiator and a context acceptor.
OM_uint32 gss_init_sec_context(
minor _status,
claimant _cred_handle,
context _handle,
target _name,
mech _type,
req _flags,
time _req,
input _channel_bindings,
actual _mech_type,
output _token,
ret _flags,
time _rec )
Argument Data Type Access minor_status OM_uint32 write claimant_cred_handle OM_uint32 read context_handle gss_ctx_id_t read/write target_name gss_name_t read mech_type gss_OID read req_flags int read time_req int read input_channel_bindings gss_channel_bindings_t read actual_mech_type gss_OID write output_token gss_buffer_t write ret_flags nt write time_rec OM_int32 write
#include <DCE/GSSAPI.H>
OM_uint32 gss_init_sec_context (
OM_uint32 *minor_status,
gss_cred_id_t claimant_cred_handle,
gss_ctx_id_t *context_handle,
gss_name_t target_name,
gss_OID mech_type,
int req_flags,
int time_req,
gss_channel_bindings_t input_channel_bindings,
gss_OID *actual_mech_type,
gss_buffer_t output_token,
nt *ret_flags,
OM_int32 *time_rec)
minor_status
Returns a status code from the security mechanism.claimant_cred_handle
Specifies an optional handle for the credential. To use the default credential, supply GSS_C_NO_CREDENTIAL. The credential handle created refers to the DCE default login context. The credential must be either an INITIATE or BOTH type credential.context_handle
Specifies the context handle for the new context.The first time the application calls the routine, specify GSS_C_NO_CONTEXT. Subsequent calls use the value returned by the first call.
target_name
Specifies the name of the context acceptor.mech_type
Specifies the security mechanism. To use DCE Security, specify either of the following:
- GSS_C_OID_DCE_KRBV5_DES
- GSS_C_NULL_OID
To use Kerberos, specify GSS_C_OID_KRBV5_DES.
req_flags
Specifies four independent flags, each of which requests that the context support a service option. The following symbolic names are provided to correspond to each flag. The symbolic names should be logically ORed to form a bit-mask value.
GSS_C_DELEG_FLAG True Delegate credentials to the context acceptor. False Do not delegate credentials. GSS_C_MUTUAL_FLAG True Request the context acceptor to authenticate itself. False The context initiator only authenticates itself. GSS_C_REPLAY_FLAG True Replayed signed or sealed messages will be detected. False Replayed messages are not detected. GSS_C_SEQUENCE_FLAG True Detect out-of-sequence signed or sealed messages. False Do not detect out-of-sequence signed or sealed messages. time_req
Specifies the desired number of seconds for which the context should remain valid. To specify the default validity period, use zero.input_channel_bindings
Specifies the bindings set by the context initiator. Allows the context initiator to bind the channel identification information securely to the security context.actual_mech_type
Returns one of the following values indicating the security mechanism:
- GSS_C_OID_DCE_KRBV5_DES, for DCE Security
- GSS_C_OID_KRBV5_DES, for Kerberos
output_token
Returns the token to send to the context acceptor.If the length field of the returned buffer is zero, no token is sent.
ret_flags
Returns six independent flags, each of which indicates that the context supports a service option. The following symbolic names are provided to correspond to each flag:
GSS_C_DELEG_FLAG True Credentials were delegated to the context acceptor. False No credentials were delegated. GSS_C_MUTUAL_FLAG True The context acceptor has been asked to authenticate itself. False The context acceptor has not been asked to authenticate itself. GSS_C_REPLAY_FLAG True Replayed signed or sealed messages will be detected. False Replayed messages will not be detected. GSS_C_SEQUENCE_FLAG True Out-of-sequence signed or sealed messages will be detected. False Out-of-sequence signed or sealed messages will not be detected. GSS_C_CONF_FLAG True Confidentiality service can be invoked by calling the gss_seal() routine. False No confidentiality service is available. (Confidentiality can be provided using the gss_seal() routine, which provides only message encapsulation, data-origin authentication, and integrity services.) GSS_C_INTEG_FLAG True Integrity service can be invoked by calling either the gss_sign() or gss_seal() routines. False Integrity service for individual messages is unavailable. time_rec
Returns the number of seconds for which the context will be valid. If the mechanism does not support credential expiration, the routine returns the value GSS_C_INDEFINITE. If the credential expiration time is not required, specify NULL.
The gss_init_sec_context() routine is the first step in the establishment of a security context between the context initiator and the context acceptor. To ensure the portability of the application, specify its default credential by supplying GSS_C_NO_CREDENTIAL to the claimant_cred_handle parameter. Specify an explicit credential when the application needs additional credential, for example, to use delegation.The first time the application calls the gss_init_sec_context() routine, specify the input_token parameter as GSS_NO_BUFFER. Calls to the routine can return an output_token for transfer to the context acceptor. The context acceptor presents the token to the gss_accept_sec_context() routine.
If the context initiator does not require a token, gss_init_sec_context() sets the length field of the output_token argument to 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 gss_init_sec_context() routine returns a status value of GSS_S_CONTINUE_NEEDED. The application calls the routine again when the reply token is received from the context acceptor and passes the token to the gss_init_sec_context() routine using the input_token parameter.
The values returned using the ret_flags and time_rec parameters are not defined unless the routine returns the status GSS_S_COMPLETE.
Possible return values are as follows:
Return Description GSS_S_COMPLETE The routine was completed successfully. GSS_S_BAD_BINDINGS The input_token parameter contains different channel bindings from those specified with the input_chan_bindings parameter. GSS_S_BAD_NAMETYPE The target_name parameter contained an invalid or unsupported name type. GSS_S_BAD_NAME The target_name parameter was incorrectly formed. GSS_S_BAD_SIG Indicates either that the input_token parameter contains an invalid signature or that the input_token parameter contains a signature that could not be verified. GSS_S_CONTINUE_NEEDED To complete the context, the gss_init_sec_context routine must be called again with a token required from the context acceptor. GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. GSS_S_DEFECTIVE_CREDENTIAL Consistency checks performed on the credential failed. GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the input_token parameter failed. GSS_S_DUPLICATE_TOKEN The input_token parameter was already processed. This is a fatal error that occurs during context establishment. GSS_S_FAILURE The routine failed. See the minor_status parameter return value for more information. GSS_S_NO_CONTEXT The supplied context handle did not refer to a valid context. GSS_S_OLD_TOKEN The input_token parameter was too old. This is a fatal error that occurs during context establishment.
gss_accept_sec_context(3gss)
gss_delete_sec_context(3gss)
| Previous | Next | Contents | Index |