gss_unwrap()

gss_unwrap() looks like this:

OM_uint32 gss_unwrap ( OM_uint32 *minor_status, const gss_ctx_id_t context_handle, const gss_buffer_t input_message_buffer, gss_buffer_t output_message_buffer, int *conf_state gss_qop_t *qop_state)

minor_status	The status code returned by the underlying security mechanism.
context_handle	The context under which this message will be sent.
input_message_buffer	The wrapped message. 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.
output_message_buffer	The buffer for the unwrapped wrapped message. After the application is done with the unwrapped message, it must release this buffer with gss_release_buffer(). This argument is also a gss_buffer_desc object.
conf_state	A flag that indicates whether confidentiality was applied or not. If non-zero, then confidentiality, message origin authentication, and integrity services were applied. If zero, only message-origin authentication and integrity were applied. Specify NULL if not required.
qop_state	The QOP (Quality of Protection) used. This is the cryptographic algorithm used in generating the MIC and doing the encryption. Specify NULL if not required.

gss_unwrap() returns GSS_S_COMPLETE if the message was successfully unwrapped. If it cannot verify the message against its MIC, it returns GSS_S_BAD_SIG.

gss_verify_mic()

If a message has been unwrapped, or if it was never wrapped in the first place, it can be verified with gss_verify_mic(). gss_verify_mic() looks like this:

OM_uint32 gss_verify_mic (
OM_uint32          *minor_status,
const gss_ctx_id_t context_handle,
const gss_buffer_t message_buffer,
const gss_buffer_t token_buffer,
gss_qop_t          qop_state)

gss_verify_mic() returns GSS_S_COMPLETE if the message was successfully verified. If it cannot verify the message against its MIC, it returns GSS_S_BAD_SIG.

Transmission Confirmation (Optional)

After the recipient has unwrapped or verified the transmitted message, it might want to send a confirmation to the sender. This means sending back a MIC for that message. Consider the case of a message that was not wrapped by the sender, but only tagged with a MIC with gss_get_mic(). The process, illustrated in Figure 1-14, is as follows:

1. The initiator tags the message with gss_get_mic().

2. The initiator sends the message and MIC to the acceptor.

3. The acceptor verifies the message with gss_verify_mic().

4. The acceptor sends the MIC back to the initiator.

5. The initiator verifies the received MIC against the original message with gss_verify_mic().

Figure 1-14 Confirming MIC'd Data

In the case of wrapped data, the gss_unwrap() function never produces a separate MIC, so the recipient must generate it from the received (and unwrapped) message. The process, illustrated in Figure 1-15, is as follows:

1. The initiator wraps the message with gss_wrap().

2. The initiator sends the wrapped message.

3. The acceptor unwraps the message with gss_unwrap().

4. The acceptor calls gss_get_mic() to produce a MIC for the unwrapped message.

5. The acceptor sends the derived MIC to the initiator.

6. The initiator compares the received MIC against the original message with gss_verify_mic().

Figure 1-15 Confirming Wrapped Data

Context Deletion and Data Deallocation

After all messages have been sent and received, and the initiator and acceptor applications have finished, both applications should call gss_delete_sec_context() to destroy their shared context. gss_delete_sec_context() deletes local data structures associated with the context. gss_delete_sec_context() looks like this:

OM_uint32 gss_delete_sec_context (
OM_uint32    *minor_status,
gss_ctx_id_t *context_handle,
gss_buffer_t output_token)

See the gss_delete_sec_context(3GSS) man page for more information.

For good measure, applications should be sure to deallocate any data space they have allocated for GSS-API data. The functions that do this are gss_release_buffer(), gss_release_cred(), gss_release_name(), and gss_release_oid_set(). See their man pages for more information.