NAME    [Toc]    [Back]

       gss_unwrap  -  Converts  a  protected  message to a usable
       form.

SYNOPSIS    [Toc]    [Back]

       #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    [Toc]    [Back]

       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 message.

              Storage  associated  with this buffer must be freed
              by  the  application  after  use  with  a  call  to
              gss_release_buffer().   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.  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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

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



                                                    gss_unwrap(3)