Generic Security Services API Library Functions  gssunwrap(3GS)



NAME
     gssunwrap - verify a message  with  attached  cryptographic
     message

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

     OMuint32 gssunwrap(OMuint32 *minorstatus,
          const gssctxidt contexthandle,
          const gssbuffert inputmessagebuffer,
          gssbuffert outputmessagebuffer, int *confstate,
          gssqopt *qopstate);


DESCRIPTION
     The gssunwrap() function converts a message previously pro-
     tected  by  gsswrap(3GS)  back to a usable form, verifying
     the embedded MIC. The confstate parameter indicates whether
     the message was encrypted; the qopstate 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 gsswrap(3GS) to provide secure framing,
     the GS-API supports the wrapping and  unwrapping  of  zero-
     length messages.

PARAMETERS
     The parameter descriptions for gssunwrap() follow:

     minorstatus             The status  code  returned  by  the
                              underlying mechanism.


     contexthandle           Identifies the context on which the
                              message arrived.


     inputmessagebuffer     The message to be protected.


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


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



SunOS 5.11          Last change: 15 Jan 2003                    1






Generic Security Services API Library Functions  gssunwrap(3GS)



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


     qopstate                Specifies the quality of protection
                              provided.   Specify  NUL  if  this
                              parameter is not required.


ERORS
     gssunwrap() may return the following status codes:

     GSCOMPLETE           Successful completion.


     GSDEFECTIVETOKEN    The   token   failed    consistency
                              checks.


     GSBADSIG            The MIC was incorrect.


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


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


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


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


     GSCONTEXTEXPIRED    The context has already expired.





SunOS 5.11          Last change: 15 Jan 2003                    2






Generic Security Services API Library Functions  gssunwrap(3GS)



     GSNOCONTEXT         The  contexthandle  parameter  did
                              not identify a valid context.


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


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWgss (32-bit)            
    
                                  SUNWgssx (64-bit)           
    
     MT-Level                     Safe                        
    


SEE ALSO
     gssreleasebuffer(3GS), gsswrap(3GS), attributes(5)


     Solaris Security for Developers Guide




















SunOS 5.11          Last change: 15 Jan 2003                    3