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