srtpenc

srtpenc

Properties

GstBuffer * key Read / Write
gboolean random-key Read / Write
GstSrtpAuthType rtcp-auth Read / Write
GstSrtpCipherType rtcp-cipher Read / Write
GstSrtpAuthType rtp-auth Read / Write
GstSrtpCipherType rtp-cipher Read / Write
guint replay-window-size Read / Write
gboolean allow-repeat-tx Read / Write
GstStructure * stats Read

Signals

Types and Values

struct GstSrtpEnc

Description

gstrtpenc acts as an encoder that adds security to RTP and RTCP packets in the form of encryption and authentication. It outs SRTP and SRTCP.

An application can request multiple RTP and RTCP pads to protect, but every sink pad requested must receive packets from the same source (identical SSRC). If a packet received contains a different SSRC, a warning is emited and the valid SSRC is forced on the packet.

This element uses libsrtp library. When receiving the first packet, the library is initialized with a new stream (based on the SSRC). It uses the default RTP and RTCP encryption and authentication mechanisms, unless the user has set the relevant properties first. It also uses a master key that MUST be set by property (key) at the beginning. The master key must be of a maximum length of 46 characters (14 characters for the salt plus the key). The encryption and authentication mechanisms available are :

Encryption (properties rtp-cipher and rtcp-cipher)

  • AES_ICM 256 bits (maximum security)

  • AES_ICM 128 bits (default)

  • NULL

Authentication (properties rtp-auth and rtcp-auth)

  • 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).

When requested to create a sink pad, a linked source pad is created. Each packet received is first analysed (checked for valid SSRC) then its buffer is protected 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. The packets pushed on the source pad are of type 'application/x-srtp' or 'application/x-srtcp'.

When the maximum usage of the master key is reached, a soft-limit signal is sent to the user. The user must then set a new master key by property. 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 it is also possible to request the internal SRTP rollover counter for a given SSRC. The rollover counter should be then transmitted and used by the clients to authenticate and decrypt the packets. Failing to do that the clients will start with a rollover counter of 0 which will probably be incorrect if the stream has been transmitted for a while to other clients.

This element supports sending with a single Master Key, it is possible to set the Master Key Identifier (MKI) using the "mki" property. If this property is set, the MKI will be added to every buffer.

Synopsis

Element Information

plugin

srtp

author

Gabriel Millaire <millaire.gabriel@collabora.com>

class

Filter/Network/SRTP

Element Pads

name

rtcp_sink_%u

direction

sink

presence

request

details

application/x-rtcp

name

rtp_sink_%u

direction

sink

presence

request

details

application/x-rtp

name

rtcp_src_%u

direction

source

presence

sometimes

details

application/x-srtcp

name

rtp_src_%u

direction

source

presence

sometimes

details

application/x-srtp

Functions

Types and Values

struct GstSrtpEnc

struct GstSrtpEnc {
  GstElement element;

  gboolean random_key;

  GstBuffer *key;
  guint rtp_cipher;
  guint rtp_auth;
  guint rtcp_cipher;
  guint rtcp_auth;
  GstBuffer *mki;

  srtp_t session;
  gboolean first_session;
  gboolean key_changed;

  guint replay_window_size;
  gboolean allow_repeat_tx;

  GHashTable *ssrcs_set;
};

Property Details

The “key” property

  “key”                      GstBuffer *

Master key (minimum of 30 and maximum of 46 bytes).

Flags: Read / Write


The “random-key” property

  “random-key”               gboolean

Generate a random key if TRUE.

Flags: Read / Write

Default value: FALSE


The “rtcp-auth” property

  “rtcp-auth”                GstSrtpAuthType

RTCP Authentication.

Flags: Read / Write

Default value: GST_SRTP_AUTH_HMAC_SHA1_80


The “rtcp-cipher” property

  “rtcp-cipher”              GstSrtpCipherType

RTCP Cipher.

Flags: Read / Write

Default value: GST_SRTP_CIPHER_AES_128_ICM


The “rtp-auth” property

  “rtp-auth”                 GstSrtpAuthType

RTP Authentication.

Flags: Read / Write

Default value: GST_SRTP_AUTH_HMAC_SHA1_80


The “rtp-cipher” property

  “rtp-cipher”               GstSrtpCipherType

RTP Cipher.

Flags: Read / Write

Default value: GST_SRTP_CIPHER_AES_128_ICM


The “replay-window-size” property

  “replay-window-size”       guint

Size of the replay protection window.

Flags: Read / Write

Allowed values: [64,32768]

Default value: 128


The “allow-repeat-tx” property

  “allow-repeat-tx”          gboolean

Whether retransmissions of packets with the same sequence number are allowed(Note that such repeated transmissions must have the same RTP payload, or a severe security weakness is introduced!).

Flags: Read / Write

Default value: FALSE


The “stats” property

  “stats”                    GstStructure *

Various statistics.

Flags: Read

Signal Details

The “soft-limit” signal

void
user_function (GstSrtpEnc *gstsrtpenc,
               gpointer    user_data)

Signal emited when the stream with ssrc has reached the soft limit of utilisation of it's master encryption key. User should provide a new key by setting the “key” property.

Parameters

gstsrtpenc

the element on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “get-rollover-counter” signal

guint
user_function (GstSrtpEnc *gstsrtpenc,
               guint       arg1,
               gpointer    user_data)

Flags: Action

See Also

srtpdec