Checks that the cryptographic signature fits the supplied message.

Syntax

OM_uint32 gss_verify(
minor _status,
context _handle,
message _buffer,
token _buffer,
qop _state )

Argument	Data Type	Access
minor_status	OM_uint32	write
context_handle	gss_ctx_id_t	read
message_buffer	gss_buffer_t	read
token_buffer	gss_buffer_t	read
qop_state	int	write

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gss_verify (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
gss_buffer_t message_buffer,
gss_buffer_t token_buffer,
int qop_state)

Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the context on which the message arrived.

message_buffer

Specifies the message to be verified.

token_buffer

Specifies the signature token to be associated with the message.

qop_state

Returns the cryptographic algorithm, or quality of protection, from the signature.

Description

The gss_verify() routine checks that an encrypted signature, in the token_buffer parameter, fits the message in the message_buffer buffer. The application receiving the message can use the qop_state parameter to check the message's protection.

Return Values

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_FAILURE	The routine failed. Check the minor status for details.
GSS_S_NO_CONTEXT	The context identified in the context_handle parameter was not valid.
GSSDCE_C_QOP_MD5	The default protection and the fastest of the three available protection algorithms. When designing portable applications, use this level of protection. The routine uses the Message Digest Algorithm 5 (MD5), from RSA Data Security, Inc., to calculate a checksum of the user data, portions of the message header, and a function of the security key. To avoid an attack involving data padding, only eight bytes of the 16-byte checksum are transmitted.
GSSDCE_C_QOP_DES_MD5	The routine uses the MD5 to calculate a checksum of the user data and portions of the message header. The routine then calculates the DES Message Authentication Code (MAC) of this checksum using the security context integrity key. This method is faster than the DES MAC method.
GSSDCE_C_QOP_DES_MAC	This is considered the standard algorithm, but it is the slowest of the three available protection algorithms. The routine uses the standard DES Message Authentication Code (MAC) to calculate the checksum of the user data and portions of the message header. The routine then encrypts the checksum with the security context's integrity key.

See Also

gss_sign(3gss)
gss_seal(3gss)

Adds an OID to an OID set.

Syntax

OM_uint32 gssdce_add_oid_set_member(
minor _status,
member _OID,
OID _set )

Argument	Data Type	Access
minor_status	OM_uint32	write
member_OID	gss_OID	read
OID_set	gss_OID_set	read

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_add_oid_set_member (
OM_uint32 *minor_status,
gss_OID *member_OID,
gss_OID_set *OID_set)

Arguments

minor_status

Returns a status code from the security mechanism.

member_OID

Specifies the OID you want to add to the OID set.

OID_set

Specifies an OID set.

Description

The gssdce_add_oid_set_member() routine adds a new OID to an OID set. If an OID set does not exist, you can create a new, empty OID set with the gssdce_create_empty_oid_set() routine.

Return Values

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.

See Also

gssdce_create_empty_oid_set
gss_acquire_cred

Creates a new, empty OID set to which members can be added by calling the gssdce_add_oid_set_member() routine.

Syntax

OM_uint32 gssdce_create_empty_oid_set(
minor _status,
OID _set )

Argument	Data Type	Access
minor_status	OM_uint32	write
OID_set	gss_OID_set	read

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_create_empty_oid_set (
OM_uint32 *minor_status,
gss_OID_set *OID_set)

Arguments

minor_status

Returns a status code from the security mechanism.

OID_set

Specifies the OID set you want to create.

Description

The gssdce_create_empty_oid_set() routine creates a new, empty OID set to which the context initiator can add members. Use the gssdce_add_oid_set_member() routine to add members to the OID set.

Use the gssdce_create_empty_oid_set() routine to specify a set of security mechanisms with which you can use an acquired credential. To create a credential that can accept a security context using DCE Security, Kerberos, or a combination of the two, use the gss_acquire_cred() routine.

Return Values

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.

See Also

gssdce_add_oid_set_member(3gss)
gss_acquire_cred(3gss)

Obtains the DCE login context associated with a GSSAPI credential.

Syntax

OM_uint32 gssdce_cred_to_login_context(
minor _status,
cred _handle,
login _context )

Argument	Data Type	Access
minor_status	OM_uint32	write
cred_handle	gss_cred_id_t	read
login_context	gss_sec_login_handle_t	write

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_cred_to_login_context (
OM_uint32 *minor_status,
gss_cred_id_t *cred_handle,
gss_sec_login_handle_t login_context)

Arguments

minor_status

Returns a status code from the security mechanism.

cred_handle

Specifies the credential handle.

login_context

Returns the DCE login context associated with the credential.

Description

Using the gssdce_cred_to_login_context() routine, an application can obtain the DCE login context associated with a GSSAPI credential. Only credentials with usage-types INIT or BOTH have associated login contexts.

Use this routine:

• If you want to add delegation notes to a login context.
• To use an INITIATE or BOTH credential to initiate an authenticated RPC call.

The application must delete the login context when it no longer needs the credentials or the login context.

Return Values

Possible return values are as follows:

Return	Description
GSS_S_COMPLETE	The routine was completed successfully.
GSS_S_CREDENTIALS_EXPIRED	The credentials have expired.
GSS_S_DEFECTIVE_CREDENTIAL	The credential is defective in some way.
GSS_S_FAILURE	The routine failed. Check the minor status for details.
GSS_S_NO_CRED	The routine requested the default login context, but no default login context was available.

See Also

gssdce_login_context_to_cred(3gss)
sec_login_purge_contexsts(3sec)
sec_login_release_context(3sec)

Extracts a DCE PAC from a GSSAPI credential.

Syntax

OM_uint32 gssdce_extract_PAC_from_cred(
minor _status,
context _handle,
output _PAC )

Argument	Data Type	Access
minor_status	OM_uint32	write
context_handle	gss_ctx_id_t	read
output_PAC	gss_sec_id_pac_t	write

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_extract_PAC_from_cred (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
gss_sec_id_pac_t *output_PAC)

Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the handle of the security context containing the PAC.

output_PAC

Returns the PAC.

Description

The gssdce_extract_PAC_from_cred() routine extracts a DCE PAC from a GSSAPI credential. The routine extracts privilege attribute information about the principal associated with the credential.

A context acceptor calls this routine to examine the PAC contained in a delegated credential.

Return Values

Possible return values are as follows:

Return	Description
GSS_S_COMPLETE	The routine was completed successfully.
GSS_S_CREDENTIALS_EXPIRED	The credentials have expired.
GSS_S_DEFECTIVE_CREDENTIAL	The credential is defective in some way.
GSS_S_FAILURE	The routine failed. Check the minor status for details.
GSS_S_NO_CRED	The routine could not access the credentials.

See Also

gssdce_extract_PAC_from_sec_context(3gss)

Extracts a DCE PAC from a GSSAPI security context.

Syntax

OM_uint32 gssdce_extract_PAC_from_sec_context(
minor _status,
context _handle,
output _PAC )

Argument	Data Type	Access
minor_status	OM_uint32	write
context_handle	gss_ctx_id_t	read
output_PAC	gss_sec_id_pac_t	write

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_extract_PAC_from_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_sec_id_pac_t output_PAC)

Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the handle of the security context containing the PAC.

output_PAC

Returns the PAC. After using the PAC for access control, the calling application must deallocate the PAC using the sec_id_pac_util_free() routine.

Description

The gssdce_extract_PAC_from_sec_context() routine extracts the context initiator's DCE PAC from a context acceptor's security context. Use this routine if the underlying mechanism type is DCE Security (GSS_C_OID_DCE_KRBV5_DES).

The context acceptor calls the gssdce_extract_PAC_from_sec_context () routine to get the PAC containing the privilege attributes of the the context initiator. PACs are used to pass information to the ACL managers to determine if the initiator has rights to access the object with the ACL references.

The principal contained in the PAC may not be the same as the src_name parameter value from the gss_accept_sec_context() routine. The principal in the PAC may be a compound principal.

If the context was established by calling the gss_init_set_context() routine and specifying GSS_C_OID_KRBV5_DES to use Kerberos, the gssdce_extract_PAC_from_sec_context() routine returns a major status of GSS_S_FAILURE and a minor status indicating that no PAC is available.

Return Values

Possible return values are as follows:

Return	Description
GSS_S_COMPLETE	The routine was completed successfully.
GSS_S_CONTEXT_EXPIRED	The security context has expired.
GSS_S_FAILURE	The routine failed. Check the minor status for details.
GSS_S_NO_CONTEXT	The routine could not access the security context.

See Also

gssdce_extract_pac_from_cred(3gss)
sec_id_pac_util_free(3sec)

Creates a GSSAPI credential handle for a context initiator from a DCE login context.

Syntax

OM_uint32 gssdce_login_context_to_cred(
minor _status,
login _context,
lifetime _req,
desired _mechs,
output _cred_handle,
actual _mechs,
lifetime _rec )

Argument	Data Type	Access
minor_status	OM_uint32	write
login_context	sec_login_handle_t	read
lifetime_req	OM_uint32	read
desired_mechs	OID_set	read
output_cred_handle	gss_cred_id_t	write
actual_mechs	OID_set	write
lifetime_rec	OM_uint32	write

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_login_context_to_cred (
OM_uint32 *minor_status,
sec_login_handle_t login_context,
OM_uint32 lifetime_req,
OID_set desired_mechs,
gss_cred_id_t *output_cred_handle,
OID_set *actual_mechs,
OM_uint32 lifetime_rec)

Arguments

minor_status

Returns a status code from the security mechanism.

login_context

Specifies the DCE login context handle. To use the default login context handle, specify NULL.

lifetime_req

Specifies the number of seconds the credential should 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 mechanism by specifying GSS_C_NULL_OID_SET.

output_cred_handle

Returns the credential handle.

actual_mechs

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

• GSS_C_OID_DCE_KRBV5_DES\bold), for DCE Security
• GSS_C_OID_KRBV5_DES\bold), for Kerberos

lifetime_rec

Returns the number of seconds that the credential will remain valid.

Description

The gssdce_login_context_to_cred() routine creates a GSSAPI credential handle for the context initiator from a DCE login context. The routine creates a credential that can only be used to initiate a security context. Use this routine if you need to create a GSSAPI credential for delegation.

If you want to create a credential of usage type ACCEPT or BOTH, use the gss_acquire_cred() routine.

Return Values

Possible return values are as follows:

Return	Description
GSS_S_COMPLETE	The routine was completed successfully.
GSS_S_DEFECTIVE_CREDENTIAL	The credential is defective in some way.
GSS_S_NO_CRED	The routine requested the default login context, but no default login context was available.
GSS_S_FAILURE	The routine failed. Check the minor status for details.

See Also

gss_acquire_cred(3gss)
gss_cred_to_login_context(3gss)

Registers a context acceptor's identity.

Syntax

OM_uint32 gssdce_register_acceptor_identity(
minor _status,
acceptor _principal_name,
get _key_fn,
arg )

Argument	Data Type	Access
minor_status	OM_uint32	write
acceptor_principal_name	gss_name_t	read
get_key_fn	rpc_auth_key_retrieval_fn_t	read
arg	void	read

C Binding

#include <DCE/GSSAPI.H>

OM_uint32 gssdce_register_acceptor_identity (
OM_uint32 *minor_status,
gss_name_t *acceptor_principal_name,
rpc_auth_key_retrieval_fn_t get_key_fn,
void *arg)

Arguments

minor_status

Returns a status code from the security mechanism.

acceptor_principal_name

Specifies the principal name to use for the context acceptor.

get_key_fn

Specifies either the DCE default key-retrieval routine or the address of a routine that returns encryption keys.

arg

Specifies an argument to pass to the get_key_fn key acquisition routine. To specify the DCE default, use NULL.

Description

The gssdce_register_acceptor_identity() routine registers the server principal name as an identity claimed by the context acceptor and informs DCE security where to find the key table containing the principal's key information.

The gssdce_register_acceptor_identity() routine uses the get_key_fn and arg parameters of the rpc_server_register_auth_info() routine to find the key for the token for context acceptor's principal name. The following table lists the values for the parameters and which key tables they point to:

Retrieval Routine get_key_fn	Key Table arg	Explanation
NULL	NULL	Uses the default DCE retrieval routine to get the key from the DCE keytable using the default key table, /krb/v5srvtab.
NULL	string=key_table_name	Uses the default DCE retrieval routine to get the key from the key table whose name you specify using the argument string.
routine_address	user_written_routine	Uses a user-written retrieval routine to get the key from a key table specified in the routine.

For more information on registering a server with DCE, refer to the rpc_server_register_auth_info(3rpc) reference page.

Return Values

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.

See Also

gss_accept_sec_context(3gss)
rpc_server_register_auth_info(3rpc)