srtpdec

gstrtpdec acts as a decoder that removes security from SRTP and SRTCP packets (encryption and authentication) and out RTP and RTCP. It receives packet of type 'application/x-srtp' or 'application/x-srtcp' on its sink pad, and outs packets of type 'application/x-rtp' or 'application/x-rtcp' on its source pad.

For each packet received, it checks if the internal SSRC is in the list of streams already in use. If this is not the case, it sends a signal to the user to get the needed parameters to create a new stream : master key, encryption and authentication mechanisms for both RTP and RTCP. If the user can't provide those parameters, the buffer is dropped and a warning is emitted.

This element uses libsrtp library. The encryption and authentication mechanisms available are :

Encryption

  • AES_ICM 256 bits (maximum security)
  • AES_ICM 128 bits (default)
  • NULL

Authentication

  • HMAC_SHA1 80 bits (default, maximum protection)
  • HMAC_SHA1 32 bits
  • NULL

Note that for SRTP protection, authentication is mandatory (non-null) if encryption is used (non-null).

Each packet received is first analysed (checked for valid SSRC) then its buffer is unprotected with libsrtp, then pushed on the source pad. If protection failed or the stream could not be created, the buffer is dropped and a warning is emitted.

When the maximum usage of the master key is reached, a soft-limit signal is sent to the user, and new parameters (master key) are needed in return. If the hard limit is reached, a flag is set and every subsequent packet is dropped, until a new key is set and the stream has been updated.

If a stream is to be shared between multiple clients the SRTP rollover counter for a given SSRC must be set in the caps "roc" field when the request-key signal is emitted by the decoder. The rollover counters should have been transmitted by a signaling protocol by some other means. If no rollover counter is provided by the user, 0 is used by default.

It is possible to receive a stream protected by multiple master keys, each buffer then contains a Master Key Identifier (MKI) to identify which key was used for this buffer. If multiple keys are needed, the first key can be specified in the caps as "srtp-key=(buffer)key1data, mki=(buffer)mki1data", then the second one can be given in the same caps as "srtp-key2=(buffer)key2data, mki2=(buffer)mki2data", and more can be added up to 15.

Example pipelines

 gst-launch-1.0 udpsrc port=5004 caps='application/x-srtp, payload=(int)8, ssrc=(uint)1356955624, srtp-key=(buffer)012345678901234567890123456789012345678901234567890123456789, srtp-cipher=(string)aes-128-icm, srtp-auth=(string)hmac-sha1-80, srtcp-cipher=(string)aes-128-icm, srtcp-auth=(string)hmac-sha1-80' !  srtpdec ! rtppcmadepay ! alawdec ! pulsesink

Receive PCMA SRTP packets through UDP using caps to specify master key and protection.

 gst-launch-1.0 audiotestsrc ! alawenc ! rtppcmapay ! 'application/x-rtp, payload=(int)8, ssrc=(uint)1356955624' ! srtpenc key="012345678901234567890123456789012345678901234567890123456789" ! udpsink port=5004

Send PCMA SRTP packets through UDP, nothing how the SSRC is forced so that the receiver will recognize it.

Hierarchy

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstElement
                ╰──srtpdec

Factory details

Authors: – Gabriel Millaire

Classification:Filter/Network/SRTP

Rank – none

Plugin – srtp

Package – GStreamer Bad Plug-ins

Pad Templates

rtcp_sink

application/x-srtcp:

Presencealways

Directionsink

Object typeGstPad


rtcp_src

application/x-rtcp:

Presencealways

Directionsrc

Object typeGstPad


rtp_sink

application/x-srtp:

Presencealways

Directionsink

Object typeGstPad


rtp_src

application/x-rtp:

Presencealways

Directionsrc

Object typeGstPad


Signals

clear-keys

clear_keys_callback (GstElement * gstsrtpdec,
                     gpointer udata)
def clear_keys_callback (gstsrtpdec, udata):
    #python callback for the 'clear-keys' signal
function clear_keys_callback(gstsrtpdec: GstElement * gstsrtpdec, udata: gpointer udata): {
    // javascript callback for the 'clear-keys' signal
}

Clear the internal list of streams

Parameters:

gstsrtpdec

the element on which the signal is emitted

udata
No description available

Flags: Run Last / Action


hard-limit

GstCaps *
hard_limit_callback (GstElement * gstsrtpdec,
                     guint ssrc,
                     gpointer udata)
def hard_limit_callback (gstsrtpdec, ssrc, udata):
    #python callback for the 'hard-limit' signal
function hard_limit_callback(gstsrtpdec: GstElement * gstsrtpdec, ssrc: guint ssrc, udata: gpointer udata): {
    // javascript callback for the 'hard-limit' signal
}

Signal emitted when the stream with ssrc has reached the hard limit of utilisation of it's master encryption key. User should provide a new key and new RTP and RTCP encryption ciphers and authentication, and return them wrapped in a GstCaps. If user could not provide those parameters or signal is not answered, the buffers of this stream will be dropped.

Parameters:

gstsrtpdec

the element on which the signal is emitted

ssrc

The unique SSRC of the stream

udata
No description available
Returns ( GstCaps * ) –
No description available

Flags: Run Last


remove-key

remove_key_callback (GstElement * gstsrtpdec,
                     guint ssrc,
                     gpointer udata)
def remove_key_callback (gstsrtpdec, ssrc, udata):
    #python callback for the 'remove-key' signal
function remove_key_callback(gstsrtpdec: GstElement * gstsrtpdec, ssrc: guint ssrc, udata: gpointer udata): {
    // javascript callback for the 'remove-key' signal
}

Removes keys for a specific SSRC

Parameters:

gstsrtpdec

the element on which the signal is emitted

ssrc

The SSRC for which to remove the key.

udata
No description available

Flags: Run Last / Action


request-key

GstCaps *
request_key_callback (GstElement * gstsrtpdec,
                      guint ssrc,
                      gpointer udata)
def request_key_callback (gstsrtpdec, ssrc, udata):
    #python callback for the 'request-key' signal
function request_key_callback(gstsrtpdec: GstElement * gstsrtpdec, ssrc: guint ssrc, udata: gpointer udata): {
    // javascript callback for the 'request-key' signal
}

Signal emitted to get the parameters relevant to stream with ssrc. User should provide the key and the RTP and RTCP encryption ciphers and authentication, and return them wrapped in a GstCaps.

Parameters:

gstsrtpdec

the element on which the signal is emitted

ssrc

The unique SSRC of the stream

udata
No description available
Returns ( GstCaps * ) –
No description available

Flags: Run Last


soft-limit

GstCaps *
soft_limit_callback (GstElement * gstsrtpdec,
                     guint ssrc,
                     gpointer udata)
def soft_limit_callback (gstsrtpdec, ssrc, udata):
    #python callback for the 'soft-limit' signal
function soft_limit_callback(gstsrtpdec: GstElement * gstsrtpdec, ssrc: guint ssrc, udata: gpointer udata): {
    // javascript callback for the 'soft-limit' signal
}

Signal emitted when the stream with ssrc has reached the soft limit of utilisation of it's master encryption key. User should provide a new key and new RTP and RTCP encryption ciphers and authentication, and return them wrapped in a GstCaps.

Parameters:

gstsrtpdec

the element on which the signal is emitted

ssrc

The unique SSRC of the stream

udata
No description available
Returns ( GstCaps * ) –
No description available

Flags: Run Last


Properties

replay-window-size

“replay-window-size” guint

Size of the replay protection window

Flags : Read / Write

Default value : 128


stats

“stats” GstStructure *

Various statistics

Flags : Read

Default value :

application/x-srtp-decoder-stats, streams=(int)<  >;

The results of the search are