Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libssl / man / SSL_alert_type_string.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
e056f0e0 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
e056f0e0 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
e056f0e0 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
e056f0e0
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
e056f0e0 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
e056f0e0
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
e056f0e0
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
e056f0e0
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
e056f0e0
JR
59. nr % 0
60. rr F
984263bc 61.\}
e056f0e0 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
e056f0e0
JR
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
e056f0e0
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
e056f0e0
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
e056f0e0 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
e056f0e0
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
e056f0e0
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
e056f0e0 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
e056f0e0
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
e056f0e0
JR
129.\" ========================================================================
130.\"
131.IX Title "SSL_alert_type_string 3"
aac4ff6f 132.TH SSL_alert_type_string 3 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc
MD
133.SH "NAME"
134SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long \- get textual description of alert information
135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
aac4ff6f
PA
139.Ve
140.PP
141.Vb 2
984263bc
MD
142\& const char *SSL_alert_type_string(int value);
143\& const char *SSL_alert_type_string_long(int value);
aac4ff6f
PA
144.Ve
145.PP
146.Vb 2
984263bc
MD
147\& const char *SSL_alert_desc_string(int value);
148\& const char *SSL_alert_desc_string_long(int value);
149.Ve
150.SH "DESCRIPTION"
e056f0e0
JR
151.IX Header "DESCRIPTION"
152\&\fISSL_alert_type_string()\fR returns a one letter string indicating the
984263bc
MD
153type of the alert specified by \fBvalue\fR.
154.PP
e056f0e0 155\&\fISSL_alert_type_string_long()\fR returns a string indicating the type of the alert
984263bc
MD
156specified by \fBvalue\fR.
157.PP
e056f0e0 158\&\fISSL_alert_desc_string()\fR returns a two letter string as a short form
984263bc
MD
159describing the reason of the alert specified by \fBvalue\fR.
160.PP
e056f0e0 161\&\fISSL_alert_desc_string_long()\fR returns a string describing the reason
984263bc
MD
162of the alert specified by \fBvalue\fR.
163.SH "NOTES"
e056f0e0
JR
164.IX Header "NOTES"
165When one side of an \s-1SSL/TLS\s0 communication wants to inform the peer about
984263bc
MD
166a special situation, it sends an alert. The alert is sent as a special message
167and does not influence the normal data stream (unless its contents results
168in the communication being canceled).
169.PP
170A warning alert is sent, when a non-fatal error condition occurs. The
e056f0e0
JR
171\&\*(L"close notify\*(R" alert is sent as a warning alert. Other examples for
172non-fatal errors are certificate errors (\*(L"certificate expired\*(R",
173\&\*(L"unsupported certificate\*(R"), for which a warning alert may be sent.
984263bc
MD
174(The sending party may however decide to send a fatal error.) The
175receiving side may cancel the connection on reception of a warning
176alert on it discretion.
177.PP
178Several alert messages must be sent as fatal alert messages as specified
e056f0e0 179by the \s-1TLS\s0 \s-1RFC\s0. A fatal alert always leads to a connection abort.
984263bc 180.SH "RETURN VALUES"
e056f0e0 181.IX Header "RETURN VALUES"
984263bc 182The following strings can occur for \fISSL_alert_type_string()\fR or
e056f0e0
JR
183\&\fISSL_alert_type_string_long()\fR:
184.ie n .IP """W""/""warning""" 4
185.el .IP "``W''/``warning''" 4
186.IX Item "W/warning"
187.PD 0
188.ie n .IP """F""/""fatal""" 4
189.el .IP "``F''/``fatal''" 4
190.IX Item "F/fatal"
191.ie n .IP """U""/""unknown""" 4
192.el .IP "``U''/``unknown''" 4
193.IX Item "U/unknown"
194.PD
984263bc
MD
195This indicates that no support is available for this alert type.
196Probably \fBvalue\fR does not contain a correct alert message.
197.PP
198The following strings can occur for \fISSL_alert_desc_string()\fR or
e056f0e0
JR
199\&\fISSL_alert_desc_string_long()\fR:
200.ie n .IP """\s-1CN\s0""/""close notify""" 4
201.el .IP "``\s-1CN\s0''/``close notify''" 4
202.IX Item "CN/close notify"
984263bc 203The connection shall be closed. This is a warning alert.
e056f0e0
JR
204.ie n .IP """\s-1UM\s0""/""unexpected message""" 4
205.el .IP "``\s-1UM\s0''/``unexpected message''" 4
206.IX Item "UM/unexpected message"
984263bc
MD
207An inappropriate message was received. This alert is always fatal
208and should never be observed in communication between proper
209implementations.
e056f0e0
JR
210.ie n .IP """\s-1BM\s0""/""bad record mac""" 4
211.el .IP "``\s-1BM\s0''/``bad record mac''" 4
212.IX Item "BM/bad record mac"
984263bc 213This alert is returned if a record is received with an incorrect
e056f0e0
JR
214\&\s-1MAC\s0. This message is always fatal.
215.ie n .IP """\s-1DF\s0""/""decompression failure""" 4
216.el .IP "``\s-1DF\s0''/``decompression failure''" 4
217.IX Item "DF/decompression failure"
984263bc
MD
218The decompression function received improper input (e.g. data
219that would expand to excessive length). This message is always
220fatal.
e056f0e0
JR
221.ie n .IP """\s-1HF\s0""/""handshake failure""" 4
222.el .IP "``\s-1HF\s0''/``handshake failure''" 4
223.IX Item "HF/handshake failure"
984263bc
MD
224Reception of a handshake_failure alert message indicates that the
225sender was unable to negotiate an acceptable set of security
226parameters given the options available. This is a fatal error.
e056f0e0
JR
227.ie n .IP """\s-1NC\s0""/""no certificate""" 4
228.el .IP "``\s-1NC\s0''/``no certificate''" 4
229.IX Item "NC/no certificate"
984263bc
MD
230A client, that was asked to send a certificate, does not send a certificate
231(SSLv3 only).
e056f0e0
JR
232.ie n .IP """\s-1BC\s0""/""bad certificate""" 4
233.el .IP "``\s-1BC\s0''/``bad certificate''" 4
234.IX Item "BC/bad certificate"
984263bc
MD
235A certificate was corrupt, contained signatures that did not
236verify correctly, etc
e056f0e0
JR
237.ie n .IP """\s-1UC\s0""/""unsupported certificate""" 4
238.el .IP "``\s-1UC\s0''/``unsupported certificate''" 4
239.IX Item "UC/unsupported certificate"
984263bc 240A certificate was of an unsupported type.
e056f0e0
JR
241.ie n .IP """\s-1CR\s0""/""certificate revoked""" 4
242.el .IP "``\s-1CR\s0''/``certificate revoked''" 4
243.IX Item "CR/certificate revoked"
984263bc 244A certificate was revoked by its signer.
e056f0e0
JR
245.ie n .IP """\s-1CE\s0""/""certificate expired""" 4
246.el .IP "``\s-1CE\s0''/``certificate expired''" 4
247.IX Item "CE/certificate expired"
984263bc 248A certificate has expired or is not currently valid.
e056f0e0
JR
249.ie n .IP """\s-1CU\s0""/""certificate unknown""" 4
250.el .IP "``\s-1CU\s0''/``certificate unknown''" 4
251.IX Item "CU/certificate unknown"
984263bc
MD
252Some other (unspecified) issue arose in processing the
253certificate, rendering it unacceptable.
e056f0e0
JR
254.ie n .IP """\s-1IP\s0""/""illegal parameter""" 4
255.el .IP "``\s-1IP\s0''/``illegal parameter''" 4
256.IX Item "IP/illegal parameter"
984263bc
MD
257A field in the handshake was out of range or inconsistent with
258other fields. This is always fatal.
e056f0e0
JR
259.ie n .IP """\s-1DC\s0""/""decryption failed""" 4
260.el .IP "``\s-1DC\s0''/``decryption failed''" 4
261.IX Item "DC/decryption failed"
984263bc
MD
262A TLSCiphertext decrypted in an invalid way: either it wasn't an
263even multiple of the block length or its padding values, when
264checked, weren't correct. This message is always fatal.
e056f0e0
JR
265.ie n .IP """\s-1RO\s0""/""record overflow""" 4
266.el .IP "``\s-1RO\s0''/``record overflow''" 4
267.IX Item "RO/record overflow"
984263bc
MD
268A TLSCiphertext record was received which had a length more than
2692^14+2048 bytes, or a record decrypted to a TLSCompressed record
270with more than 2^14+1024 bytes. This message is always fatal.
e056f0e0
JR
271.ie n .IP """\s-1CA\s0""/""unknown \s-1CA\s0""" 4
272.el .IP "``\s-1CA\s0''/``unknown \s-1CA\s0''" 4
273.IX Item "CA/unknown CA"
984263bc
MD
274A valid certificate chain or partial chain was received, but the
275certificate was not accepted because the \s-1CA\s0 certificate could not
276be located or couldn't be matched with a known, trusted \s-1CA\s0. This
277message is always fatal.
e056f0e0
JR
278.ie n .IP """\s-1AD\s0""/""access denied""" 4
279.el .IP "``\s-1AD\s0''/``access denied''" 4
280.IX Item "AD/access denied"
984263bc
MD
281A valid certificate was received, but when access control was
282applied, the sender decided not to proceed with negotiation.
283This message is always fatal.
e056f0e0
JR
284.ie n .IP """\s-1DE\s0""/""decode error""" 4
285.el .IP "``\s-1DE\s0''/``decode error''" 4
286.IX Item "DE/decode error"
984263bc
MD
287A message could not be decoded because some field was out of the
288specified range or the length of the message was incorrect. This
289message is always fatal.
e056f0e0
JR
290.ie n .IP """\s-1CY\s0""/""decrypt error""" 4
291.el .IP "``\s-1CY\s0''/``decrypt error''" 4
292.IX Item "CY/decrypt error"
984263bc
MD
293A handshake cryptographic operation failed, including being
294unable to correctly verify a signature, decrypt a key exchange,
295or validate a finished message.
e056f0e0
JR
296.ie n .IP """\s-1ER\s0""/""export restriction""" 4
297.el .IP "``\s-1ER\s0''/``export restriction''" 4
298.IX Item "ER/export restriction"
984263bc
MD
299A negotiation not in compliance with export restrictions was
300detected; for example, attempting to transfer a 1024 bit
301ephemeral \s-1RSA\s0 key for the \s-1RSA_EXPORT\s0 handshake method. This
302message is always fatal.
e056f0e0
JR
303.ie n .IP """\s-1PV\s0""/""protocol version""" 4
304.el .IP "``\s-1PV\s0''/``protocol version''" 4
305.IX Item "PV/protocol version"
984263bc
MD
306The protocol version the client has attempted to negotiate is
307recognized, but not supported. (For example, old protocol
308versions might be avoided for security reasons). This message is
309always fatal.
e056f0e0
JR
310.ie n .IP """\s-1IS\s0""/""insufficient security""" 4
311.el .IP "``\s-1IS\s0''/``insufficient security''" 4
312.IX Item "IS/insufficient security"
984263bc
MD
313Returned instead of handshake_failure when a negotiation has
314failed specifically because the server requires ciphers more
315secure than those supported by the client. This message is always
316fatal.
e056f0e0
JR
317.ie n .IP """\s-1IE\s0""/""internal error""" 4
318.el .IP "``\s-1IE\s0''/``internal error''" 4
319.IX Item "IE/internal error"
984263bc
MD
320An internal error unrelated to the peer or the correctness of the
321protocol makes it impossible to continue (such as a memory
322allocation failure). This message is always fatal.
e056f0e0
JR
323.ie n .IP """\s-1US\s0""/""user canceled""" 4
324.el .IP "``\s-1US\s0''/``user canceled''" 4
325.IX Item "US/user canceled"
984263bc
MD
326This handshake is being canceled for some reason unrelated to a
327protocol failure. If the user cancels an operation after the
328handshake is complete, just closing the connection by sending a
329close_notify is more appropriate. This alert should be followed
330by a close_notify. This message is generally a warning.
e056f0e0
JR
331.ie n .IP """\s-1NR\s0""/""no renegotiation""" 4
332.el .IP "``\s-1NR\s0''/``no renegotiation''" 4
333.IX Item "NR/no renegotiation"
984263bc
MD
334Sent by the client in response to a hello request or by the
335server in response to a client hello after initial handshaking.
336Either of these would normally lead to renegotiation; when that
337is not appropriate, the recipient should respond with this alert;
338at that point, the original requester can decide whether to
339proceed with the connection. One case where this would be
340appropriate would be where a server has spawned a process to
341satisfy a request; the process might receive security parameters
342(key length, authentication, etc.) at startup and it might be
343difficult to communicate changes to these parameters after that
344point. This message is always a warning.
e056f0e0
JR
345.ie n .IP """\s-1UK\s0""/""unknown""" 4
346.el .IP "``\s-1UK\s0''/``unknown''" 4
347.IX Item "UK/unknown"
984263bc
MD
348This indicates that no description is available for this alert type.
349Probably \fBvalue\fR does not contain a correct alert message.
350.SH "SEE ALSO"
a7d27d5a 351.IX Header "SEE ALSO"
e056f0e0 352\&\fIssl\fR\|(3), \fISSL_CTX_set_info_callback\fR\|(3)