diff options
author | Lutz Jänicke <jaenicke@openssl.org> | 2001-08-19 16:20:42 +0000 |
---|---|---|
committer | Lutz Jänicke <jaenicke@openssl.org> | 2001-08-19 16:20:42 +0000 |
commit | a403188f92101512d4d3e45bc7b8e047d283d9d2 (patch) | |
tree | ced6323b0ea1894a2ce8907c1eb480ca68191691 /doc | |
parent | 82b223052712859ccb71d587d4e29394dae813e8 (diff) |
Alert description strings for TLSv1 and documentation.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_alert_type_string.pod | 228 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 1 |
2 files changed, 229 insertions, 0 deletions
diff --git a/doc/ssl/SSL_alert_type_string.pod b/doc/ssl/SSL_alert_type_string.pod new file mode 100644 index 0000000000..1d8e524f1b --- /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 6fc5f9050b..bee252aa8b 100644 --- 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)>, |