SSL Alert Callback

Overview

Since version 3.30 on Fedora (or 3.28 on RHEL) NSS provides a callback mechanism for alerts received and sent by SSL socket.

Data Structure

The data structure is defined in ssl.h:

typedef PRUint8 SSLAlertLevel;
typedef PRUint8 SSLAlertDescription;

typedef struct {
    SSLAlertLevel level;
    SSLAlertDescription description;
} SSLAlert;

The values of alert level and description are defined internally in ssl3prot.h:

typedef enum { alert_warning = 1,
               alert_fatal = 2 } SSL3AlertLevel;

typedef enum {
    close_notify = 0,
    end_of_early_data = 1, /* TLS 1.3 */
    unexpected_message = 10,
    bad_record_mac = 20,
    decryption_failed_RESERVED = 21, /* do not send; see RFC 5246 */
    record_overflow = 22,            /* TLS only */
    decompression_failure = 30,
    handshake_failure = 40,
    no_certificate = 41, /* SSL3 only, NOT TLS */
    bad_certificate = 42,
    unsupported_certificate = 43,
    certificate_revoked = 44,
    certificate_expired = 45,
    certificate_unknown = 46,
    illegal_parameter = 47,

    /* All alerts below are TLS only. */
    unknown_ca = 48,
    access_denied = 49,
    decode_error = 50,
    decrypt_error = 51,
    export_restriction = 60,
    protocol_version = 70,
    insufficient_security = 71,
    internal_error = 80,
    inappropriate_fallback = 86, /* could also be sent for SSLv3 */
    user_canceled = 90,
    no_renegotiation = 100,

    /* Alerts for client hello extensions */
    missing_extension = 109,
    unsupported_extension = 110,
    certificate_unobtainable = 111,
    unrecognized_name = 112,
    bad_certificate_status_response = 113,
    bad_certificate_hash_value = 114,
    no_application_protocol = 120,

    /* invalid alert */
    no_alert = 256
} SSL3AlertDescription;

Callback Function

The callback function prototype is defined in ssl.h:

typedef void(PR_CALLBACK *SSLAlertCallback)(const PRFileDesc *fd, void *arg,
                                            const SSLAlert *alert);

The prototype can be used to define callback functions for alerts received and sent:

void alertReceivedCallback(PRFileDec *fd, void *arg, SSLAlert *alert) {
    ...
}

void alertSentCallback(PRFileDec *fd, void *arg, SSLAlert *alert) {
    ...
}

For example, see the JSSL_AlertReceivedCallback() and JSSL_AlertSentCallback() functions in JSS.

Callback Registration

The callback registration functions are defined in ssl.h:

SSL_IMPORT SECStatus SSL_AlertReceivedCallback(PRFileDesc *fd, SSLAlertCallback cb,
                                               void *arg);
SSL_IMPORT SECStatus SSL_AlertSentCallback(PRFileDesc *fd, SSLAlertCallback cb,
void *arg);

To register the above callback functions:

PRFileDesc* socketFD = ...;
SECStatus status;

status = SSL_AlertReceivedCallback(socketFD, alertReceivedCallback, socket);

if (status != SECSuccess) {
    ...
}

status = SSL_AlertSentCallback(socketFD, alertSentCallback, socket);

if (status != SECSuccess) {
    ...
}

For example, see the JSSL_CreateSocketData() function in JSS.

See Also

• NSS Bug #956866: SSL alert callback

• JSS SSL Socket Listener

• PKI SSL Audit Design