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