|
1 '\" te |
|
2 .\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. |
|
3 .TH gss_unwrap 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions" |
|
4 .SH NAME |
|
5 gss_unwrap \- verify a message with attached cryptographic 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_unwrap\fR(\fBOM_uint32 *\fR\fIminor_status\fR, |
|
13 \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR, |
|
14 \fBconst gss_buffer_t\fR \fIinput_message_buffer\fR, |
|
15 \fBgss_buffer_t\fR \fIoutput_message_buffer\fR, \fBint *\fR\fIconf_state\fR, |
|
16 \fBgss_qop_t *\fR\fIqop_state\fR); |
|
17 .fi |
|
18 |
|
19 .SH DESCRIPTION |
|
20 .sp |
|
21 .LP |
|
22 The \fBgss_unwrap()\fR function converts a message previously protected by \fBgss_wrap\fR(3GSS) back to a usable form, verifying the embedded \fBMIC\fR. The \fIconf_state\fR parameter indicates whether the message was encrypted; the \fIqop_state\fR parameter indicates the strength of protection that was used to provide the confidentiality and integrity services. |
|
23 .sp |
|
24 .LP |
|
25 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 wrapping and unwrapping of zero-length messages. |
|
26 .SH PARAMETERS |
|
27 .sp |
|
28 .LP |
|
29 The parameter descriptions for \fBgss_unwrap()\fR follow: |
|
30 .sp |
|
31 .ne 2 |
|
32 .mk |
|
33 .na |
|
34 \fB\fIminor_status\fR\fR |
|
35 .ad |
|
36 .RS 25n |
|
37 .rt |
|
38 The status code returned by the underlying mechanism. |
|
39 .RE |
|
40 |
|
41 .sp |
|
42 .ne 2 |
|
43 .mk |
|
44 .na |
|
45 \fB\fIcontext_handle\fR\fR |
|
46 .ad |
|
47 .RS 25n |
|
48 .rt |
|
49 Identifies the context on which the message arrived. |
|
50 .RE |
|
51 |
|
52 .sp |
|
53 .ne 2 |
|
54 .mk |
|
55 .na |
|
56 \fB\fIinput_message_buffer\fR\fR |
|
57 .ad |
|
58 .RS 25n |
|
59 .rt |
|
60 The message to be protected. |
|
61 .RE |
|
62 |
|
63 .sp |
|
64 .ne 2 |
|
65 .mk |
|
66 .na |
|
67 \fB\fIoutput_message_buffer\fR\fR |
|
68 .ad |
|
69 .RS 25n |
|
70 .rt |
|
71 The buffer to receive the unwrapped message. Storage associated with this buffer must be freed by the application after use with a call to \fBgss_release_buffer\fR(3GSS). |
|
72 .RE |
|
73 |
|
74 .sp |
|
75 .ne 2 |
|
76 .mk |
|
77 .na |
|
78 \fB\fIconf_state\fR\fR |
|
79 .ad |
|
80 .RS 25n |
|
81 .rt |
|
82 If the value of \fIconf_state\fR is non-zero, then confidentiality and integrity protection were used. If the value is zero, only integrity service was used. Specify \fBNULL\fR if this parameter is not required. |
|
83 .RE |
|
84 |
|
85 .sp |
|
86 .ne 2 |
|
87 .mk |
|
88 .na |
|
89 \fB\fIqop_state\fR\fR |
|
90 .ad |
|
91 .RS 25n |
|
92 .rt |
|
93 Specifies the quality of protection provided. Specify \fBNULL\fR if this parameter is not required. |
|
94 .RE |
|
95 |
|
96 .SH ERRORS |
|
97 .sp |
|
98 .LP |
|
99 \fBgss_unwrap()\fR may return the following status codes: |
|
100 .sp |
|
101 .ne 2 |
|
102 .mk |
|
103 .na |
|
104 \fB\fBGSS_S_COMPLETE\fR\fR |
|
105 .ad |
|
106 .RS 25n |
|
107 .rt |
|
108 Successful completion. |
|
109 .RE |
|
110 |
|
111 .sp |
|
112 .ne 2 |
|
113 .mk |
|
114 .na |
|
115 \fB\fBGSS_S_DEFECTIVE_TOKEN\fR\fR |
|
116 .ad |
|
117 .RS 25n |
|
118 .rt |
|
119 The token failed consistency checks. |
|
120 .RE |
|
121 |
|
122 .sp |
|
123 .ne 2 |
|
124 .mk |
|
125 .na |
|
126 \fB\fBGSS_S_BAD_SIG\fR\fR |
|
127 .ad |
|
128 .RS 25n |
|
129 .rt |
|
130 The \fBMIC\fR was incorrect. |
|
131 .RE |
|
132 |
|
133 .sp |
|
134 .ne 2 |
|
135 .mk |
|
136 .na |
|
137 \fB\fBGSS_S_DUPLICATE_TOKEN\fR\fR |
|
138 .ad |
|
139 .RS 25n |
|
140 .rt |
|
141 The token was valid, and contained a correct \fBMIC\fR for the message, but it had already been processed. |
|
142 .RE |
|
143 |
|
144 .sp |
|
145 .ne 2 |
|
146 .mk |
|
147 .na |
|
148 \fB\fBGSS_S_OLD_TOKEN\fR\fR |
|
149 .ad |
|
150 .RS 25n |
|
151 .rt |
|
152 The token was valid, and contained a correct \fBMIC\fR for the message, but it is too old to check for duplication. |
|
153 .RE |
|
154 |
|
155 .sp |
|
156 .ne 2 |
|
157 .mk |
|
158 .na |
|
159 \fB\fBGSS_S_UNSEQ_TOKEN\fR\fR |
|
160 .ad |
|
161 .RS 25n |
|
162 .rt |
|
163 The token was valid, and contained a correct \fBMIC\fR for the message, but has been verified out of sequence; a later token has already been received. |
|
164 .RE |
|
165 |
|
166 .sp |
|
167 .ne 2 |
|
168 .mk |
|
169 .na |
|
170 \fB\fBGSS_S_GAP_TOKEN\fR\fR |
|
171 .ad |
|
172 .RS 25n |
|
173 .rt |
|
174 The token was valid, and contained a correct \fBMIC\fR for the message, but has been verified out of sequence; an earlier expected token has not yet been received. |
|
175 .RE |
|
176 |
|
177 .sp |
|
178 .ne 2 |
|
179 .mk |
|
180 .na |
|
181 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR |
|
182 .ad |
|
183 .RS 25n |
|
184 .rt |
|
185 The context has already expired. |
|
186 .RE |
|
187 |
|
188 .sp |
|
189 .ne 2 |
|
190 .mk |
|
191 .na |
|
192 \fB\fBGSS_S_NO_CONTEXT\fR\fR |
|
193 .ad |
|
194 .RS 25n |
|
195 .rt |
|
196 The \fIcontext_handle\fR parameter did not identify a valid context. |
|
197 .RE |
|
198 |
|
199 .sp |
|
200 .ne 2 |
|
201 .mk |
|
202 .na |
|
203 \fB\fBGSS_S_FAILURE\fR\fR |
|
204 .ad |
|
205 .RS 25n |
|
206 .rt |
|
207 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. |
|
208 .RE |
|
209 |
|
210 .SH ATTRIBUTES |
|
211 .sp |
|
212 .LP |
|
213 See \fBattributes\fR(5) for descriptions of the following attributes: |
|
214 .sp |
|
215 |
|
216 .sp |
|
217 .TS |
|
218 tab() box; |
|
219 cw(2.75i) |cw(2.75i) |
|
220 lw(2.75i) |lw(2.75i) |
|
221 . |
|
222 ATTRIBUTE TYPEATTRIBUTE VALUE |
|
223 _ |
|
224 MT-LevelSafe |
|
225 .TE |
|
226 |
|
227 .SH SEE ALSO |
|
228 .sp |
|
229 .LP |
|
230 \fBgss_release_buffer\fR(3GSS), \fBgss_wrap\fR(3GSS), \fBattributes\fR(5) |
|
231 .sp |
|
232 .LP |
|
233 |