srtpenc: GStreamer Bad Plugins 1.0 Plugins Reference Manual

## 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

void | soft-limit | Run Last
guint | get-rollover-counter | Action

## Types and Values

struct | GstSrtpEnc

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── 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 mecanisms 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;

## 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