123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233 |
- =pod
- =head1 NAME
- SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
- =head1 SYNOPSIS
- #include <openssl/ssl.h>
- const char *SSL_alert_type_string(int value);
- const char *SSL_alert_type_string_long(int value);
- const char *SSL_alert_desc_string(int value);
- const char *SSL_alert_desc_string_long(int value);
- =head1 DESCRIPTION
- SSL_alert_type_string() returns a one letter string indicating the
- type of the alert specified by B<value>.
- SSL_alert_type_string_long() returns a string indicating the type of the alert
- specified by B<value>.
- SSL_alert_desc_string() returns a two letter string as a short form
- describing the reason of the alert specified by B<value>.
- SSL_alert_desc_string_long() returns a string describing the reason
- of the alert specified by B<value>.
- =head1 NOTES
- When one side of an SSL/TLS communication wants to inform the peer about
- a special situation, it sends an alert. The alert is sent as a special message
- and does not influence the normal data stream (unless its contents results
- in the communication being canceled).
- A warning alert is sent, when a non-fatal error condition occurs. The
- "close notify" alert is sent as a warning alert. Other examples for
- non-fatal errors are certificate errors ("certificate expired",
- "unsupported certificate"), for which a warning alert may be sent.
- (The sending party may however decide to send a fatal error.) The
- receiving side may cancel the connection on reception of a warning
- alert on it discretion.
- Several alert messages must be sent as fatal alert messages as specified
- by the TLS RFC. A fatal alert always leads to a connection abort.
- =head1 RETURN VALUES
- The following strings can occur for SSL_alert_type_string() or
- SSL_alert_type_string_long():
- =over 4
- =item "W"/"warning"
- =item "F"/"fatal"
- =item "U"/"unknown"
- This indicates that no support is available for this alert type.
- Probably B<value> does not contain a correct alert message.
- =back
- The following strings can occur for SSL_alert_desc_string() or
- SSL_alert_desc_string_long():
- =over 4
- =item "CN"/"close notify"
- The connection shall be closed. This is a warning alert.
- =item "UM"/"unexpected message"
- An inappropriate message was received. This alert is always fatal
- and should never be observed in communication between proper
- implementations.
- =item "BM"/"bad record mac"
- This alert is returned if a record is received with an incorrect
- MAC. This message is always fatal.
- =item "DF"/"decompression failure"
- The decompression function received improper input (e.g. data
- that would expand to excessive length). This message is always
- fatal.
- =item "HF"/"handshake failure"
- Reception of a handshake_failure alert message indicates that the
- sender was unable to negotiate an acceptable set of security
- parameters given the options available. This is a fatal error.
- =item "NC"/"no certificate"
- A client, that was asked to send a certificate, does not send a certificate
- (SSLv3 only).
- =item "BC"/"bad certificate"
- A certificate was corrupt, contained signatures that did not
- verify correctly, etc
- =item "UC"/"unsupported certificate"
- A certificate was of an unsupported type.
- =item "CR"/"certificate revoked"
- A certificate was revoked by its signer.
- =item "CE"/"certificate expired"
- A certificate has expired or is not currently valid.
- =item "CU"/"certificate unknown"
- Some other (unspecified) issue arose in processing the
- certificate, rendering it unacceptable.
- =item "IP"/"illegal parameter"
- A field in the handshake was out of range or inconsistent with
- other fields. This is always fatal.
- =item "DC"/"decryption failed"
- A TLSCiphertext decrypted in an invalid way: either it wasn't an
- even multiple of the block length or its padding values, when
- checked, weren't correct. This message is always fatal.
- =item "RO"/"record overflow"
- A TLSCiphertext record was received which had a length more than
- 2^14+2048 bytes, or a record decrypted to a TLSCompressed record
- with more than 2^14+1024 bytes. This message is always fatal.
- =item "CA"/"unknown CA"
- A valid certificate chain or partial chain was received, but the
- certificate was not accepted because the CA certificate could not
- be located or couldn't be matched with a known, trusted CA. This
- message is always fatal.
- =item "AD"/"access denied"
- A valid certificate was received, but when access control was
- applied, the sender decided not to proceed with negotiation.
- This message is always fatal.
- =item "DE"/"decode error"
- A message could not be decoded because some field was out of the
- specified range or the length of the message was incorrect. This
- message is always fatal.
- =item "CY"/"decrypt error"
- A handshake cryptographic operation failed, including being
- unable to correctly verify a signature, decrypt a key exchange,
- or validate a finished message.
- =item "ER"/"export restriction"
- A negotiation not in compliance with export restrictions was
- detected; for example, attempting to transfer a 1024 bit
- ephemeral RSA key for the RSA_EXPORT handshake method. This
- message is always fatal.
- =item "PV"/"protocol version"
- The protocol version the client has attempted to negotiate is
- recognized, but not supported. (For example, old protocol
- versions might be avoided for security reasons). This message is
- always fatal.
- =item "IS"/"insufficient security"
- Returned instead of handshake_failure when a negotiation has
- failed specifically because the server requires ciphers more
- secure than those supported by the client. This message is always
- fatal.
- =item "IE"/"internal error"
- An internal error unrelated to the peer or the correctness of the
- protocol makes it impossible to continue (such as a memory
- allocation failure). This message is always fatal.
- =item "US"/"user canceled"
- This handshake is being canceled for some reason unrelated to a
- protocol failure. If the user cancels an operation after the
- handshake is complete, just closing the connection by sending a
- close_notify is more appropriate. This alert should be followed
- by a close_notify. This message is generally a warning.
- =item "NR"/"no renegotiation"
- Sent by the client in response to a hello request or by the
- server in response to a client hello after initial handshaking.
- Either of these would normally lead to renegotiation; when that
- is not appropriate, the recipient should respond with this alert;
- at that point, the original requester can decide whether to
- proceed with the connection. One case where this would be
- appropriate would be where a server has spawned a process to
- satisfy a request; the process might receive security parameters
- (key length, authentication, etc.) at startup and it might be
- difficult to communicate changes to these parameters after that
- point. This message is always a warning.
- =item "UP"/"unknown PSK identity"
- Sent by the server to indicate that it does not recognize a PSK
- identity or an SRP identity.
- =item "UK"/"unknown"
- This indicates that no description is available for this alert type.
- Probably B<value> does not contain a correct alert message.
- =back
- =head1 SEE ALSO
- L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
- =cut
|