]>
Commit | Line | Data |
---|---|---|
a403188f LJ |
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 | ||
bfd7bb3e | 19 | SSL_alert_type_string() returns a one letter string indicating the |
a403188f LJ |
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 | ||
bfd7bb3e | 25 | SSL_alert_desc_string() returns a two letter string as a short form |
a403188f LJ |
26 | describing the reason of the alert specified by B<value>. |
27 | ||
bfd7bb3e | 28 | SSL_alert_desc_string_long() returns a string describing the reason |
a403188f LJ |
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 | ||
3b80e3aa | 133 | A TLSCiphertext decrypted in an invalid way: either it wasn't an |
a403188f | 134 | even multiple of the block length or its padding values, when |
3b80e3aa | 135 | checked, weren't correct. This message is always fatal. |
a403188f LJ |
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 | |
3b80e3aa | 147 | be located or couldn't be matched with a known, trusted CA. This |
a403188f LJ |
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 | ||
0c58d22a DSH |
217 | =item "UP"/"unknown PSK identity" |
218 | ||
219 | Sent by the server to indicate that it does not recognize a PSK | |
1bc74519 | 220 | identity or an SRP identity. |
0c58d22a | 221 | |
a403188f LJ |
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 | ||
b97fdb57 | 231 | L<ssl(7)>, L<SSL_CTX_set_info_callback(3)> |
a403188f | 232 | |
e2f92610 RS |
233 | =head1 COPYRIGHT |
234 | ||
235 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
236 | ||
4746f25a | 237 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
238 | this file except in compliance with the License. You can obtain a copy |
239 | in the file LICENSE in the source distribution or at | |
240 | L<https://www.openssl.org/source/license.html>. | |
241 | ||
242 | =cut |