gss_unwrap(3)gss_unwrap(3)NAMEgss_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
Kerberos 5 error code. Security context that contains the session key
used to decrypt the message and verify its checksum. Protected message
to be unwrapped and verified. Buffer that receives the unwrapped mes‐
sage.
Storage associated with this buffer must be freed by the appli‐
cation after use with a call to gss_release_buffer(). Protec‐
tion 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. 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 mes‐
sages 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 Applica‐
tion 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 sup‐
plementary 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
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_DEFECTIVE_TOKEN xx09xxxx
GSS_S_DUPLICATE_TOKEN xxxx0002
GSS_S_FAILURE xx0Dxxxx
GSS_S_NO_CONTEXT xx08xxxx
GSS_S_OLD_TOKEN xxxx0004
GSS_S_UNSEQ_TOKEN xxxx0008
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)gss_unwrap(3)
