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