Manual Pages for UNIX Operating System command usage for man gss_unwrap

Generic Security Services API Library Functions  gss_unwrap(3GSS)



NAME
     gss_unwrap - verify a message  with  attached  cryptographic
     message

SYNOPSIS
     cc [ flag... ] file... -lgss  [ library... ]
     #include 

     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);


DESCRIPTION
     The gss_unwrap() function converts a message previously pro-
     tected  by  gss_wrap(3GSS)  back to a usable form, verifying
     the embedded MIC. 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 con-
     fidentiality and integrity services.


     Since some  application-level  protocols  may  wish  to  use
     tokens  emitted by gss_wrap(3GSS) to provide secure framing,
     the GSS-API supports the wrapping and  unwrapping  of  zero-
     length messages.

PARAMETERS
     The parameter descriptions for gss_unwrap() follow:

     minor_status             The status  code  returned  by  the
                              underlying mechanism.


     context_handle           Identifies the context on which the
                              message arrived.


     input_message_buffer     The message to be protected.


     output_message_buffer    The buffer to receive the unwrapped
                              message.  Storage  associated  with
                              this buffer must be  freed  by  the
                              application  after  use with a call
                              to gss_release_buffer(3GSS).


     conf_state               If the value of conf_state is  non-
                              zero,   then   confidentiality  and



SunOS 5.11          Last change: 15 Jan 2003                    1






Generic Security Services API Library Functions  gss_unwrap(3GSS)



                              integrity protection were used.  If
                              the  value  is zero, only integrity
                              service was used. Specify  NULL  if
                              this parameter is not required.


     qop_state                Specifies the quality of protection
                              provided.   Specify  NULL  if  this
                              parameter is not required.


ERRORS
     gss_unwrap() may return the following status codes:

     GSS_S_COMPLETE           Successful completion.


     GSS_S_DEFECTIVE_TOKEN    The   token   failed    consistency
                              checks.


     GSS_S_BAD_SIG            The MIC was incorrect.


     GSS_S_DUPLICATE_TOKEN    The token was valid, and  contained
                              a  correct MIC for the message, but
                              it had already been processed.


     GSS_S_OLD_TOKEN          The token was valid, and  contained
                              a  correct MIC for the message, but
                              it is too old to check for duplica-
                              tion.


     GSS_S_UNSEQ_TOKEN        The token was valid, and  contained
                              a  correct MIC for the message, but
                              has been verified out of  sequence;
                              a  later  token  has  already  been
                              received.


     GSS_S_GAP_TOKEN          The token was valid, and  contained
                              a  correct MIC for the message, but
                              has been verified out of  sequence;
                              an  earlier  expected token has not
                              yet been received.


     GSS_S_CONTEXT_EXPIRED    The context has already expired.





SunOS 5.11          Last change: 15 Jan 2003                    2






Generic Security Services API Library Functions  gss_unwrap(3GSS)



     GSS_S_NO_CONTEXT         The  context_handle  parameter  did
                              not identify a valid context.


     GSS_S_FAILURE            The underlying  mechanism  detected
                              an  error for which no specific GSS
                              status  code   is   defined.    The
                              mechanism-specific    status   code
                              reported   by    means    of    the
                              minor_status  parameter details the
                              error condition.


ATTRIBUTES
     See attributes(5)  for descriptions of the following  attri-
     butes:



     ____________________________________________________________________
    |       ATTRIBUTE TYPE        |           ATTRIBUTE VALUE           |
    |_____________________________|_____________________________________|
    | Availability                | system/library/security/gss (32-bit)|
    |_____________________________|_____________________________________|
    |                             | SUNWgssx (64-bit)                   |
    |_____________________________|_____________________________________|
    | MT-Level                    | Safe                                |
    |_____________________________|_____________________________________|


SEE ALSO
     gss_release_buffer(3GSS), gss_wrap(3GSS), attributes(5)


     Oracle Solaris Security for Developers Guide




















SunOS 5.11          Last change: 15 Jan 2003                    3