1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  const char *SSL_alert_type_string(int value);
   12:  const char *SSL_alert_type_string_long(int value);
   13: 
   14:  const char *SSL_alert_desc_string(int value);
   15:  const char *SSL_alert_desc_string_long(int value);
   16: 
   17: =head1 DESCRIPTION
   18: 
   19: SSL_alert_type_string() returns a one letter string indicating the
   20: type of the alert specified by B<value>.
   21: 
   22: SSL_alert_type_string_long() returns a string indicating the type of the alert
   23: specified by B<value>.
   24: 
   25: SSL_alert_desc_string() returns a two letter string as a short form
   26: describing the reason of the alert specified by B<value>.
   27: 
   28: SSL_alert_desc_string_long() returns a string describing the reason
   29: of the alert specified by B<value>.
   30: 
   31: =head1 NOTES
   32: 
   33: When one side of an SSL/TLS communication wants to inform the peer about
   34: a special situation, it sends an alert. The alert is sent as a special message
   35: and does not influence the normal data stream (unless its contents results
   36: in the communication being canceled).
   37: 
   38: A warning alert is sent, when a non-fatal error condition occurs. The
   39: "close notify" alert is sent as a warning alert. Other examples for
   40: non-fatal errors are certificate errors ("certificate expired",
   41: "unsupported certificate"), for which a warning alert may be sent.
   42: (The sending party may however decide to send a fatal error.) The
   43: receiving side may cancel the connection on reception of a warning
   44: alert on it discretion.
   45: 
   46: Several alert messages must be sent as fatal alert messages as specified
   47: by the TLS RFC. A fatal alert always leads to a connection abort.
   48: 
   49: =head1 RETURN VALUES
   50: 
   51: The following strings can occur for SSL_alert_type_string() or
   52: SSL_alert_type_string_long():
   53: 
   54: =over 4
   55: 
   56: =item "W"/"warning"
   57: 
   58: =item "F"/"fatal"
   59: 
   60: =item "U"/"unknown"
   61: 
   62: This indicates that no support is available for this alert type.
   63: Probably B<value> does not contain a correct alert message.
   64: 
   65: =back
   66: 
   67: The following strings can occur for SSL_alert_desc_string() or
   68: SSL_alert_desc_string_long():
   69: 
   70: =over 4
   71: 
   72: =item "CN"/"close notify"
   73: 
   74: The connection shall be closed. This is a warning alert.
   75: 
   76: =item "UM"/"unexpected message"
   77: 
   78: An inappropriate message was received. This alert is always fatal
   79: and should never be observed in communication between proper
   80: implementations.
   81: 
   82: =item "BM"/"bad record mac"
   83: 
   84: This alert is returned if a record is received with an incorrect
   85: MAC. This message is always fatal.
   86: 
   87: =item "DF"/"decompression failure"
   88: 
   89: The decompression function received improper input (e.g. data
   90: that would expand to excessive length). This message is always
   91: fatal.
   92: 
   93: =item "HF"/"handshake failure"
   94: 
   95: Reception of a handshake_failure alert message indicates that the
   96: sender was unable to negotiate an acceptable set of security
   97: parameters given the options available. This is a fatal error.
   98: 
   99: =item "NC"/"no certificate"
  100: 
  101: A client, that was asked to send a certificate, does not send a certificate
  102: (SSLv3 only).
  103: 
  104: =item "BC"/"bad certificate"
  105: 
  106: A certificate was corrupt, contained signatures that did not
  107: verify correctly, etc
  108: 
  109: =item "UC"/"unsupported certificate"
  110: 
  111: A certificate was of an unsupported type.
  112: 
  113: =item "CR"/"certificate revoked"
  114: 
  115: A certificate was revoked by its signer.
  116: 
  117: =item "CE"/"certificate expired"
  118: 
  119: A certificate has expired or is not currently valid.
  120: 
  121: =item "CU"/"certificate unknown"
  122: 
  123: Some other (unspecified) issue arose in processing the
  124: certificate, rendering it unacceptable.
  125: 
  126: =item "IP"/"illegal parameter"
  127: 
  128: A field in the handshake was out of range or inconsistent with
  129: other fields. This is always fatal.
  130: 
  131: =item "DC"/"decryption failed"
  132: 
  133: A TLSCiphertext decrypted in an invalid way: either it wasn't an
  134: even multiple of the block length or its padding values, when
  135: checked, weren't correct. This message is always fatal.
  136: 
  137: =item "RO"/"record overflow"
  138: 
  139: A TLSCiphertext record was received which had a length more than
  140: 2^14+2048 bytes, or a record decrypted to a TLSCompressed record
  141: with more than 2^14+1024 bytes. This message is always fatal.
  142: 
  143: =item "CA"/"unknown CA"
  144: 
  145: A valid certificate chain or partial chain was received, but the
  146: certificate was not accepted because the CA certificate could not
  147: be located or couldn't be matched with a known, trusted CA.  This
  148: message is always fatal.
  149: 
  150: =item "AD"/"access denied"
  151: 
  152: A valid certificate was received, but when access control was
  153: applied, the sender decided not to proceed with negotiation.
  154: This message is always fatal.
  155: 
  156: =item "DE"/"decode error"
  157: 
  158: A message could not be decoded because some field was out of the
  159: specified range or the length of the message was incorrect. This
  160: message is always fatal.
  161: 
  162: =item "CY"/"decrypt error"
  163: 
  164: A handshake cryptographic operation failed, including being
  165: unable to correctly verify a signature, decrypt a key exchange,
  166: or validate a finished message.
  167: 
  168: =item "ER"/"export restriction"
  169: 
  170: A negotiation not in compliance with export restrictions was
  171: detected; for example, attempting to transfer a 1024 bit
  172: ephemeral RSA key for the RSA_EXPORT handshake method. This
  173: message is always fatal.
  174: 
  175: =item "PV"/"protocol version"
  176: 
  177: The protocol version the client has attempted to negotiate is
  178: recognized, but not supported. (For example, old protocol
  179: versions might be avoided for security reasons). This message is
  180: always fatal.
  181: 
  182: =item "IS"/"insufficient security"
  183: 
  184: Returned instead of handshake_failure when a negotiation has
  185: failed specifically because the server requires ciphers more
  186: secure than those supported by the client. This message is always
  187: fatal.
  188: 
  189: =item "IE"/"internal error"
  190: 
  191: An internal error unrelated to the peer or the correctness of the
  192: protocol makes it impossible to continue (such as a memory
  193: allocation failure). This message is always fatal.
  194: 
  195: =item "US"/"user canceled"
  196: 
  197: This handshake is being canceled for some reason unrelated to a
  198: protocol failure. If the user cancels an operation after the
  199: handshake is complete, just closing the connection by sending a
  200: close_notify is more appropriate. This alert should be followed
  201: by a close_notify. This message is generally a warning.
  202: 
  203: =item "NR"/"no renegotiation"
  204: 
  205: Sent by the client in response to a hello request or by the
  206: server in response to a client hello after initial handshaking.
  207: Either of these would normally lead to renegotiation; when that
  208: is not appropriate, the recipient should respond with this alert;
  209: at that point, the original requester can decide whether to
  210: proceed with the connection. One case where this would be
  211: appropriate would be where a server has spawned a process to
  212: satisfy a request; the process might receive security parameters
  213: (key length, authentication, etc.) at startup and it might be
  214: difficult to communicate changes to these parameters after that
  215: point. This message is always a warning.
  216: 
  217: =item "UK"/"unknown"
  218: 
  219: This indicates that no description is available for this alert type.
  220: Probably B<value> does not contain a correct alert message.
  221: 
  222: =back
  223: 
  224: =head1 SEE ALSO
  225: 
  226: L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
  227: 
  228: =cut