usr/src/man/man3gss/gss_verify_mic.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_VERIFY_MIC 3GSS "Jan 15, 2003"
   7 .SH NAME
   8 gss_verify_mic \- verify integrity of a received 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_verify_mic\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR, \fBconst gss_buffer_t\fR \fImessage_buffer\fR,
  17      \fBconst gss_buffer_t\fR \fItoken_buffer\fR, \fBgss_qop_t *\fR\fIqop_state\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBgss_verify_mic()\fR function verifies that a cryptographic \fBMIC\fR,
  24 contained in the token parameter, fits the supplied message. The
  25 \fIqop_state\fR parameter allows a message recipient to determine the strength
  26 of protection that was applied to the message.
  27 .sp
  28 .LP
  29 Since some application-level protocols may wish to use tokens emitted by
  30 \fBgss_wrap\fR(3GSS) to provide secure framing, the \fBGSS-API\fR supports the
  31 calculation and verification of \fBMIC\fRs over zero-length messages.
  32 .SH PARAMETERS
  33 .sp
  34 .LP
  35 The parameter descriptions for \fBgss_verify_mic()\fR follow:
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIminor_status\fR\fR
  40 .ad
  41 .RS 18n
  42 The status code returned by the underlying mechanism.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIcontext_handle\fR\fR
  49 .ad
  50 .RS 18n
  51 Identifies the context on which the message arrived.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fImessage_buffer\fR\fR
  58 .ad
  59 .RS 18n
  60 The message to be verified.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fItoken_buffer\fR\fR
  67 .ad
  68 .RS 18n
  69 The token associated with the message.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fIqop_state\fR\fR
  76 .ad
  77 .RS 18n
  78 Specifies the quality of protection gained from the \fBMIC\fR. Specify
  79 \fBNULL\fR if this parameter is not required.
  80 .RE
  81
  82 .SH ERRORS
  83 .sp
  84 .LP
  85 \fBgss_verify_mic()\fR may return the following status codes:
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBGSS_S_COMPLETE\fR\fR
  90 .ad
  91 .RS 25n
  92 Successful completion.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBGSS_S_DEFECTIVE_TOKEN\fR\fR
  99 .ad
 100 .RS 25n
 101 The token failed consistency checks.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBGSS_S_BAD_SIG\fR\fR
 108 .ad
 109 .RS 25n
 110 The \fBMIC\fR was incorrect.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBGSS_S_DUPLICATE_TOKEN\fR\fR
 117 .ad
 118 .RS 25n
 119 The token was valid and contained a correct \fBMIC\fR for the message, but it
 120 had already been processed.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBGSS_S_OLD_TOKEN\fR\fR
 127 .ad
 128 .RS 25n
 129 The token was valid and contained a correct \fBMIC\fR for the message, but it
 130 is too old to check for duplication.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBGSS_S_UNSEQ_TOKEN\fR\fR
 137 .ad
 138 .RS 25n
 139 The token was valid and contained a correct \fBMIC\fR for the message, but it
 140 has been verified out of sequence; a later token has already been received.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBGSS_S_GAP_TOKEN\fR\fR
 147 .ad
 148 .RS 25n
 149 The token was valid and contained a correct \fBMIC\fR for the message, but it
 150 has been verified out of sequence; an earlier expected token has not yet been
 151 received.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR
 158 .ad
 159 .RS 25n
 160 The context has already expired.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBGSS_S_NO_CONTEXT\fR\fR
 167 .ad
 168 .RS 25n
 169 The \fIcontext_handle\fR parameter did not identify a valid context.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBGSS_S_FAILURE\fR\fR
 176 .ad
 177 .RS 25n
 178 The underlying mechanism detected an error for which no specific \fBGSS\fR
 179 status code is defined.  The mechanism-specific status code reported by means
 180 of the \fIminor_status\fR parameter details the error condition.
 181 .RE
 182
 183 .SH ATTRIBUTES
 184 .sp
 185 .LP
 186 See \fBattributes\fR(5)  for descriptions of the following attributes:
 187 .sp
 188
 189 .sp
 190 .TS
 191 box;
 192 c | c
 193 l | l .
 194 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 195 _
 196 MT-Level        Safe
 197 .TE
 198
 199 .SH SEE ALSO
 200 .sp
 201 .LP
 202 \fBgss_wrap\fR(3GSS), \fBattributes\fR(5)
 203 .sp
 204 .LP
 205 \fISolaris Security for Developers Guide\fR