Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_alert_type_string.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
34 '''
35 '''
36 '''     Set up \*(-- to give an unbreakable dash;
37 '''     string Tr holds user defined translation string.
38 '''     Bell System Logo is used as a dummy character.
39 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
42 .ds -- \(*W-
43 .ds PI pi
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46 .ds L" ""
47 .ds R" ""
48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
50 '''   such as .IP and .SH, which do another additional levels of
51 '''   double-quote interpretation
52 .ds M" """
53 .ds S" """
54 .ds N" """""
55 .ds T" """""
56 .ds L' '
57 .ds R' '
58 .ds M' '
59 .ds S' '
60 .ds N' '
61 .ds T' '
62 'br\}
63 .el\{\
64 .ds -- \(em\|
65 .tr \*(Tr
66 .ds L" ``
67 .ds R" ''
68 .ds M" ``
69 .ds S" ''
70 .ds N" ``
71 .ds T" ''
72 .ds L' `
73 .ds R' '
74 .ds M' `
75 .ds S' '
76 .ds N' `
77 .ds T' '
78 .ds PI \(*p
79 'br\}
80 .\"     If the F register is turned on, we'll generate
81 .\"     index entries out stderr for the following things:
82 .\"             TH      Title 
83 .\"             SH      Header
84 .\"             Sh      Subsection 
85 .\"             Ip      Item
86 .\"             X<>     Xref  (embedded
87 .\"     Of course, you have to process the output yourself
88 .\"     in some meaninful fashion.
89 .if \nF \{
90 .de IX
91 .tm Index:\\$1\t\\n%\t"\\$2"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH SSL_alert_type_string 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ          \" put $1 in typewriter font
102 .ft CW
103 'if n "\c
104 'if t \\&\\$1\c
105 'if n \\&\\$1\c
106 'if n \&"
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108 '.ft R
109 ..
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 .       \" AM - accent mark definitions
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 .       \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
173 .       ds : e
174 .       ds 8 ss
175 .       ds v \h'-1'\o'\(aa\(ga'
176 .       ds _ \h'-1'^
177 .       ds . \h'-1'.
178 .       ds 3 3
179 .       ds o a
180 .       ds d- d\h'-1'\(ga
181 .       ds D- D\h'-1'\(hy
182 .       ds th \o'bp'
183 .       ds Th \o'LP'
184 .       ds ae ae
185 .       ds Ae AE
186 .       ds oe oe
187 .       ds Oe OE
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long \- get textual description of alert information
192 .SH "SYNOPSIS"
193 .PP
194 .Vb 1
195 \& #include <openssl/ssl.h>
196 .Ve
197 .Vb 2
198 \& const char *SSL_alert_type_string(int value);
199 \& const char *SSL_alert_type_string_long(int value);
200 .Ve
201 .Vb 2
202 \& const char *SSL_alert_desc_string(int value);
203 \& const char *SSL_alert_desc_string_long(int value);
204 .Ve
205 .SH "DESCRIPTION"
206 \fISSL_alert_type_string()\fR returns a one letter string indicating the
207 type of the alert specified by \fBvalue\fR.
208 .PP
209 \fISSL_alert_type_string_long()\fR returns a string indicating the type of the alert
210 specified by \fBvalue\fR.
211 .PP
212 \fISSL_alert_desc_string()\fR returns a two letter string as a short form
213 describing the reason of the alert specified by \fBvalue\fR.
214 .PP
215 \fISSL_alert_desc_string_long()\fR returns a string describing the reason
216 of the alert specified by \fBvalue\fR.
217 .SH "NOTES"
218 When one side of an SSL/TLS communication wants to inform the peer about
219 a special situation, it sends an alert. The alert is sent as a special message
220 and does not influence the normal data stream (unless its contents results
221 in the communication being canceled).
222 .PP
223 A warning alert is sent, when a non-fatal error condition occurs. The
224 \*(L"close notify\*(R" alert is sent as a warning alert. Other examples for
225 non-fatal errors are certificate errors ("certificate expired\*(R",
226 \*(L"unsupported certificate"), for which a warning alert may be sent.
227 (The sending party may however decide to send a fatal error.) The
228 receiving side may cancel the connection on reception of a warning
229 alert on it discretion.
230 .PP
231 Several alert messages must be sent as fatal alert messages as specified
232 by the TLS RFC. A fatal alert always leads to a connection abort.
233 .SH "RETURN VALUES"
234 The following strings can occur for \fISSL_alert_type_string()\fR or
235 \fISSL_alert_type_string_long()\fR:
236 .Ip "\*(N"'/'arning\*(T"" 4
237 .Ip "\*(N"'/'atal\*(T"" 4
238 .Ip "\*(N"'/'nknown\*(T"" 4
239 This indicates that no support is available for this alert type.
240 Probably \fBvalue\fR does not contain a correct alert message.
241 .PP
242 The following strings can occur for \fISSL_alert_desc_string()\fR or
243 \fISSL_alert_desc_string_long()\fR:
244 .Ip "\*(N"\s-1CN\s'/'lose notify\*(T"" 4
245 The connection shall be closed. This is a warning alert.
246 .Ip "\*(N"\s-1UM\s'/'nexpected message\*(T"" 4
247 An inappropriate message was received. This alert is always fatal
248 and should never be observed in communication between proper
249 implementations.
250 .Ip "\*(N"\s-1BM\s'/'ad record mac\*(T"" 4
251 This alert is returned if a record is received with an incorrect
252 \s-1MAC\s0. This message is always fatal.
253 .Ip "\*(N"\s-1DF\s'/'ecompression failure\*(T"" 4
254 The decompression function received improper input (e.g. data
255 that would expand to excessive length). This message is always
256 fatal.
257 .Ip "\*(N"\s-1HF\s'/'andshake failure\*(T"" 4
258 Reception of a handshake_failure alert message indicates that the
259 sender was unable to negotiate an acceptable set of security
260 parameters given the options available. This is a fatal error.
261 .Ip "\*(N"\s-1NC\s'/'o certificate\*(T"" 4
262 A client, that was asked to send a certificate, does not send a certificate
263 (SSLv3 only).
264 .Ip "\*(N"\s-1BC\s'/'ad certificate\*(T"" 4
265 A certificate was corrupt, contained signatures that did not
266 verify correctly, etc
267 .Ip "\*(N"\s-1UC\s'/'nsupported certificate\*(T"" 4
268 A certificate was of an unsupported type.
269 .Ip "\*(N"\s-1CR\s'/'ertificate revoked\*(T"" 4
270 A certificate was revoked by its signer.
271 .Ip "\*(N"\s-1CE\s'/'ertificate expired\*(T"" 4
272 A certificate has expired or is not currently valid.
273 .Ip "\*(N"\s-1CU\s'/'ertificate unknown\*(T"" 4
274 Some other (unspecified) issue arose in processing the
275 certificate, rendering it unacceptable.
276 .Ip "\*(N"\s-1IP\s'/'llegal parameter\*(T"" 4
277 A field in the handshake was out of range or inconsistent with
278 other fields. This is always fatal.
279 .Ip "\*(N"\s-1DC\s'/'ecryption failed\*(T"" 4
280 A TLSCiphertext decrypted in an invalid way: either it wasn't an
281 even multiple of the block length or its padding values, when
282 checked, weren't correct. This message is always fatal.
283 .Ip "\*(N"\s-1RO\s'/'ecord overflow\*(T"" 4
284 A TLSCiphertext record was received which had a length more than
285 2^14+2048 bytes, or a record decrypted to a TLSCompressed record
286 with more than 2^14+1024 bytes. This message is always fatal.
287 .Ip "\*(N"\s-1CA\s'/'nknown \s-1CA\s0\*(T"" 4
288 A valid certificate chain or partial chain was received, but the
289 certificate was not accepted because the \s-1CA\s0 certificate could not
290 be located or couldn't be matched with a known, trusted \s-1CA\s0.  This
291 message is always fatal.
292 .Ip "\*(N"\s-1AD\s'/'ccess denied\*(T"" 4
293 A valid certificate was received, but when access control was
294 applied, the sender decided not to proceed with negotiation.
295 This message is always fatal.
296 .Ip "\*(N"\s-1DE\s'/'ecode error\*(T"" 4
297 A message could not be decoded because some field was out of the
298 specified range or the length of the message was incorrect. This
299 message is always fatal.
300 .Ip "\*(N"\s-1CY\s'/'ecrypt error\*(T"" 4
301 A handshake cryptographic operation failed, including being
302 unable to correctly verify a signature, decrypt a key exchange,
303 or validate a finished message.
304 .Ip "\*(N"\s-1ER\s'/'xport restriction\*(T"" 4
305 A negotiation not in compliance with export restrictions was
306 detected; for example, attempting to transfer a 1024 bit
307 ephemeral \s-1RSA\s0 key for the \s-1RSA_EXPORT\s0 handshake method. This
308 message is always fatal.
309 .Ip "\*(N"\s-1PV\s'/'rotocol version\*(T"" 4
310 The protocol version the client has attempted to negotiate is
311 recognized, but not supported. (For example, old protocol
312 versions might be avoided for security reasons). This message is
313 always fatal.
314 .Ip "\*(N"\s-1IS\s'/'nsufficient security\*(T"" 4
315 Returned instead of handshake_failure when a negotiation has
316 failed specifically because the server requires ciphers more
317 secure than those supported by the client. This message is always
318 fatal.
319 .Ip "\*(N"\s-1IE\s'/'nternal error\*(T"" 4
320 An internal error unrelated to the peer or the correctness of the
321 protocol makes it impossible to continue (such as a memory
322 allocation failure). This message is always fatal.
323 .Ip "\*(N"\s-1US\s'/'ser canceled\*(T"" 4
324 This handshake is being canceled for some reason unrelated to a
325 protocol failure. If the user cancels an operation after the
326 handshake is complete, just closing the connection by sending a
327 close_notify is more appropriate. This alert should be followed
328 by a close_notify. This message is generally a warning.
329 .Ip "\*(N"\s-1NR\s'/'o renegotiation\*(T"" 4
330 Sent by the client in response to a hello request or by the
331 server in response to a client hello after initial handshaking.
332 Either of these would normally lead to renegotiation; when that
333 is not appropriate, the recipient should respond with this alert;
334 at that point, the original requester can decide whether to
335 proceed with the connection. One case where this would be
336 appropriate would be where a server has spawned a process to
337 satisfy a request; the process might receive security parameters
338 (key length, authentication, etc.) at startup and it might be
339 difficult to communicate changes to these parameters after that
340 point. This message is always a warning.
341 .Ip "\*(N"\s-1UK\s'/'nknown\*(T"" 4
342 This indicates that no description is available for this alert type.
343 Probably \fBvalue\fR does not contain a correct alert message.
344 .SH "SEE ALSO"
345 ssl(3), SSL_CTX_set_info_callback(3)
346
347 .rn }` ''
348 .IX Title "SSL_alert_type_string 3"
349 .IX Name "SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information"
350
351 .IX Header "NAME"
352
353 .IX Header "SYNOPSIS"
354
355 .IX Header "DESCRIPTION"
356
357 .IX Header "NOTES"
358
359 .IX Header "RETURN VALUES"
360
361 .IX Item "\*(N"'/'arning\*(T""
362
363 .IX Item "\*(N"'/'atal\*(T""
364
365 .IX Item "\*(N"'/'nknown\*(T""
366
367 .IX Item "\*(N"\s-1CN\s'/'lose notify\*(T""
368
369 .IX Item "\*(N"\s-1UM\s'/'nexpected message\*(T""
370
371 .IX Item "\*(N"\s-1BM\s'/'ad record mac\*(T""
372
373 .IX Item "\*(N"\s-1DF\s'/'ecompression failure\*(T""
374
375 .IX Item "\*(N"\s-1HF\s'/'andshake failure\*(T""
376
377 .IX Item "\*(N"\s-1NC\s'/'o certificate\*(T""
378
379 .IX Item "\*(N"\s-1BC\s'/'ad certificate\*(T""
380
381 .IX Item "\*(N"\s-1UC\s'/'nsupported certificate\*(T""
382
383 .IX Item "\*(N"\s-1CR\s'/'ertificate revoked\*(T""
384
385 .IX Item "\*(N"\s-1CE\s'/'ertificate expired\*(T""
386
387 .IX Item "\*(N"\s-1CU\s'/'ertificate unknown\*(T""
388
389 .IX Item "\*(N"\s-1IP\s'/'llegal parameter\*(T""
390
391 .IX Item "\*(N"\s-1DC\s'/'ecryption failed\*(T""
392
393 .IX Item "\*(N"\s-1RO\s'/'ecord overflow\*(T""
394
395 .IX Item "\*(N"\s-1CA\s'/'nknown \s-1CA\s0\*(T""
396
397 .IX Item "\*(N"\s-1AD\s'/'ccess denied\*(T""
398
399 .IX Item "\*(N"\s-1DE\s'/'ecode error\*(T""
400
401 .IX Item "\*(N"\s-1CY\s'/'ecrypt error\*(T""
402
403 .IX Item "\*(N"\s-1ER\s'/'xport restriction\*(T""
404
405 .IX Item "\*(N"\s-1PV\s'/'rotocol version\*(T""
406
407 .IX Item "\*(N"\s-1IS\s'/'nsufficient security\*(T""
408
409 .IX Item "\*(N"\s-1IE\s'/'nternal error\*(T""
410
411 .IX Item "\*(N"\s-1US\s'/'ser canceled\*(T""
412
413 .IX Item "\*(N"\s-1NR\s'/'o renegotiation\*(T""
414
415 .IX Item "\*(N"\s-1UK\s'/'nknown\*(T""
416
417 .IX Header "SEE ALSO"
418