Correct example.
[openssl.git] / doc / ssl / SSL_alert_type_string.pod
1 =pod
2
3 =head1 NAME
4
5 SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
6
7 =head1 SYNOPSIS
8
9  #include <openssl/ssl.h>
10
11  const char *SSL_alert_type_string(int value);
12  const char *SSL_alert_type_string_long(int value);
13
14  const char *SSL_alert_desc_string(int value);
15  const char *SSL_alert_desc_string_long(int value);
16
17 =head1 DESCRIPTION
18
19 SSL_alert_type_string() returns a one letter string indicating the
20 type of the alert specified by B<value>.
21
22 SSL_alert_type_string_long() returns a string indicating the type of the alert
23 specified by B<value>.
24
25 SSL_alert_desc_string() returns a two letter string as a short form
26 describing the reason of the alert specified by B<value>.
27
28 SSL_alert_desc_string_long() returns a string describing the reason
29 of the alert specified by B<value>.
30
31 =head1 NOTES
32
33 When one side of an SSL/TLS communication wants to inform the peer about
34 a special situation, it sends an alert. The alert is sent as a special message
35 and does not influence the normal data stream (unless its contents results
36 in the communication being canceled).
37
38 A warning alert is sent, when a non-fatal error condition occurs. The
39 "close notify" alert is sent as a warning alert. Other examples for
40 non-fatal errors are certificate errors ("certificate expired",
41 "unsupported certificate"), for which a warning alert may be sent.
42 (The sending party may however decide to send a fatal error.) The
43 receiving side may cancel the connection on reception of a warning
44 alert on it discretion.
45
46 Several alert messages must be sent as fatal alert messages as specified
47 by the TLS RFC. A fatal alert always leads to a connection abort.
48
49 =head1 RETURN VALUES
50
51 The following strings can occur for SSL_alert_type_string() or
52 SSL_alert_type_string_long():
53
54 =over 4
55
56 =item "W"/"warning"
57
58 =item "F"/"fatal"
59
60 =item "U"/"unknown"
61
62 This indicates that no support is available for this alert type.
63 Probably B<value> does not contain a correct alert message.
64
65 =back
66
67 The following strings can occur for SSL_alert_desc_string() or
68 SSL_alert_desc_string_long():
69
70 =over 4
71
72 =item "CN"/"close notify"
73
74 The connection shall be closed. This is a warning alert.
75
76 =item "UM"/"unexpected message"
77
78 An inappropriate message was received. This alert is always fatal
79 and should never be observed in communication between proper
80 implementations.
81
82 =item "BM"/"bad record mac"
83
84 This alert is returned if a record is received with an incorrect
85 MAC. This message is always fatal.
86
87 =item "DF"/"decompression failure"
88
89 The decompression function received improper input (e.g. data
90 that would expand to excessive length). This message is always
91 fatal.
92
93 =item "HF"/"handshake failure"
94
95 Reception of a handshake_failure alert message indicates that the
96 sender was unable to negotiate an acceptable set of security
97 parameters given the options available. This is a fatal error.
98
99 =item "NC"/"no certificate"
100
101 A client, that was asked to send a certificate, does not send a certificate
102 (SSLv3 only).
103
104 =item "BC"/"bad certificate"
105
106 A certificate was corrupt, contained signatures that did not
107 verify correctly, etc
108
109 =item "UC"/"unsupported certificate"
110
111 A certificate was of an unsupported type.
112
113 =item "CR"/"certificate revoked"
114
115 A certificate was revoked by its signer.
116
117 =item "CE"/"certificate expired"
118
119 A certificate has expired or is not currently valid.
120
121 =item "CU"/"certificate unknown"
122
123 Some other (unspecified) issue arose in processing the
124 certificate, rendering it unacceptable.
125
126 =item "IP"/"illegal parameter"
127
128 A field in the handshake was out of range or inconsistent with
129 other fields. This is always fatal.
130
131 =item "DC"/"decryption failed"
132
133 A TLSCiphertext decrypted in an invalid way: either it wasn't an
134 even multiple of the block length or its padding values, when
135 checked, weren't correct. This message is always fatal.
136
137 =item "RO"/"record overflow"
138
139 A TLSCiphertext record was received which had a length more than
140 2^14+2048 bytes, or a record decrypted to a TLSCompressed record
141 with more than 2^14+1024 bytes. This message is always fatal.
142
143 =item "CA"/"unknown CA"
144
145 A valid certificate chain or partial chain was received, but the
146 certificate was not accepted because the CA certificate could not
147 be located or couldn't be matched with a known, trusted CA.  This
148 message is always fatal.
149
150 =item "AD"/"access denied"
151
152 A valid certificate was received, but when access control was
153 applied, the sender decided not to proceed with negotiation.
154 This message is always fatal.
155
156 =item "DE"/"decode error"
157
158 A message could not be decoded because some field was out of the
159 specified range or the length of the message was incorrect. This
160 message is always fatal.
161
162 =item "CY"/"decrypt error"
163
164 A handshake cryptographic operation failed, including being
165 unable to correctly verify a signature, decrypt a key exchange,
166 or validate a finished message.
167
168 =item "ER"/"export restriction"
169
170 A negotiation not in compliance with export restrictions was
171 detected; for example, attempting to transfer a 1024 bit
172 ephemeral RSA key for the RSA_EXPORT handshake method. This
173 message is always fatal.
174
175 =item "PV"/"protocol version"
176
177 The protocol version the client has attempted to negotiate is
178 recognized, but not supported. (For example, old protocol
179 versions might be avoided for security reasons). This message is
180 always fatal.
181
182 =item "IS"/"insufficient security"
183
184 Returned instead of handshake_failure when a negotiation has
185 failed specifically because the server requires ciphers more
186 secure than those supported by the client. This message is always
187 fatal.
188
189 =item "IE"/"internal error"
190
191 An internal error unrelated to the peer or the correctness of the
192 protocol makes it impossible to continue (such as a memory
193 allocation failure). This message is always fatal.
194
195 =item "US"/"user canceled"
196
197 This handshake is being canceled for some reason unrelated to a
198 protocol failure. If the user cancels an operation after the
199 handshake is complete, just closing the connection by sending a
200 close_notify is more appropriate. This alert should be followed
201 by a close_notify. This message is generally a warning.
202
203 =item "NR"/"no renegotiation"
204
205 Sent by the client in response to a hello request or by the
206 server in response to a client hello after initial handshaking.
207 Either of these would normally lead to renegotiation; when that
208 is not appropriate, the recipient should respond with this alert;
209 at that point, the original requester can decide whether to
210 proceed with the connection. One case where this would be
211 appropriate would be where a server has spawned a process to
212 satisfy a request; the process might receive security parameters
213 (key length, authentication, etc.) at startup and it might be
214 difficult to communicate changes to these parameters after that
215 point. This message is always a warning.
216
217 =item "UP"/"unknown PSK identity"
218
219 Sent by the server to indicate that it does not recognize a PSK
220 identity or an SRP identity. 
221
222 =item "UK"/"unknown"
223
224 This indicates that no description is available for this alert type.
225 Probably B<value> does not contain a correct alert message.
226
227 =back
228
229 =head1 SEE ALSO
230
231 L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
232
233 =cut