Message Tagging With gss_get_mic()

Programs can use gss_get_mic() to add a cryptographic MIC to a message; the recipient can check this MIC to see if the received message is the same as the one that was sent by calling gss_verify_mic(). gss_get_mic() has the following form:

OM_uint32 gss_get_mic (
OM_uint32          *minor_status,
const gss_ctx_id_t context_handle,
gss_qop_t          qop_req,
const gss_buffer_t message_buffer,
gss_buffer_t       msg_token)

minor_status

The status code returned by the underlying mechanism.

context_handle

The context under which the message will be sent.

qop_req

A requested QOP (Quality of Protection). This is the cryptographic algorithm used in generating the MIC. For portability's sake, applications should specify the default QOP by setting this argument to GSS_C_QOP_DEFAULT whenever possible. (See Appendix C, Specifying an OID on specifying a non-default QOP.)

message_buffer

The message to be tagged with a MIC. This argument must be in the form of a gss_buffer_desc object; see Strings and Similar Data. Must be freed up with gss_release_buffer() when you have finished with it.

msg_token

The token containing the message and its MIC. This must be freed up with gss_release_buffer() when you have finished with it.

Note that gss_get_mic() produces separate output for the message and the MIC. (This is different from gss_wrap(), which bundles them together as output.) This separation means that a sender application must arrange to send both the message and its MIC. More significantly, the receiving application must be able to receive and distinguish the message and the MIC. Ways to ensure the proper processing of message and MIC include:

• Through program control (that is, state). A recipient application might know to call its receiving function twice, once to get a message, once to get the message's MIC.

• Through flags. Sending and receiving functions can flag what kind of token they're including.

• Through user-defined token structures that might include both message and MIC.

gss_get_mic() returns GSS_S_COMPLETE if it completes successfully. If the specified QOP is not valid, it returns GSS_S_BAD_QOP. For more information, see the gss_get_mic(3GSS) man page.