| 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) |
| minor_status | The status code returned by the underlying mechanism. |
| context_handle | The context under which the message will be sent. |
| message_buffer | The received 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. |
| token_buffer | The token containing the received MIC. This argument must be in the form of a gss_buffer_desc object; see "Strings and Similar Data". This buffer must be freed up with gss_release_buffer() when the application has finished with it. |
| qop_state | The QOP (Quality of Protection) that was applied in generating the MIC. Specify NULL if not required. |
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:
The initiator tags the message with gss_get_mic().
The initiator sends the message and MIC to the acceptor.
The acceptor verifies the message with gss_verify_mic().
The acceptor sends the MIC back to the initiator.
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:
The initiator wraps the message with gss_wrap().
The initiator sends the wrapped message.
The acceptor unwraps the message with gss_unwrap().
The acceptor calls gss_get_mic() to produce a MIC for the unwrapped message.
The acceptor sends the derived MIC to the initiator.
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) |
| minor_status | The status code returned by the underlying mechanism. |
| context_handle | The context to delete. |
| output_token | Should be set to GSS_C_NO_BUFFER. |
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.