Alert description strings for TLSv1 and documentation.

diff --git a/CHANGES b/CHANGES
index d7e86490bcbee3db1c6072723c9abd72f6e44e1b..aef5034c8088cc29ce9dbe9e1feac2aba16a4aee 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -12,6 +12,9 @@
          *) applies to 0.9.6a/0.9.6b/0.9.6c and 0.9.7
          +) applies to 0.9.7 only
 
+  *) Add alert descriptions for TLSv1 to SSL_alert_desc_string[_long]().
+     [Lutz Jaenicke]
+
   +) Add EVP test program.
      [Ben Laurie]
 

diff --git a/doc/ssl/SSL_alert_type_string.pod b/doc/ssl/SSL_alert_type_string.pod
new file mode 100644 (file)
index 0000000..1d8e524
--- /dev/null
+++ b/doc/ssl/SSL_alert_type_string.pod
@@ -0,0 +1,228 @@
+=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 the 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 the a two letter string as a short form
+describing the reason of the alert specified by B<value>.
+
+SSL_alert_desc_string_long() returns the 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 "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)>
+
+=cut

diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 6fc5f9050b0f909e960ce45268530e54f935a596..bee252aa8b0067c9d70970202158e5b29b1b7187 100644 (file)
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -676,6 +676,7 @@ L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
 L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
 L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
 L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>,
 L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>,
 L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
 L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,

diff --git a/ssl/ssl_stat.c b/ssl/ssl_stat.c
index d74e0aa7c1c043db34ea7b2a1b123df68135a058..e8b4f56aae73a2e4a85373eff917d1f0d26333a4 100644 (file)
--- a/ssl/ssl_stat.c
+++ b/ssl/ssl_stat.c
@@ -387,6 +387,18 @@ char *SSL_alert_desc_string(int value)
        case SSL3_AD_CERTIFICATE_EXPIRED:       str="CE"; break;
        case SSL3_AD_CERTIFICATE_UNKNOWN:       str="CU"; break;
        case SSL3_AD_ILLEGAL_PARAMETER:         str="IP"; break;
+       case TLS1_AD_DECRYPTION_FAILED          str="DC"; break;
+       case TLS1_AD_RECORD_OVERFLOW            str="RO"; break;
+       case TLS1_AD_UNKNOWN_CA                 str="CA"; break;
+       case TLS1_AD_ACCESS_DENIED              str="AD"; break;
+       case TLS1_AD_DECODE_ERROR               str="DE"; break;
+       case TLS1_AD_DECRYPT_ERROR              str="CY"; break;
+       case TLS1_AD_EXPORT_RESTRICTION         str="ER"; break;
+       case TLS1_AD_PROTOCOL_VERSION           str="PV"; break;
+       case TLS1_AD_INSUFFICIENT_SECURITY      str="IS"; break;
+       case TLS1_AD_INTERNAL_ERROR             str="IE"; break;
+       case TLS1_AD_USER_CANCELLED             str="US"; break;
+       case TLS1_AD_NO_RENEGOTIATION           str="NR"; break;
        default:                                str="UK"; break;
                }
        return(str);
@@ -434,6 +446,42 @@ char *SSL_alert_desc_string_long(int value)
        case SSL3_AD_ILLEGAL_PARAMETER:
                str="illegal parameter";
                break;
+       case TLS1_AD_DECRYPTION_FAILED
+               str="decryption failed";
+               break;
+       case TLS1_AD_RECORD_OVERFLOW
+               str="record overflow";
+               break;
+       case TLS1_AD_UNKNOWN_CA
+               str="unknown CA";
+               break;
+       case TLS1_AD_ACCESS_DENIED
+               str="access denied";
+               break;
+       case TLS1_AD_DECODE_ERROR
+               str="decode error";
+               break;
+       case TLS1_AD_DECRYPT_ERROR
+               str="decrypt error";
+               break;
+       case TLS1_AD_EXPORT_RESTRICTION
+               str="export restriction";
+               break;
+       case TLS1_AD_PROTOCOL_VERSION
+               str="protocol version";
+               break;
+       case TLS1_AD_INSUFFICIENT_SECURITY
+               str="insufficient security";
+               break;
+       case TLS1_AD_INTERNAL_ERROR
+               str="internal error";
+               break;
+       case TLS1_AD_USER_CANCELLED
+               str="user canceled";
+               break;
+       case TLS1_AD_NO_RENEGOTIATION
+               str="no renegotiation";
+               break;
        default: str="unknown"; break;
                }
        return(str);