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