share/man/man3gss/gss_unwrap.3gss

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GSS_UNWRAP 3GSS "Jan 15, 2003"
   7 .SH NAME
   8 gss_unwrap \- verify a message with attached cryptographic message
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_unwrap\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR,
  17      \fBconst gss_buffer_t\fR \fIinput_message_buffer\fR,
  18      \fBgss_buffer_t\fR \fIoutput_message_buffer\fR, \fBint *\fR\fIconf_state\fR,
  19      \fBgss_qop_t *\fR\fIqop_state\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBgss_unwrap()\fR function converts a message previously protected by
  26 \fBgss_wrap\fR(3GSS) back to a usable form, verifying the embedded \fBMIC\fR.
  27 The \fIconf_state\fR parameter indicates whether the message was encrypted; the
  28 \fIqop_state\fR parameter indicates the strength of protection that was used to
  29 provide the confidentiality and integrity services.
  30 .sp
  31 .LP
  32 Since some application-level protocols may wish to use tokens emitted by
  33 \fBgss_wrap\fR(3GSS) to provide secure framing, the \fBGSS-API\fR supports the
  34 wrapping and unwrapping of zero-length messages.
  35 .SH PARAMETERS
  36 .sp
  37 .LP
  38 The parameter descriptions for \fBgss_unwrap()\fR follow:
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIminor_status\fR\fR
  43 .ad
  44 .RS 25n
  45 The status code returned by the underlying mechanism.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIcontext_handle\fR\fR
  52 .ad
  53 .RS 25n
  54 Identifies the context on which the message arrived.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fIinput_message_buffer\fR\fR
  61 .ad
  62 .RS 25n
  63 The message to be protected.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIoutput_message_buffer\fR\fR
  70 .ad
  71 .RS 25n
  72 The buffer to receive the unwrapped message. Storage associated with this
  73 buffer must be freed by the application after use with a call to
  74 \fBgss_release_buffer\fR(3GSS).
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIconf_state\fR\fR
  81 .ad
  82 .RS 25n
  83 If the value of \fIconf_state\fR is non-zero, then confidentiality and
  84 integrity protection were used. If the value is zero, only integrity service
  85 was used. Specify \fBNULL\fR if this parameter is not required.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIqop_state\fR\fR
  92 .ad
  93 .RS 25n
  94 Specifies the quality of protection provided. Specify \fBNULL\fR if this
  95 parameter is not required.
  96 .RE
  97
  98 .SH ERRORS
  99 .sp
 100 .LP
 101 \fBgss_unwrap()\fR may return the following status codes:
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBGSS_S_COMPLETE\fR\fR
 106 .ad
 107 .RS 25n
 108 Successful completion.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBGSS_S_DEFECTIVE_TOKEN\fR\fR
 115 .ad
 116 .RS 25n
 117 The token failed consistency checks.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBGSS_S_BAD_SIG\fR\fR
 124 .ad
 125 .RS 25n
 126 The \fBMIC\fR was incorrect.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBGSS_S_DUPLICATE_TOKEN\fR\fR
 133 .ad
 134 .RS 25n
 135 The token was valid, and contained a correct \fBMIC\fR for the message, but it
 136 had already been processed.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBGSS_S_OLD_TOKEN\fR\fR
 143 .ad
 144 .RS 25n
 145 The token was valid, and contained a correct \fBMIC\fR for the message, but it
 146 is too old to check for duplication.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBGSS_S_UNSEQ_TOKEN\fR\fR
 153 .ad
 154 .RS 25n
 155 The token was valid, and contained a correct \fBMIC\fR for the message, but has
 156 been verified out of sequence; a later token has already been received.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBGSS_S_GAP_TOKEN\fR\fR
 163 .ad
 164 .RS 25n
 165 The token was valid, and contained a correct \fBMIC\fR for the message, but has
 166 been verified out of sequence; an earlier expected token has not yet been
 167 received.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR
 174 .ad
 175 .RS 25n
 176 The context has already expired.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBGSS_S_NO_CONTEXT\fR\fR
 183 .ad
 184 .RS 25n
 185 The \fIcontext_handle\fR parameter did not identify a valid context.
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBGSS_S_FAILURE\fR\fR
 192 .ad
 193 .RS 25n
 194 The underlying mechanism detected an error for which no specific \fBGSS\fR
 195 status code is defined.  The mechanism-specific status code reported by means
 196 of the \fIminor_status\fR parameter details the error condition.
 197 .RE
 198
 199 .SH ATTRIBUTES
 200 .sp
 201 .LP
 202 See \fBattributes\fR(5)  for descriptions of the following attributes:
 203 .sp
 204
 205 .sp
 206 .TS
 207 box;
 208 c | c
 209 l | l .
 210 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 211 _
 212 MT-Level        Safe
 213 .TE
 214
 215 .SH SEE ALSO
 216 .sp
 217 .LP
 218 \fBgss_release_buffer\fR(3GSS), \fBgss_wrap\fR(3GSS), \fBattributes\fR(5)
 219 .sp
 220 .LP
 221 \fISolaris Security for Developers Guide\fR