SSL_alert_type_string.pod revision 109999
11592Srgrimes=pod 21592Srgrimes 31592Srgrimes=head1 NAME 41592Srgrimes 51592SrgrimesSSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information 61592Srgrimes 71592Srgrimes=head1 SYNOPSIS 81592Srgrimes 91592Srgrimes #include <openssl/ssl.h> 101592Srgrimes 111592Srgrimes const char *SSL_alert_type_string(int value); 121592Srgrimes const char *SSL_alert_type_string_long(int value); 131592Srgrimes 141592Srgrimes const char *SSL_alert_desc_string(int value); 151592Srgrimes const char *SSL_alert_desc_string_long(int value); 161592Srgrimes 171592Srgrimes=head1 DESCRIPTION 181592Srgrimes 191592SrgrimesSSL_alert_type_string() returns a one letter string indicating the 201592Srgrimestype of the alert specified by B<value>. 21262435Sbrueffer 221592SrgrimesSSL_alert_type_string_long() returns a string indicating the type of the alert 231592Srgrimesspecified by B<value>. 241592Srgrimes 251592SrgrimesSSL_alert_desc_string() returns a two letter string as a short form 261592Srgrimesdescribing the reason of the alert specified by B<value>. 271592Srgrimes 281592SrgrimesSSL_alert_desc_string_long() returns a string describing the reason 291592Srgrimesof the alert specified by B<value>. 301592Srgrimes 311592Srgrimes=head1 NOTES 321592Srgrimes 331592SrgrimesWhen one side of an SSL/TLS communication wants to inform the peer about 341592Srgrimesa special situation, it sends an alert. The alert is sent as a special message 351592Srgrimesand does not influence the normal data stream (unless its contents results 361592Srgrimesin the communication being canceled). 3727074Ssteve 381592SrgrimesA warning alert is sent, when a non-fatal error condition occurs. The 3927074Ssteve"close notify" alert is sent as a warning alert. Other examples for 401592Srgrimesnon-fatal errors are certificate errors ("certificate expired", 41262434Sbrueffer"unsupported certificate"), for which a warning alert may be sent. 42262434Sbrueffer(The sending party may however decide to send a fatal error.) The 431592Srgrimesreceiving side may cancel the connection on reception of a warning 441592Srgrimesalert on it discretion. 451592Srgrimes 461592SrgrimesSeveral alert messages must be sent as fatal alert messages as specified 471592Srgrimesby the TLS RFC. A fatal alert always leads to a connection abort. 481592Srgrimes 491592Srgrimes=head1 RETURN VALUES 501592Srgrimes 511592SrgrimesThe following strings can occur for SSL_alert_type_string() or 521592SrgrimesSSL_alert_type_string_long(): 531592Srgrimes 541592Srgrimes=over 4 551592Srgrimes 561592Srgrimes=item "W"/"warning" 571592Srgrimes 581592Srgrimes=item "F"/"fatal" 591592Srgrimes 601592Srgrimes=item "U"/"unknown" 611592Srgrimes 621592SrgrimesThis indicates that no support is available for this alert type. 631592SrgrimesProbably B<value> does not contain a correct alert message. 641592Srgrimes 651592Srgrimes=back 661592Srgrimes 671592SrgrimesThe following strings can occur for SSL_alert_desc_string() or 681592SrgrimesSSL_alert_desc_string_long(): 691592Srgrimes 701592Srgrimes=over 4 711592Srgrimes 721592Srgrimes=item "CN"/"close notify" 731592Srgrimes 741592SrgrimesThe connection shall be closed. This is a warning alert. 751592Srgrimes 761592Srgrimes=item "UM"/"unexpected message" 771592Srgrimes 781592SrgrimesAn inappropriate message was received. This alert is always fatal 791592Srgrimesand should never be observed in communication between proper 801592Srgrimesimplementations. 811592Srgrimes 821592Srgrimes=item "BM"/"bad record mac" 831592Srgrimes 841592SrgrimesThis alert is returned if a record is received with an incorrect 851592SrgrimesMAC. This message is always fatal. 861592Srgrimes 871592Srgrimes=item "DF"/"decompression failure" 881592Srgrimes 891592SrgrimesThe decompression function received improper input (e.g. data 901592Srgrimesthat would expand to excessive length). This message is always 911592Srgrimesfatal. 921592Srgrimes 931592Srgrimes=item "HF"/"handshake failure" 941592Srgrimes 951592SrgrimesReception of a handshake_failure alert message indicates that the 961592Srgrimessender was unable to negotiate an acceptable set of security 971592Srgrimesparameters given the options available. This is a fatal error. 981592Srgrimes 991592Srgrimes=item "NC"/"no certificate" 1001592Srgrimes 10127074SsteveA client, that was asked to send a certificate, does not send a certificate 1021592Srgrimes(SSLv3 only). 1031592Srgrimes 1041592Srgrimes=item "BC"/"bad certificate" 1051592Srgrimes 10627074SsteveA certificate was corrupt, contained signatures that did not 1071592Srgrimesverify correctly, etc 1081592Srgrimes 1091592Srgrimes=item "UC"/"unsupported certificate" 1101592Srgrimes 1111592SrgrimesA certificate was of an unsupported type. 1121592Srgrimes 1131592Srgrimes=item "CR"/"certificate revoked" 1141592Srgrimes 1151592SrgrimesA certificate was revoked by its signer. 1161592Srgrimes 1171592Srgrimes=item "CE"/"certificate expired" 11827074Ssteve 11927074SsteveA certificate has expired or is not currently valid. 12027074Ssteve 1211592Srgrimes=item "CU"/"certificate unknown" 1221592Srgrimes 1231592SrgrimesSome other (unspecified) issue arose in processing the 1241592Srgrimescertificate, rendering it unacceptable. 1251592Srgrimes 1261592Srgrimes=item "IP"/"illegal parameter" 1271592Srgrimes 12827079SsteveA field in the handshake was out of range or inconsistent with 12927074Ssteveother fields. This is always fatal. 1301592Srgrimes 13127074Ssteve=item "DC"/"decryption failed" 1321592Srgrimes 13327074SsteveA TLSCiphertext decrypted in an invalid way: either it wasn't an 1341592Srgrimeseven multiple of the block length or its padding values, when 1351592Srgrimeschecked, weren't correct. This message is always fatal. 1361592Srgrimes 1371592Srgrimes=item "RO"/"record overflow" 13827074Ssteve 13927074SsteveA TLSCiphertext record was received which had a length more than 1401592Srgrimes2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1411592Srgrimeswith more than 2^14+1024 bytes. This message is always fatal. 1421592Srgrimes 14327074Ssteve=item "CA"/"unknown CA" 1441592Srgrimes 1451592SrgrimesA valid certificate chain or partial chain was received, but the 14627074Sstevecertificate was not accepted because the CA certificate could not 1471592Srgrimesbe located or couldn't be matched with a known, trusted CA. This 1481592Srgrimesmessage is always fatal. 1491592Srgrimes 1501592Srgrimes=item "AD"/"access denied" 1511592Srgrimes 1521592SrgrimesA valid certificate was received, but when access control was 1531592Srgrimesapplied, the sender decided not to proceed with negotiation. 1541592SrgrimesThis message is always fatal. 1551592Srgrimes 1561592Srgrimes=item "DE"/"decode error" 15727074Ssteve 1581592SrgrimesA message could not be decoded because some field was out of the 15927074Sstevespecified range or the length of the message was incorrect. This 16027074Sstevemessage is always fatal. 1611592Srgrimes 1621592Srgrimes=item "CY"/"decrypt error" 1631592Srgrimes 1641592SrgrimesA handshake cryptographic operation failed, including being 1651592Srgrimesunable to correctly verify a signature, decrypt a key exchange, 1661592Srgrimesor validate a finished message. 1671592Srgrimes 1681592Srgrimes=item "ER"/"export restriction" 1691592Srgrimes 17027074SsteveA negotiation not in compliance with export restrictions was 17127074Sstevedetected; for example, attempting to transfer a 1024 bit 1721592Srgrimesephemeral RSA key for the RSA_EXPORT handshake method. This 1731592Srgrimesmessage is always fatal. 1741592Srgrimes 17527074Ssteve=item "PV"/"protocol version" 17627074Ssteve 17727074SsteveThe protocol version the client has attempted to negotiate is 17827074Ssteverecognized, but not supported. (For example, old protocol 17927074Ssteveversions might be avoided for security reasons). This message is 18027074Sstevealways fatal. 18127074Ssteve 1821592Srgrimes=item "IS"/"insufficient security" 1831592Srgrimes 1841592SrgrimesReturned instead of handshake_failure when a negotiation has 1851592Srgrimesfailed specifically because the server requires ciphers more 18627074Sstevesecure than those supported by the client. This message is always 18727074Sstevefatal. 18827074Ssteve 18927074Ssteve=item "IE"/"internal error" 19027074Ssteve 19127074SsteveAn internal error unrelated to the peer or the correctness of the 1921592Srgrimesprotocol makes it impossible to continue (such as a memory 1931592Srgrimesallocation failure). This message is always fatal. 1941592Srgrimes 1951592Srgrimes=item "US"/"user canceled" 19627074Ssteve 19727074SsteveThis handshake is being canceled for some reason unrelated to a 19827074Ssteveprotocol failure. If the user cancels an operation after the 19927074Sstevehandshake is complete, just closing the connection by sending a 20027074Ssteveclose_notify is more appropriate. This alert should be followed 2011592Srgrimesby a close_notify. This message is generally a warning. 2021592Srgrimes 2031592Srgrimes=item "NR"/"no renegotiation" 20427074Ssteve 20527074SsteveSent by the client in response to a hello request or by the 20627074Ssteveserver in response to a client hello after initial handshaking. 20727074SsteveEither of these would normally lead to renegotiation; when that 2081592Srgrimesis not appropriate, the recipient should respond with this alert; 20927074Ssteveat that point, the original requester can decide whether to 2101592Srgrimesproceed with the connection. One case where this would be 2111592Srgrimesappropriate would be where a server has spawned a process to 2121592Srgrimessatisfy a request; the process might receive security parameters 21327074Ssteve(key length, authentication, etc.) at startup and it might be 21427074Sstevedifficult to communicate changes to these parameters after that 21527074Sstevepoint. This message is always a warning. 21627074Ssteve 2171592Srgrimes=item "UK"/"unknown" 2181592Srgrimes 2191592SrgrimesThis indicates that no description is available for this alert type. 2201592SrgrimesProbably B<value> does not contain a correct alert message. 2211592Srgrimes 2221592Srgrimes=back 2231592Srgrimes 2241592Srgrimes=head1 SEE ALSO 2251592Srgrimes 2261592SrgrimesL<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)> 2271592Srgrimes 2281592Srgrimes=cut 2291592Srgrimes