Optional Parameters

In routine descriptions, optional parameters allow the application to request default behaviors by passing a default value for the parameter. Table 5-4 lists conventions that are used for optional parameters:

Table 5-4 Conventions for Optional Parameters

Convention	Value Default	Explanation
gss_buffer_t types	GSS_C_NO_BUFFER	For an input parameter, indicates no data is supplied. For an output parameter, indicates that the information returned is not required by the application.
Integer types (input)		Refer to the reference pages for default values.
Integer types (output)	NULL	Indicates that the application does not require the information.
Pointer types (output)	NULL	Indicates that the application does not require the information.
OIDS	GSS_C_NULL_OID	Indicates the default choice for name type or security mechanism.
OID sets	GSS_C_NULL_OID_SET	Indicates the default set of security mechanisms, DCE Security, and Kerberos.
Credentials	GSS_C_NO_CREDENTIAL	Indicates that the application should use the default credential handle.
Channel bindings	GSS_C_NO_CHANNEL_BINDINGS	Indicates that no channel bindings are used.

See Also

OSF DCE Application Development Guide

Establishes a security context between the application and a context acceptor.

Syntax

OM_uint32 gss_accept_sec_context( minor _status,
context _handle,
verifier _cred_handle,
input _token_buffer,
input _chan_bindings,
src _name,
actual _mech_type,
output _token,
ret _flags,
time _rec,
delegated _cred_handle )

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gss_accept_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_cred_id_t verifier_cred_handle,
gss_buffer_t input_token_buffer,
gss_channel_bindings_t input_chan_bindings,
gss_name_t *src_name,
gss_OID *actual_mech_type,
gss_buffer_t output_token,
int *ret_flags,
OM_uint32 *time_rec,
gss_cred_id_t *delegated_cred_handle)

Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies a context handle for a new context. The first time the context initiator uses the routine, specify GSS_C_NO_CONTEXT to set up a specific context. In subsequent calls, use the value returned by this parameter.

verifier_cred_handle

Specifies the credential handle (the identity) claimed by the context acceptor. This is optional information. The credential must be either an ACCEPT type credential or a BOTH type credential. If you do not specify a credential handle and specify instead GSS_C_NO_CREDIALS, the application can accept a context under any registered identity. Use the gssdce_register_acceptor_identity() routine to register an identity before specifying GSS_C_NO_CRED.

input_token_buffer

Specifies the token received from the context acceptor.

input_chan_bindings

Specifies bindings supplied by the context initiator.

Allows the context initiator to bind the channel identification information securely to the security context.

src_name

Returns the authenticated name of the context initiator. This information is optional. If the authenticated name is not required, specify NULL.

To deallocate the authenticated name, pass it to the gss_release_name() routine.

actual_mech_type

Returns a set of security mechanisms with which the credential can be used. The set can contain one of the following:

• GSS_C_OID_DCE_KRBV5_DES, for DCE Security
• GSS_C_OID_KRBV5_DES, for Kerberos Version 5

output_token

Returns a token to pass to the context acceptor. If no token is to be passed to the context acceptor, the routine sets the length field of the returned token buffer to zero.

reg_flags

Returns a bit-mask containing 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 ANDed with the value of ret_flags to test whether the context supports the service option.

Name	Flag	Description
GSS_C_DELEG_FLAG	True	Delegated credentials are available from the delegated_cred_handle parameter.
	False	No credentials were delegated.
GSS_C_MUTUAL_FLAG	True	The context acceptor requested mutual authentication.
	False	The context acceptor did not request mutual authentication.
GSS_C_REPLAY_FLAG	True	Replayed signed or sealed messages will be detected.
	False	Replayed messages will not be detected.
GSS_C_CONF_FLAG	True	Confidentiality services are available by calling the gss_seal() routine.
	False	Confidentiality services are not available. However, the application can call the gss_seal() routine to provide message encapsulation, data-origin authentication, and integrity services.
GSS_C_INTEG_FLAG	True	Integrity services can be invoked by calling either the gss_sign() or gss_seal() routines.
	False	Integrity services for individual messages are not available.

time_rec

Returns the number of seconds for which the context remains valid. This is optional information. If the time is not required, specify NULL.

delegated_cred_handle

Returns the credential handle for credentials received from the context initiator. The credential handle is valid only if delegated credentials are available. If the ret_flags parameter is true, the flag GSS_C_DELEG_FLAG is set, indicating that delegated credentials are available.

Description

The gss_accept_sec_context() routine is the second step in establishing a security context between the context initiator and a context acceptor. In the first step, the context initiator calls the gss_init_sec_context() routine. The gss_init_sec_context() routine generates a token for the security context and passes it to the context initiator. The context initiator sends the token to the context acceptor.

In the second step, the context acceptor accepts the call from the context initiator and calls the gss_accept_sec_context() routine. The gss_accept_sec_context() routine expects a value for the input_token parameter. The value for the input_token is generated by the gss_init_sec_context() routine and passed by the initiator to the acceptor.

The gss_accept_sec_context() routine can also return a value for the output_token parameter. The context acceptor presents the token to the gss_init_sec_context() routine. If the acceptor does not need to send a token to the initiator, gss_accept_sec_context() sets the length field of the output_token parameter to zero.

To complete establishing the context, the context initiator can require one or more reply tokens from the context acceptor. If the application requires reply tokens, the gss_accept_sec_context() routine returns a status value containing GSS_S_CONTINUE_NEEDED. The application calls the routine again when the reply token is received from the context acceptor. The application passes the token to the gss_accept_sec_context() routine using the output_token parameters.

The gss_accept_sec_context() routine must find a key to decrypt the token. The token contains the unencrypted principal name of the context acceptor. The acceptor's principal name identifies the key that the context initiator used to encrypt the rest of the token. The gss_accept_sec_context() routine matches the principal name with the key in the following way:

• If you specify a credential, the credential and the name in the token must match. The acceptor's principal name (contained in the token) has been registered by a call to the gss_dec_register_acceptor_identity(). The gss_accept_sec_context() routine looks in the registered key table.
• If you specify GSS_C_NO_CRED and the principal name in the token is registered, the gss_accept_sec_context() routine looks in the table specified when you registered the token name using either the rpc_server_register_auth_info() routine or the gssdce_register_acceptor_identity()\bold) routine.
• If you specify GSS_C_NO_CRED and the principal name in the token is not registered, the gss_accept_sec_context() routine fails and returns the status GSS_S_FAILURE because GSSAPI does not know where to find the key.

The following table summarizes how the gss_accept_sec_context() routine determines the key for the credential:

You specify...	Is the principal's name registered?	Then the routine...
A credential	Yes	Looks in the key table specified in gssdce_register_acceptor_identity() or the default key table.
GSS_C_NO_CRED	Yes	Looks in the key table specified in gssdce_register_acceptor_identity.
	No	Fails because the principal is not registered. It returns the status code GSS_S_FAILURE.

The values returned using the src_name, ret_flags, time_rec, and delegated_cred_handle parameters are not defined unless the routine returns the status GSS_S_COMPLETE.

Return Values

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_SIG	The input_token parameter contains an invalid signature.
GSS_S_CONTINUE_NEEDED	To complete the context, the gss_accept_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_NO_CRED	Indicates either the supplied credentials were not valid for context acceptance or the credential handle did not reference any credentials.
GSS_S_OLD_TOKEN	The input_token parameter was too old. This is a fatal error that occurs during context establishment.

See Also

gss_acquire_cred(3gss)
gss_delete_sec_context(3gss)
gss_init_sec_context(3gss)
gssdce_registor_acceptor_identity(3gss)

Allows an application to acquire a handle for an existing, named credential.

Syntax

OM_uint32 gss_acquire_cred(
*minor_status,
desired _name,
time _req,
desired _mechs,
cred _usage,
*output_cred_handle,
*actual_mechs,
*time_rec )

Argument	Data Type	Access
minor_status	OM_uint32	write
desired_name	gss_name_t	read
time_rec	OM_uint32	read
desired_mechs	gss_OID_set	read
cred_usage	int	read
output_cred_handle	gss_cred_id_t	write
actual_mechs	gss_OID_set	write
time_rec	OM_uint32	write

C Binding

#include <DCE/GSSAPI.H>
OM_uint32 gss_acquire_cred (
OM_uint32 *minor_status,
gss_name_t desired_name,
OM_uint32 time_req,
gss_OID_set desired_mechs,
int cred_usage,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_int32 *time_rec)

Arguments

minor_status

Returns a status code from the security mechanism.

desired_name

Specifies the principal name to use for the credential.

time_req

Specifies the number of seconds that credentials remain valid.

desired_mechs

Specifies the OID set for the security mechanism to use with the credential, as follows:

To use...	Specify...
DCE Security	GSS_C_NULL_OID_SET
Kerberos	GSS_C_OID_KRBV5_DES
Both DCE Security and Kerberos	GSS_C_OID_DCE_KRBV5_DES and GSS_C_OID_KRBV5_DES

To help ensure portability of your application, use the default security by specifying GSS_C_NULL_OID_SET.

cred_usage

Specify one of the following:

• GSS_C_BOTH
  Specifies credentials that the context initiator can use to either initiate or accept security contexts.
• GSS_C_ACCEPT
  Specifies credentials the context initiator can use only to accept security contexts.

output_cred_handle

Returns the handle for the return credential.

actual_mechs

Returns a set of mechanisms for which the credential is valid. This information is optional. If you do not want a set of mechanisms returned, specify NULL.

time_rec

Returns the actual number of seconds for which the return credential remains valid. This information is optional. If the actual number of seconds is not required, specify NULL.

Description

The gss_acquire_cred() routine allows an application to obtain a handle for either an ACCEPT or BOTH credential. The application then passes the credential handle to either the gss_init_sec_context() or gss_accept_sec_context() routine.

Credential handles created by the gss_acquire_cred() routine contain a principal name. If the principal name is unregistered, the gss_acquire_cred() routine automatically registers the principal in the default key table. You can change the principal's key table by calling the gssdce_register_acceptor_identify() routine.

To create an INITIATE credential, you must use the gssdce_login_context_to_cred() routine.

Return Values

Possible return values are as follows:

Return	Description
GSS_S_COMPLETE	The routine was completed successfully.
GSS_S_BAD_MECH	The requested security mechanism is unsupported or unavailable.
GSS_S_BAD_NAMETYPE	The name passed by the desired_name parameter is unsupported.
GSS_S_BAD_NAME	An invalid name was passed by the desired_name parameter.
GSS_S_FAILURE	The routine failed. See the minor_status parameter return value for more information.

See Also

gssdce_accept_sec_context(3gss)
gssdce_create_empty_oid_set(3gss)
gssdce_login_context_to_credential(3gss)
gssdce_register_acceptor_identity(3gss)
gss_init_sec_context(3gss)

Allows an application to compare two internal names to determine whether they refer to the same object.

Syntax

OM_uint32 gss_compare_name(
minor _status,
name1 ,
name2 ,
name _equal )

Argument	Data Type	Access
minor_status	OM_uint32	write
name1	gss_name_t	read
name2	gss_name_t	read
name_equal	int	write

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gss_accept_compare_name (
OM_uint32 *minor_status,
gss_name_t name1,
gss_name_t name2,
int *name_equal)

Arguments

minor_status

Returns a status code from the security mechanism.

name1

Specifies the first internal name

name2

Specifies the second internal name

name_equal

Returns one of the following values:

• True
  The names refer to the same object.
• False
  The names are not known to refer to the same object.

Description

The gss_compare_name() routine lets an application compare two internal names to determine whether they refer to the same object.

Return Values

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 name1 or name2 parameter is unsupported.
GSS_S_BAD_NAME	An invalid name was passed by the name1 or name2 parameter.
GSS_S_FAILURE	The routine failed. Check the minor status for details.

See Also

gss_display_name(3gss)
gss_import_name(3gss)
gss_release_name(3gss)