Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide


Previous Contents Index


gss_inquire_cred(3gss)

Provides the calling application information about a credential.

Syntax

OM_uint32 gss_inquire_cred(
minor _status,
cred _handle,
name ,
lifetime ,
cred _usage,
mechs )

Argument Data Type Access
minor_status OM_uint32 write
cred_handle gss_cred_id_t read
name gss_name_t write
lifetime OM_uint32 write
cred_usage nt write
mechs gss_OID_set write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_inquire_cred (
OM_uint32 *minor_status,
gss_cred_id_t cred_handle,
gss_name_t *name,
OM_uint32 *lifetime,
nt *cred_usage,
gss_OID_set *mechs)


Arguments

minor_status

Returns a status code from the security mechanism.

cred_handle

Specifies a handle for the target credential. To get information about the default credential, specify GSS_C_NO_CREDENTIAL.

name

Returns the principal name asserted by the credential. If the principal name is not required, specify NULL.

lifetime

Returns the number of seconds for which the credential will remain valid.

If the credential expired, the parameter returns a zero. If there is no credential expiration, the parameter returns the value GSS_C_INDEFINITE. If an expiration time is not required, specify NULL.

cred_usage

Returns one of the following values describing how the application can use the credential:

If no usage information is required, specify NULL.

mechs

Returns a set of security mechanisms supported by the credential, as follows:

Description

The gss_inquire_cred() routine provides information about a credential to the calling application. The calling application must first have called the gss_acquire_cred() routine for a handle for the 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 expired. If the lifetime parameter was passed as NULL, it is set to zero.
GSS_S_DEFECTIVE_CREDENTIAL The credentials were invalid.
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

gss_acquire_cred(3gss)

gss_process_context_token(3gss)

Passes a context to the security service.

Syntax

OM_uint32 gss_process_context_token(
minor _status,
context _handle,
input _token_buffer )

Argument Data Type Access
minor_status OM_uint32 write
context_handle gss_ctx_id_t read
input_token_buffer gss_buffer_t read

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_process_context_token (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_buffer_t input_token_buffer)


Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the context handle on which the security service processes the token.

input_token_buffer

Specifies an opaque pointer to the first byte of the token to be processed.

Description

The gss_process_context_token() routine passes tokens generated by the gss_delete_security_context() routine to the security service.

Usually, tokens are associated with either the context establishment or with per-message security services. If the tokens are associated with the context establishment, they are passed to the gss_init_sec_context() or gss_accept_sec_context() routine. If the tokens are associated with the per-message security service, they are passed to the gss_verify() or gss_unseal() routine. Tokens generated by the gss_delete_security_context() routine are passed by the gss_process_context_token() routine to the security service for processing.


Return Values

Possible return values are as follows:
Return Description
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the input_token parameter failed.
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.

See Also

gss_delete_security_context(3gss)

gss_release_buffer(3gss)

Frees storage associated with a buffer.

Syntax

OM_uint32 gss_release_buffer(
minor _status,
buffer )

Argument Data Type Access
minor_status OM_uint32 write
buffer gss_buffer_t write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_release_buffer (
OM_uint32 *minor_status,
gss_buffer_t buffer)


Arguments

minor_status

Returns a status code from the security mechanism.

buffer

Returns the storage associated with the buffer to delete.

Description

The gss_release_buffer() routine deletes the buffer by freeing the storage associated with it.

Return Values

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 for details.

See Also

None.

gss_release_cred(3gss)

Marks a credential for deletion.

Syntax

OM_uint32 gss_release_cred(
minor _status,
output _cred_handle )

Argument Data Type Access
minor_status OM_uint32 write
output_cred_handle gss_cred_id_t read

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_release_cred (
OM_uint32 *minor_status,
gss_cred_id_t *output_cred_handle)


Arguments

minor_status

Returns a status code from the security mechanism.

output_cred_handle

Specifies the buffer containing the opaque credential handle. This information is optional. To release the default credential, specify GSS_C_NO_CREDENTIAL.

Description

The gss_release_cred() routine informs the GSSAPI that a credential is no longer required and marks it for deletion.

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.
GSS_S_NO_CRED The credentials could not be accessed.

See Also

None.

gss_release_name(3gss)

Frees storage associated with an internal name that was allocated by a GSSAPI routine.

Syntax

OM_uint32 gss_release_name(
minor _status,
name )

Argument Data Type Access
minor_status OM_uint32 write
name gss_name_t write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_release_name (
OM_uint32 *minor_status,
gss_name_t *name)


Arguments

minor_status

Returns a status code from the security mechanism.

name

Returns the name to delete.

Description

The gss_release_name() routine deletes the internal name by freeing the storage associated with that internal name and with the gss_import_name() routine.

Return Values

Possible return values are as follows:
Return Description
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_NAME The name parameter did not contain a valid name.
GSS_S_FAILURE The routine failed. Check the minor status for details.

See Also

gss_compare_name(3gss)
gss_display_name(3gss)
gss_import_name(3gss)

gss_release_oid_set(3gss)

Frees storage associated with a gss_OID_set object.

Syntax

OM_uint32 gss_release_oid_set(
minor _status,
set )

Argument Data Type Access
minor_status OM_uint32 write
set gss_OID_set write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_release_oid_set (
OM_uint32 *minor_status,
gss_OID_set set)


Arguments

minor_status

Returns a status code from the security mechanism.

set

Returns the storage to delete. The storage is associated with the gss_OID_set parameter and was allocated by a GSSAPI routine.

Description

The gss_release_oid_set() routine frees storage that is associated with the gss_OID_set parameter and was allocated by a GSSAPI 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.

gss_seal(3gss)

Cryptographically signs, and optionally encrypts, a message.

Syntax

OM_uint32 gss_seal(
minor _status,
context _handle,
conf _req_flag,
qop _req,
input _message_buffer,
conf _state,
output _message_buffer )

Argument Data Type Access
minor_status OM_uint32 write
context_handle gss_ctx_id_t read
conf_req_flag int read
qop_req int read
input_message_buffer gss_buffer_t read
conf_state int write
output_message_buffer gss_buffer_t write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_seal (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
int conf_req_flag,
int qop_req,
gss_buffer_t input_message_buffer,
int *conf_state,
gss_buffer_t output_message_buffer)


Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the context on which the message is sent.

conf_req_flag

Specifies the requested level of confidentiality and integrity services, as follows:
True Both confidentiality and integrity services are requested.
False Only integrity services are requested.

qop_req

Specifies the cryptographic algorithm, or quality of protection. Specify GSS_C_QOP_DEFAULT. The DCE GSSAPI supports only one quality of protection. Alternatives to this for all qop parameters are GSS_C_QOP_MD5, GSS_C_QOP_DES_MD5, GSS_C_QOP_MAC.

input_message_buffer

Specifies the message to seal.

conf_state

Returns the requested level of confidentiality and integrity services, as follows:
True Confidentiality, data origin, authentification, and integrity services have been applied.
False Only integrity and data origin services have been applied.

output_message_buffer

Returns the buffer to receive the sealed message.

Description

The gss_seal() routine cryptographically signs and optionally encrypts the message. The output_message parameter contains both the signature and the message.

While the qop_req parameter enables a choice between several qualities of protection, DCE GSSAPI supports only one quality of protection. If you specify an unsupported protection, the gss_seal() routine returns a status of GSS_S_FAILURE. Alternatives to this for all qop parameters are GSS_C_QOP_MD5, GSS_C_QOP_DES_MD5, GSS_C_QOP_MAC.


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. The context identified in the context_handle parameter was not valid.
GSS_S_NO_CONTEXT The context identified in the context_handle parameter was not valid.

gss_sign(3gss)

Generates a cryptographic signature for a message.

Syntax

OM_uint32 gss_sign(
minor _status,
context _handle,
qop _req,
message _buffer,
msg _token )

Argument Data Type Access
minor_status OM_uint32 write
context_handle gss_ctx_id_t read
qop_req int read
message_buffer gss_buffer_t read
msg_token gss_buffer_t write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_sign (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
int qop_req,
gss_buffer_t message_buffer,
gss_buffer_t msg_token)


Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the context on which the message is sent.

qop_req

Specifies the cryptographic algorithm, or quality of protection. Specify GSS_C_QOP_DEFAULT. DCE GSSAPI supports only one quality of protection. Alternatives to this for all qop parameters are GSS_C_QOP_MD5, GSS_C_QOP_DES_MD5, GSS_C_QOP_MAC.

message_buffer

Specifies the message to send.

msg_token

Returns the buffer to receive the signature token to transfer to the context acceptor.

Description

The gss_sign() routine generates an encrypted signature for a message. It places the signature in a token for transfer to the context acceptor.

Although the qop_req parameter enables a choice between several qualities of protection, DCE GSSAPI supports only one quality of protection. If you specify an unsupported protection, the gss_sign() routine returns a status of GSS_S_FAILURE. Alternatives to this for all qop parameters are GSS_C_QOP_MD5, GSS_C_QOP_DES_MD5, GSS_C_QOP_MAC.


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. The context specified in the context_handle parameter was not valid.
GSS_S_NO_CONTEXT The context identified in the context_handle parameter was not valid.

gss_unseal(3gss)

Converts a sealed message into a usable form and verifies the embedded signature.

Syntax

OM_uint32 gss_unseal(
minor _status,
context _handle,
input _message_buffer,
output _message_buffer,
conf _state,
qop _state )

Argument Data Type Access
minor_status OM_uint32 write
context_handle gss_ctx_id_t read
input_message_buffer gss_buffer_t read
output_message_buffer gss_buffer_t read
conf_state int write
qop_state int write

C Binding

#include <DCE/GSSAPI.H>


OM_uint32 gss_unseal (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
gss_buffer_t input_message_buffer,
gss_buffer_t output_message_buffer,
int *conf_state,
int *qop_state)


Arguments

minor_status

Returns a status code from the security mechanism.

context_handle

Specifies the context on which the message arrived.

input_message_buffer

Specifies the sealed message.

output_message_buffer

Specifies the buffer to receive the unsealed message.

conf_state

Returns the requested level of confidentiality and integrity services, as follows:
True Both confidentiality and integrity services are requested.
False Only integrity services are requested.

qop_state

Returns the cryptographic algorithm, or quality of protection.

Description

The gss_unseal() routine converts a sealed message to a usable form and verifies the embedded signature. The conf_state parameter indicates whether the message was encrypted. The qop_state parameter indicates the quality of protection.

Return Values

Possible return values are as follows:
Return Description
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_SIG The signature was incorrect.
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_DEFECTIVE_TOKEN The token failed consistency checks.
GSS_S_DUPLICATE_TOKEN The token was valid and contained the correct signature but it had already been processed.
GSS_S_FAILURE The routine failed. The context specified in the context_handle parameter was not valid.
GSS_S_NO_CONTEXT The context identified in the context_handle parameter was not valid.
GSS_S_OLD_TOKEN The token was valid and contained the correct signature but it is too old.
GSS_S_UNSEQ_TOKEN The token was valid and contained the correct signature but it has been verified out of sequence. An earlier token signed or sealed by the remote application has not been processed locally.
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)


Previous Next Contents Index