SRTP events and callbacks
Secure RTP

libSRTP can use a user-provided callback function to handle events. More...

## Data Structures

struct | srtp_event_data_t
| srtp_event_data_t is the structure passed as a callback to the event handler function More...

## Typedefs

typedef struct srtp_event_data_t | srtp_event_data_t
| srtp_event_data_t is the structure passed as a callback to the event handler function More...
typedef void() | srtp_event_handler_func_t(srtp_event_data_t *data)
| srtp_event_handler_func_t is the function prototype for the event handler. More...
typedef void() | srtp_log_handler_func_t(srtp_log_level_t level, const char *msg, void *data)
| srtp_log_handler_func_t is the function prototype for the log handler. More...

## Enumerations

enum | srtp_event_t { event_ssrc_collision, event_key_soft_limit, event_key_hard_limit, event_packet_index_limit }
| srtp_event_t defines events that need to be handled More...
enum | srtp_log_level_t { srtp_log_level_error, srtp_log_level_warning, srtp_log_level_info, srtp_log_level_debug }
| srtp_log_level_t defines log levels. More...

## Functions

srtp_err_status_t | srtp_install_event_handler (srtp_event_handler_func_t func)
| sets the event handler to the function supplied by the caller. More...
const char * | srtp_get_version_string (void)
| Returns the version string of the library.
unsigned int | srtp_get_version (void)
| Returns the numeric representation of the library version.
srtp_err_status_t | srtp_set_debug_module (const char *mod_name, int v)
| srtp_set_debug_module(mod_name, v) More...
srtp_err_status_t | srtp_list_debug_modules (void)
| srtp_list_debug_modules() outputs a list of debugging modules
srtp_err_status_t | srtp_install_log_handler (srtp_log_handler_func_t func, void *data)
| sets the log handler to the function supplied by the caller. More...
srtp_err_status_t | srtp_get_protect_trailer_length (srtp_t session, uint32_t use_mki, uint32_t mki_index, uint32_t *length)
| srtp_get_protect_trailer_length(session, use_mki, mki_index, length) More...
srtp_err_status_t | srtp_get_protect_rtcp_trailer_length (srtp_t session, uint32_t use_mki, uint32_t mki_index, uint32_t *length)
| srtp_get_protect_rtcp_trailer_length(session, use_mki, mki_index, length) More...
srtp_err_status_t | srtp_set_stream_roc (srtp_t session, uint32_t ssrc, uint32_t roc)
| srtp_set_stream_roc(session, ssrc, roc) More...
srtp_err_status_t | srtp_get_stream_roc (srtp_t session, uint32_t ssrc, uint32_t *roc)
| srtp_get_stream_roc(session, ssrc, roc) More...

## Detailed Description

libSRTP allows a user to provide a callback function to handle events that need to be dealt with outside of the data plane (see the enum srtp_event_t for a description of these events). Dealing with these events is not a strict necessity; they are not security-critical, but the application may suffer if they are not handled. The function srtp_set_event_handler() is used to provide the callback function.

A default event handler that merely reports on the events as they happen is included. It is also possible to set the event handler function to NULL, in which case all events will just be silently ignored.

## Typedef Documentation

## srtp_event_data_t

typedef struct srtp_event_data_t srtp_event_data_t

The struct srtp_event_data_t holds the data passed to the event handler function.

## srtp_event_handler_func_t

typedef void() srtp_event_handler_func_t(srtp_event_data_t *data)

The typedef srtp_event_handler_func_t is the prototype for the event handler function. It has as its only argument an srtp_event_data_t which describes the event that needs to be handled. There can only be a single, global handler for all events in libSRTP.

## srtp_log_handler_func_t

typedef void() srtp_log_handler_func_t(srtp_log_level_t level, const char *msg, void *data)

The typedef srtp_event_handler_func_t is the prototype for the event handler function. It has as srtp_log_level_t, log message and data as arguments. There can only be a single, global handler for all log messages in libSRTP.

## Enumeration Type Documentation

## srtp_event_t

enum srtp_event_t

The enum srtp_event_t defines events that need to be handled outside the `data plane', such as SSRC collisions and key expirations.

When a key expires or the maximum number of packets has been reached, an SRTP stream will enter an `expired' state in which no more packets can be protected or unprotected. When this happens, it is likely that you will want to either deallocate the stream (using srtp_remove_stream()), and possibly allocate a new one.

When an SRTP stream expires, the other streams in the same session are unaffected, unless key sharing is used by that stream. In the latter case, all of the streams in the session will expire.

Enumerator
event_ssrc_collision | An SSRC collision occured.
event_key_soft_limit | An SRTP stream reached the soft key usage limit and will expire soon.
event_key_hard_limit | An SRTP stream reached the hard key usage limit and has expired.
event_packet_index_limit | An SRTP stream reached the hard packet limit (2^48 packets).

## srtp_log_level_t

enum srtp_log_level_t

The enumeration srtp_log_level_t defines log levels reported in the srtp_log_handler_func_t.

Enumerator
srtp_log_level_error | log level is reporting an error message
srtp_log_level_warning | log level is reporting a warning message
srtp_log_level_info | log level is reporting an info message
srtp_log_level_debug | log level is reporting a debug message

## Function Documentation

## srtp_get_protect_rtcp_trailer_length()

srtp_err_status_t srtp_get_protect_rtcp_trailer_length | ( | srtp_t | session,
|  | uint32_t | use_mki,
|  | uint32_t | mki_index,
|  | uint32_t * | length
| ) |  |

Determines the length of the amount of data Lib SRTP will add to the packet during the protect process. The length is returned in the length parameter

returns err_status_ok on success, err_status_bad_mki if the MKI index is invalid

## srtp_get_protect_trailer_length()

srtp_err_status_t srtp_get_protect_trailer_length | ( | srtp_t | session,
|  | uint32_t | use_mki,
|  | uint32_t | mki_index,
|  | uint32_t * | length
| ) |  |

Determines the length of the amount of data Lib SRTP will add to the packet during the protect process. The length is returned in the length parameter

returns err_status_ok on success, err_status_bad_mki if the MKI index is invalid

## srtp_get_stream_roc()

srtp_err_status_t srtp_get_stream_roc | ( | srtp_t | session,
|  | uint32_t | ssrc,
|  | uint32_t * | roc
| ) |  |

Get the roll-over-counter on a session for a given SSRC

returns err_status_ok on success, srtp_err_status_bad_param if there is no stream found

## srtp_install_event_handler()

srtp_err_status_t srtp_install_event_handler | ( | srtp_event_handler_func_t | func | ) |

The function call srtp_install_event_handler(func) sets the event handler function to the value func. The value NULL is acceptable as an argument; in this case, events will be ignored rather than handled.

Parameters

  func | is a pointer to a fuction that takes an srtp_event_data_t pointer as an argument and returns void. This function will be used by libSRTP to handle events.

## srtp_install_log_handler()

srtp_err_status_t srtp_install_log_handler | ( | srtp_log_handler_func_t | func,
|  | void * | data
| ) |  |

The function call srtp_install_log_handler(func) sets the log handler function to the value func. The value NULL is acceptable as an argument; in this case, log messages will be ignored. This function can be called before srtp_init() inorder to capture any logging during start up.

Parameters

  func | is a pointer to a fuction of type srtp_log_handler_func_t. This function will be used by libSRTP to output log messages.
  data | is a user pointer that will be returned as the data argument in func.

## srtp_set_debug_module()

srtp_err_status_t srtp_set_debug_module | ( | const char * | mod_name,
|  | int | v
| ) |  |

sets dynamic debugging to the value v (0 for off, 1 for on) for the debug module with the name mod_name

returns err_status_ok on success, err_status_fail otherwise

## srtp_set_stream_roc()

srtp_err_status_t srtp_set_stream_roc | ( | srtp_t | session,
|  | uint32_t | ssrc,
|  | uint32_t | roc
| ) |  |

Set the roll-over-counter on a session for a given SSRC

returns err_status_ok on success, srtp_err_status_bad_param if there is no stream found