Import OpenSSL-0.9.8i.
[dragonfly.git] / crypto / openssl-0.9.7e / doc / ssl / SSL_alert_type_string.pod
blob94e28cc3075e0910dc17a4d1b2a8ca35d1d33208
1 =pod
3 =head1 NAME
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
7 =head1 SYNOPSIS
9  #include <openssl/ssl.h>
11  const char *SSL_alert_type_string(int value);
12  const char *SSL_alert_type_string_long(int value);
14  const char *SSL_alert_desc_string(int value);
15  const char *SSL_alert_desc_string_long(int value);
17 =head1 DESCRIPTION
19 SSL_alert_type_string() returns a one letter string indicating the
20 type of the alert specified by B<value>.
22 SSL_alert_type_string_long() returns a string indicating the type of the alert
23 specified by B<value>.
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>.
28 SSL_alert_desc_string_long() returns a string describing the reason
29 of the alert specified by B<value>.
31 =head1 NOTES
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).
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.
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.
49 =head1 RETURN VALUES
51 The following strings can occur for SSL_alert_type_string() or
52 SSL_alert_type_string_long():
54 =over 4
56 =item "W"/"warning"
58 =item "F"/"fatal"
60 =item "U"/"unknown"
62 This indicates that no support is available for this alert type.
63 Probably B<value> does not contain a correct alert message.
65 =back
67 The following strings can occur for SSL_alert_desc_string() or
68 SSL_alert_desc_string_long():
70 =over 4
72 =item "CN"/"close notify"
74 The connection shall be closed. This is a warning alert.
76 =item "UM"/"unexpected message"
78 An inappropriate message was received. This alert is always fatal
79 and should never be observed in communication between proper
80 implementations.
82 =item "BM"/"bad record mac"
84 This alert is returned if a record is received with an incorrect
85 MAC. This message is always fatal.
87 =item "DF"/"decompression failure"
89 The decompression function received improper input (e.g. data
90 that would expand to excessive length). This message is always
91 fatal.
93 =item "HF"/"handshake failure"
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.
99 =item "NC"/"no certificate"
101 A client, that was asked to send a certificate, does not send a certificate
102 (SSLv3 only).
104 =item "BC"/"bad certificate"
106 A certificate was corrupt, contained signatures that did not
107 verify correctly, etc
109 =item "UC"/"unsupported certificate"
111 A certificate was of an unsupported type.
113 =item "CR"/"certificate revoked"
115 A certificate was revoked by its signer.
117 =item "CE"/"certificate expired"
119 A certificate has expired or is not currently valid.
121 =item "CU"/"certificate unknown"
123 Some other (unspecified) issue arose in processing the
124 certificate, rendering it unacceptable.
126 =item "IP"/"illegal parameter"
128 A field in the handshake was out of range or inconsistent with
129 other fields. This is always fatal.
131 =item "DC"/"decryption failed"
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.
137 =item "RO"/"record overflow"
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.
143 =item "CA"/"unknown CA"
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.
150 =item "AD"/"access denied"
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.
156 =item "DE"/"decode error"
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.
162 =item "CY"/"decrypt error"
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.
168 =item "ER"/"export restriction"
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.
175 =item "PV"/"protocol version"
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.
182 =item "IS"/"insufficient security"
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.
189 =item "IE"/"internal error"
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.
195 =item "US"/"user canceled"
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.
203 =item "NR"/"no renegotiation"
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.
217 =item "UK"/"unknown"
219 This indicates that no description is available for this alert type.
220 Probably B<value> does not contain a correct alert message.
222 =back
224 =head1 SEE ALSO
226 L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
228 =cut