Next: Priority Strings, Previous: Buffered data transfer, Up: How to use GnuTLS in applications [Contents][Index]
During a TLS connection alert messages may be exchanged by the
two peers. Those messages may be fatal, meaning the connection
must be terminated afterwards, or warning when something needs
to be reported to the peer, but without interrupting the session.
The error codes GNUTLS_E_WARNING_ALERT_RECEIVED
or GNUTLS_E_FATAL_ALERT_RECEIVED
signal those alerts
when received, and may be returned by all GnuTLS functions that receive
data from the peer, being gnutls_handshake and gnutls_record_recv.
If those error codes are received the alert and its level should be logged or reported to the peer using the functions below.
session: is a gnutls_session_t
type.
This function will return the last alert number received. This
function should be called when GNUTLS_E_WARNING_ALERT_RECEIVED
or
GNUTLS_E_FATAL_ALERT_RECEIVED
errors are returned by a gnutls
function. The peer may send alerts if he encounters an error.
If no alert has been received the returned value is undefined.
Returns: the last alert received, a
gnutls_alert_description_t
value.
alert: is an alert number.
This function will return a string that describes the given alert
number, or NULL
. See gnutls_alert_get()
.
Returns: string corresponding to gnutls_alert_description_t
value.
The peer may also be warned or notified of a fatal issue by using one of the functions below. All the available alerts are listed in The Alert Protocol.
session: is a gnutls_session_t
type.
level: is the level of the alert
desc: is the alert description
This function will send an alert to the peer in order to inform him of something important (eg. his Certificate could not be verified). If the alert level is Fatal then the peer is expected to close the connection, otherwise he may ignore the alert and continue.
The error code of the underlying record send function will be
returned, so you may also receive GNUTLS_E_INTERRUPTED
or
GNUTLS_E_AGAIN
as well.
Returns: On success, GNUTLS_E_SUCCESS
(0) is returned, otherwise
an error code is returned.
err: is a negative integer
level: the alert level will be stored there
Get an alert depending on the error code returned by a gnutls
function. All alerts sent by this function should be considered
fatal. The only exception is when err
is GNUTLS_E_REHANDSHAKE
,
where a warning alert should be sent to the peer indicating that no
renegotiation will be performed.
If there is no mapping to a valid alert the alert to indicate
internal error (GNUTLS_A_INTERNAL_ERROR
) is returned.
Returns: the alert code to use for a particular error code.
Next: Priority Strings, Previous: Buffered data transfer, Up: How to use GnuTLS in applications [Contents][Index]