NAME

gss_unwrap − Converts a protected message to a usable form. 

SYNOPSIS

#include <gssapi/gssapi.h>
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 );

PARAMETERS

minor_status
Kerberos 5 error code.

context_handle
Security context that contains the session key used to decrypt the message and verify its checksum.

input_message_buffer
Protected message to be unwrapped and verified.

output_message_buffer
Buffer that receives the unwrapped message.

Storage associated with this buffer must be freed by the application after use with a call to gss_release_buffer(). 

conf_state
Protection used when the message was wrapped, that is, encrypted to ensure confidentiality. Specify NULL if this information is not required. 

       •Non-zero −− encryption used. 

       •Zero −− encryption not used. 

qop_state
Quality of protection (QOP) provided:

       •If the GSS_KRB5-C-CONF-QOP-DES confidentiality QOP was used to wrap the message, GSS_KRB5-C-INTEG-QOP-DES-MD5 is returned. 

       •If the CSF_GSS_KRB5_C_CONF_QOP_DES3 confidentiality QOP was used to wrap the message, CSF_GSS_KRB5_C_INTEG_QOP_DES3_MD5 is returned. 

Specify NULL if this information is not required.  gss_wrap() contains more information about QOPs. 

DESCRIPTION

The gss_unwrap() function converts a previously protected message back to a usable form by:

       •Verifying the checksum to check message integrity. 

       •Decrypting the message if confidentiality was used. 

This function is used in conjunction with gss_wrap() to protect messages when they are transferred between an application and its peer. 

The conf_state parameter indicates whether the message was encrypted; the qop_state parameter indicates the strength of protection that was used to provide the confidentiality and integrity services.  gss_wrap() contains more information about QOPs. 

Note

This function is a direct replacement for the gss_unseal() function used in GSS-API version 1 compliant products, including the HP Application Security Toolkit. 

If the function returns GSS_S_COMPLETE, the message has been decrypted and the checksum in the token verified successfully. 

If the function returns GSS_S_FAILURE, the token may be out-of-sequence, old, or a replay. To check for these conditions in the supplementary information fields, AND the major status code with a named identifier. 

Storage associated with the output message buffer must be freed by the application after use with a call to gss_release_buffer(). 

RETURN VALUES

PORTABILITY CONSIDERATIONS

Since the HP implementation of DES3 is an extension of the GSS-API, it will not interoperate with other GSS-API vendors offering DES3. 

SEE ALSO

Functions:  gss_accept_sec_context(3), gss_init_sec_context(3), gss_release_buffer(3), gss_wrap(3)