HP Open Source Security for OpenVMS Volume 3: Kerberos > Chapter 5 GSSAPI (Generic Security Services Application Programming Interface)

gss_get_mic — Generate a cryptographic MIC for a message

  Table of Contents

  Glossary

  Index

C Prototype

OM_uint32 gss_get_mic(
OM_uint32 * minor_status,
gss_ctx_id_t context_handle,
gss_qop_t qop_req,
gss_buffer_t message_buffer,
gss_buffer_t message_token );

Arguments

minor_status (output) 

An implementation-specific status code.

context_handle (input)  

Identifies the context on which the message will be sent.

qop_req (input) 

Specifies the requested quality of protection. Callers are encouraged, on portability grounds, to accept the default quality of protection offered by the chosen mechanism, which may be requested by specifying GSS_C_QOP_DEFAULT for this argument. If an unsupported protection strength is requested, gss_get_mic will return a status of GSS_S_BAD_QOP.

message_buffer (input) 

The message to be protected.

message_token (output) 

A buffer to receive the token. The application must free storage associated with this buffer after use with a call to gss_release_buffer.

Description

This routine supports data origin authentication and data integrity services. When gss_get_mic is invoked on an input message, it generates a cryptographic MIC, and places the MIC in a per-message token containing data items that allow underlying mechanisms to provide the specified security services. The original message, along with the generated per-message token, is passed to the remote peer; these two data elements are processed by gss_verify_mic, which validates the message in conjunction with the separate token. The qop_req argument allows a choice between several cryptographic algorithms.

This routine is functionally equivalent to the gss_sign routine. New code should use gss_get_mic instead of gss_sign. Although both routines are supported, gss_sign has been deprecated in the GSSAPI Version 2 specification.

Return Values

This routine returns one of the following GSS status codes:

GSS_S_COMPLETE

Indicates that an integrity check, suitable for an established security context, was successfully applied and that the message and corresponding per_msg_token are ready for transmission.
GSS_S_CONTEXT_EXPIREDIndicates that context-related data items have expired, so that the requested operation cannot be performed.
GSS_S_NO_CONTEXTIndicates that the context_handle argument did not identify a valid context.
GSS_S_BAD_QOPIndicates that the provided QOP value is not recognized or supported for the context.