189837Skris=pod 289837Skris 389837Skris=head1 NAME 489837Skris 589837SkrisSSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information 689837Skris 789837Skris=head1 SYNOPSIS 889837Skris 989837Skris #include <openssl/ssl.h> 1089837Skris 11109998Smarkm const char *SSL_alert_type_string(int value); 12109998Smarkm const char *SSL_alert_type_string_long(int value); 1389837Skris 14109998Smarkm const char *SSL_alert_desc_string(int value); 15109998Smarkm const char *SSL_alert_desc_string_long(int value); 1689837Skris 1789837Skris=head1 DESCRIPTION 1889837Skris 1989837SkrisSSL_alert_type_string() returns a one letter string indicating the 2089837Skristype of the alert specified by B<value>. 2189837Skris 2289837SkrisSSL_alert_type_string_long() returns a string indicating the type of the alert 2389837Skrisspecified by B<value>. 2489837Skris 2589837SkrisSSL_alert_desc_string() returns a two letter string as a short form 2689837Skrisdescribing the reason of the alert specified by B<value>. 2789837Skris 2889837SkrisSSL_alert_desc_string_long() returns a string describing the reason 2989837Skrisof the alert specified by B<value>. 3089837Skris 3189837Skris=head1 NOTES 3289837Skris 3389837SkrisWhen one side of an SSL/TLS communication wants to inform the peer about 3489837Skrisa special situation, it sends an alert. The alert is sent as a special message 3589837Skrisand does not influence the normal data stream (unless its contents results 3689837Skrisin the communication being canceled). 3789837Skris 3889837SkrisA warning alert is sent, when a non-fatal error condition occurs. The 3989837Skris"close notify" alert is sent as a warning alert. Other examples for 4089837Skrisnon-fatal errors are certificate errors ("certificate expired", 4189837Skris"unsupported certificate"), for which a warning alert may be sent. 4289837Skris(The sending party may however decide to send a fatal error.) The 4389837Skrisreceiving side may cancel the connection on reception of a warning 4489837Skrisalert on it discretion. 4589837Skris 4689837SkrisSeveral alert messages must be sent as fatal alert messages as specified 4789837Skrisby the TLS RFC. A fatal alert always leads to a connection abort. 4889837Skris 4989837Skris=head1 RETURN VALUES 5089837Skris 5189837SkrisThe following strings can occur for SSL_alert_type_string() or 5289837SkrisSSL_alert_type_string_long(): 5389837Skris 5489837Skris=over 4 5589837Skris 5689837Skris=item "W"/"warning" 5789837Skris 5889837Skris=item "F"/"fatal" 5989837Skris 6089837Skris=item "U"/"unknown" 6189837Skris 6289837SkrisThis indicates that no support is available for this alert type. 6389837SkrisProbably B<value> does not contain a correct alert message. 6489837Skris 6589837Skris=back 6689837Skris 6789837SkrisThe following strings can occur for SSL_alert_desc_string() or 6889837SkrisSSL_alert_desc_string_long(): 6989837Skris 7089837Skris=over 4 7189837Skris 7289837Skris=item "CN"/"close notify" 7389837Skris 7489837SkrisThe connection shall be closed. This is a warning alert. 7589837Skris 7689837Skris=item "UM"/"unexpected message" 7789837Skris 7889837SkrisAn inappropriate message was received. This alert is always fatal 7989837Skrisand should never be observed in communication between proper 8089837Skrisimplementations. 8189837Skris 8289837Skris=item "BM"/"bad record mac" 8389837Skris 8489837SkrisThis alert is returned if a record is received with an incorrect 8589837SkrisMAC. This message is always fatal. 8689837Skris 8789837Skris=item "DF"/"decompression failure" 8889837Skris 8989837SkrisThe decompression function received improper input (e.g. data 9089837Skristhat would expand to excessive length). This message is always 9189837Skrisfatal. 9289837Skris 9389837Skris=item "HF"/"handshake failure" 9489837Skris 9589837SkrisReception of a handshake_failure alert message indicates that the 9689837Skrissender was unable to negotiate an acceptable set of security 9789837Skrisparameters given the options available. This is a fatal error. 9889837Skris 9989837Skris=item "NC"/"no certificate" 10089837Skris 10189837SkrisA client, that was asked to send a certificate, does not send a certificate 10289837Skris(SSLv3 only). 10389837Skris 10489837Skris=item "BC"/"bad certificate" 10589837Skris 10689837SkrisA certificate was corrupt, contained signatures that did not 10789837Skrisverify correctly, etc 10889837Skris 10989837Skris=item "UC"/"unsupported certificate" 11089837Skris 11189837SkrisA certificate was of an unsupported type. 11289837Skris 11389837Skris=item "CR"/"certificate revoked" 11489837Skris 11589837SkrisA certificate was revoked by its signer. 11689837Skris 11789837Skris=item "CE"/"certificate expired" 11889837Skris 11989837SkrisA certificate has expired or is not currently valid. 12089837Skris 12189837Skris=item "CU"/"certificate unknown" 12289837Skris 12389837SkrisSome other (unspecified) issue arose in processing the 12489837Skriscertificate, rendering it unacceptable. 12589837Skris 12689837Skris=item "IP"/"illegal parameter" 12789837Skris 12889837SkrisA field in the handshake was out of range or inconsistent with 12989837Skrisother fields. This is always fatal. 13089837Skris 13189837Skris=item "DC"/"decryption failed" 13289837Skris 13389837SkrisA TLSCiphertext decrypted in an invalid way: either it wasn't an 13489837Skriseven multiple of the block length or its padding values, when 13589837Skrischecked, weren't correct. This message is always fatal. 13689837Skris 13789837Skris=item "RO"/"record overflow" 13889837Skris 13989837SkrisA TLSCiphertext record was received which had a length more than 14089837Skris2^14+2048 bytes, or a record decrypted to a TLSCompressed record 14189837Skriswith more than 2^14+1024 bytes. This message is always fatal. 14289837Skris 14389837Skris=item "CA"/"unknown CA" 14489837Skris 14589837SkrisA valid certificate chain or partial chain was received, but the 14689837Skriscertificate was not accepted because the CA certificate could not 14789837Skrisbe located or couldn't be matched with a known, trusted CA. This 14889837Skrismessage is always fatal. 14989837Skris 15089837Skris=item "AD"/"access denied" 15189837Skris 15289837SkrisA valid certificate was received, but when access control was 15389837Skrisapplied, the sender decided not to proceed with negotiation. 15489837SkrisThis message is always fatal. 15589837Skris 15689837Skris=item "DE"/"decode error" 15789837Skris 15889837SkrisA message could not be decoded because some field was out of the 15989837Skrisspecified range or the length of the message was incorrect. This 16089837Skrismessage is always fatal. 16189837Skris 16289837Skris=item "CY"/"decrypt error" 16389837Skris 16489837SkrisA handshake cryptographic operation failed, including being 16589837Skrisunable to correctly verify a signature, decrypt a key exchange, 16689837Skrisor validate a finished message. 16789837Skris 16889837Skris=item "ER"/"export restriction" 16989837Skris 17089837SkrisA negotiation not in compliance with export restrictions was 17189837Skrisdetected; for example, attempting to transfer a 1024 bit 17289837Skrisephemeral RSA key for the RSA_EXPORT handshake method. This 17389837Skrismessage is always fatal. 17489837Skris 17589837Skris=item "PV"/"protocol version" 17689837Skris 17789837SkrisThe protocol version the client has attempted to negotiate is 17889837Skrisrecognized, but not supported. (For example, old protocol 17989837Skrisversions might be avoided for security reasons). This message is 18089837Skrisalways fatal. 18189837Skris 18289837Skris=item "IS"/"insufficient security" 18389837Skris 18489837SkrisReturned instead of handshake_failure when a negotiation has 18589837Skrisfailed specifically because the server requires ciphers more 18689837Skrissecure than those supported by the client. This message is always 18789837Skrisfatal. 18889837Skris 18989837Skris=item "IE"/"internal error" 19089837Skris 19189837SkrisAn internal error unrelated to the peer or the correctness of the 19289837Skrisprotocol makes it impossible to continue (such as a memory 19389837Skrisallocation failure). This message is always fatal. 19489837Skris 19589837Skris=item "US"/"user canceled" 19689837Skris 19789837SkrisThis handshake is being canceled for some reason unrelated to a 19889837Skrisprotocol failure. If the user cancels an operation after the 19989837Skrishandshake is complete, just closing the connection by sending a 20089837Skrisclose_notify is more appropriate. This alert should be followed 20189837Skrisby a close_notify. This message is generally a warning. 20289837Skris 20389837Skris=item "NR"/"no renegotiation" 20489837Skris 20589837SkrisSent by the client in response to a hello request or by the 20689837Skrisserver in response to a client hello after initial handshaking. 20789837SkrisEither of these would normally lead to renegotiation; when that 20889837Skrisis not appropriate, the recipient should respond with this alert; 20989837Skrisat that point, the original requester can decide whether to 21089837Skrisproceed with the connection. One case where this would be 21189837Skrisappropriate would be where a server has spawned a process to 21289837Skrissatisfy a request; the process might receive security parameters 21389837Skris(key length, authentication, etc.) at startup and it might be 21489837Skrisdifficult to communicate changes to these parameters after that 21589837Skrispoint. This message is always a warning. 21689837Skris 21789837Skris=item "UK"/"unknown" 21889837Skris 21989837SkrisThis indicates that no description is available for this alert type. 22089837SkrisProbably B<value> does not contain a correct alert message. 22189837Skris 22289837Skris=back 22389837Skris 22489837Skris=head1 SEE ALSO 22589837Skris 22689837SkrisL<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)> 22789837Skris 22889837Skris=cut 229