Index for Section 3

Alphabetical listing for G

Bottom of page

gss_unwrap(3)
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
  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)

Index for Section 3

Alphabetical listing for G

Top of page