## GstRTSPAuth GstRTSPAuth — Authentication and authorization |

## Functions

GstRTSPAuth * | gst_rtsp_auth_new ()
GTlsCertificate * | gst_rtsp_auth_get_tls_certificate ()
void | gst_rtsp_auth_set_tls_certificate ()
GTlsDatabase * | gst_rtsp_auth_get_tls_database ()
void | gst_rtsp_auth_set_tls_database ()
GTlsAuthenticationMode | gst_rtsp_auth_get_tls_authentication_mode ()
void | gst_rtsp_auth_set_tls_authentication_mode ()
void | gst_rtsp_auth_set_realm ()
gchar * | gst_rtsp_auth_get_realm ()
gchar * | gst_rtsp_auth_make_basic ()
void | gst_rtsp_auth_add_basic ()
void | gst_rtsp_auth_remove_basic ()
void | gst_rtsp_auth_add_digest ()
void | gst_rtsp_auth_remove_digest ()
gboolean | gst_rtsp_auth_parse_htdigest ()
gboolean | gst_rtsp_auth_check ()
GstRTSPToken * | gst_rtsp_auth_get_default_token ()
void | gst_rtsp_auth_set_default_token ()
GstRTSPAuthMethod | gst_rtsp_auth_get_supported_methods ()
void | gst_rtsp_auth_set_supported_methods ()

## Signals

gboolean | accept-certificate | Run Last

## Types and Values

struct | GstRTSPAuth
struct | GstRTSPAuthClass
#define | GST_RTSP_AUTH_CHECK_CONNECT
#define | GST_RTSP_AUTH_CHECK_URL
#define | GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_ACCESS
#define | GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT
#define | GST_RTSP_AUTH_CHECK_TRANSPORT_CLIENT_SETTINGS
#define | GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE
#define | GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS
#define | GST_RTSP_PERM_MEDIA_FACTORY_ACCESS
#define | GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT

## Object Hierarchy

        GObject
        ╰── GstRTSPAuth

## Description

The GstRTSPAuth object is responsible for checking if the current user is allowed to perform requested actions. The default implementation has some reasonable checks but subclasses can implement custom security policies.

A new auth object is made with `gst_rtsp_auth_new()`. It is usually configured on the GstRTSPServer object.

The RTSP server will call `gst_rtsp_auth_check()` with a string describing the check to perform. The possible checks are prefixed with GST_RTSP_AUTH_CHECK_*. Depending on the check, the default implementation will use the current GstRTSPToken, GstRTSPContext and GstRTSPPermissions on the object to check if an operation is allowed.

The default GstRTSPAuth object has support for basic authentication. With `gst_rtsp_auth_add_basic()` you can add a basic authentication string together with the GstRTSPToken that will become active when successfully authenticated.

When a TLS certificate has been set with `gst_rtsp_auth_set_tls_certificate()`, the default auth object will require the client to connect with a TLS connection.

Last reviewed on 2013-07-16 (1.0.0)

## Functions

### gst_rtsp_auth_new ()

    GstRTSPAuth *
    gst_rtsp_auth_new (void);

Create a new GstRTSPAuth instance.

#### Returns

a new GstRTSPAuth.

[transfer full]

### gst_rtsp_auth_get_tls_certificate ()

    GTlsCertificate *
    gst_rtsp_auth_get_tls_certificate (GstRTSPAuth *auth);

Get the GTlsCertificate used for negotiating TLS `auth` .

#### Parameters

auth | a GstRTSPAuth |

#### Returns

the GTlsCertificate of `auth` . `g_object_unref()` after usage.

[transfer full][nullable]

### gst_rtsp_auth_set_tls_certificate ()

    void
    gst_rtsp_auth_set_tls_certificate (GstRTSPAuth *auth,
                                       GTlsCertificate *cert);

Set the TLS certificate for the auth. Client connections will only be accepted when TLS is negotiated.

#### Parameters

auth | a GstRTSPAuth |
cert | a GTlsCertificate. | [transfer none][allow-none]

### gst_rtsp_auth_get_tls_database ()

    GTlsDatabase *
    gst_rtsp_auth_get_tls_database (GstRTSPAuth *auth);

Get the GTlsDatabase used for verifying client certificate.

#### Parameters

auth | a GstRTSPAuth |

#### Returns

the GTlsDatabase of `auth` . `g_object_unref()` after usage.

[transfer full][nullable]

Since: 1.6

### gst_rtsp_auth_set_tls_database ()

    void
    gst_rtsp_auth_set_tls_database (GstRTSPAuth *auth,
                                    GTlsDatabase *database);

Sets the certificate database that is used to verify peer certificates. If set to `NULL` (the default), then peer certificate validation will always set the `G_TLS_CERTIFICATE_UNKNOWN_CA` error.

#### Parameters

auth | a GstRTSPAuth |
database | a GTlsDatabase. | [transfer none][allow-none]

Since: 1.6

### gst_rtsp_auth_get_tls_authentication_mode ()

    GTlsAuthenticationMode
    gst_rtsp_auth_get_tls_authentication_mode
                                   (GstRTSPAuth *auth);

Get the GTlsAuthenticationMode.

#### Parameters

auth | a GstRTSPAuth |

#### Returns

the GTlsAuthenticationMode.

[transfer full]

### gst_rtsp_auth_set_tls_authentication_mode ()

    void
    gst_rtsp_auth_set_tls_authentication_mode
                                   (GstRTSPAuth *auth,
                                    GTlsAuthenticationMode mode);

The GTlsAuthenticationMode to set on the underlying GTlsServerConnection. When set to another value than `G_TLS_AUTHENTICATION_NONE`, “accept-certificate” signal will be emitted and must be handled.

#### Parameters

auth | a GstRTSPAuth |
mode | a GTlsAuthenticationMode |

Since: 1.6

### gst_rtsp_auth_set_realm ()

    void
    gst_rtsp_auth_set_realm (GstRTSPAuth *auth,
                             const gchar *realm);

Set the `realm` of `auth`

Since: 1.16

### gst_rtsp_auth_get_realm ()

    gchar *
    gst_rtsp_auth_get_realm (GstRTSPAuth *auth);

#### Returns

the `realm` of `auth` .

[transfer full]

Since: 1.16

### gst_rtsp_auth_make_basic ()

    gchar *
    gst_rtsp_auth_make_basic (const gchar *user,
                              const gchar *pass);

Construct a Basic authorisation token from `user` and `pass` .

#### Parameters

user | a userid |
pass | a password |

#### Returns

the base64 encoding of the string `user` :`pass` . `g_free()` after usage.

[transfer full]

### gst_rtsp_auth_add_basic ()

    void
    gst_rtsp_auth_add_basic (GstRTSPAuth *auth,
                             const gchar *basic,
                             GstRTSPToken *token);

Add a basic token for the default authentication algorithm that enables the client with privileges listed in `token` .

#### Parameters

auth | a GstRTSPAuth |
basic | the basic token |
token | authorisation token. | [transfer none]

### gst_rtsp_auth_remove_basic ()

    void
    gst_rtsp_auth_remove_basic (GstRTSPAuth *auth,
                                const gchar *basic);

Removes `basic` authentication token.

#### Parameters

auth | a GstRTSPAuth |
basic | the basic token. | [transfer none]

### gst_rtsp_auth_add_digest ()

    void
    gst_rtsp_auth_add_digest (GstRTSPAuth *auth,
                              const gchar *user,
                              const gchar *pass,
                              GstRTSPToken *token);

Add a digest `user` and `pass` for the default authentication algorithm that enables the client with privileges listed in `token` .

#### Parameters

auth | a GstRTSPAuth |
user | the digest user name |
pass | the digest password |
token | authorisation token. | [transfer none]

Since: 1.12

### gst_rtsp_auth_remove_digest ()

    void
    gst_rtsp_auth_remove_digest (GstRTSPAuth *auth,
                                 const gchar *user);

Removes a digest user.

#### Parameters

auth | a GstRTSPAuth |
user | the digest user name. | [transfer none]

Since: 1.12

### gst_rtsp_auth_parse_htdigest ()

    gboolean
    gst_rtsp_auth_parse_htdigest (GstRTSPAuth *auth,
                                  const gchar *path,
                                  GstRTSPToken *token);

Parse the contents of the file at `path` and enable the privileges listed in `token` for the users it describes.

The format of the file is expected to match the format described by https://en.wikipedia.org/wiki/Digest_access_authentication#The_.htdigest_file, as output by the `htdigest` command.

#### Parameters

path | Path to the htdigest file. | [type filename]
token | authorisation token. | [transfer none]

#### Returns

`TRUE` if the file was successfully parsed, `FALSE` otherwise.

Since: 1.16

### gst_rtsp_auth_check ()

    gboolean
    gst_rtsp_auth_check (const gchar *check);

Check if `check` is allowed in the current context.

#### Parameters

check | the item to check |

#### Returns

FALSE if check failed.

### gst_rtsp_auth_get_default_token ()

    GstRTSPToken *
    gst_rtsp_auth_get_default_token (GstRTSPAuth *auth);

Get the default token for `auth` . This token will be used for unauthenticated users.

#### Parameters

auth | a GstRTSPAuth |

#### Returns

the GstRTSPToken of `auth` . `gst_rtsp_token_unref()` after usage.

[transfer full][nullable]

### gst_rtsp_auth_set_default_token ()

    void
    gst_rtsp_auth_set_default_token (GstRTSPAuth *auth,
                                     GstRTSPToken *token);

Set the default GstRTSPToken to `token` in `auth` . The default token will be used for unauthenticated users.

#### Parameters

auth | a GstRTSPAuth |
token | a GstRTSPToken. | [transfer none][allow-none]

### gst_rtsp_auth_get_supported_methods ()

    GstRTSPAuthMethod
    gst_rtsp_auth_get_supported_methods (GstRTSPAuth *auth);

Gets the supported authentication methods of `auth` .

#### Parameters

auth | a GstRTSPAuth |

#### Returns

The supported authentication methods

Since: 1.12

### gst_rtsp_auth_set_supported_methods ()

    void
    gst_rtsp_auth_set_supported_methods (GstRTSPAuth *auth,
                                         GstRTSPAuthMethod methods);

Sets the supported authentication `methods` for `auth` .

#### Parameters

auth | a GstRTSPAuth |
methods | supported methods |

Since: 1.12

## Types and Values

### struct GstRTSPAuth

    struct GstRTSPAuth;

The authentication structure.

### struct GstRTSPAuthClass

    struct GstRTSPAuthClass {
      GObjectClass  parent_class;

      gboolean           (*authenticate) (GstRTSPAuth *auth, GstRTSPContext *ctx);
      gboolean           (*check)        (GstRTSPAuth *auth, GstRTSPContext *ctx,
                                          const gchar *check);
      void               (*generate_authenticate_header) (GstRTSPAuth *auth, GstRTSPContext *ctx);
      gboolean           (*accept_certificate) (GstRTSPAuth *auth,
                                                GTlsConnection *connection,
                                                GTlsCertificate *peer_cert,
                                                GTlsCertificateFlags errors);
    };

The authentication class.

#### Members

`authenticate` () | check the authentication of a client. The default implementation checks if the authentication in the header matches one of the basic authentication tokens. This function should set the authgroup field in the context. |
`check` () | check if a resource can be accessed. this function should call authenticate to authenticate the client when needed. The method should also construct and send an appropriate response message on error. |
`generate_authenticate_header` () |  |
`accept_certificate` () |  |

### GST_RTSP_AUTH_CHECK_CONNECT

    #define GST_RTSP_AUTH_CHECK_CONNECT                  "auth.check.connect"

Check a new connection

### GST_RTSP_AUTH_CHECK_URL

    #define GST_RTSP_AUTH_CHECK_URL                      "auth.check.url"

Check the URL and methods

### GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_ACCESS

    #define GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_ACCESS     "auth.check.media.factory.access"

Check if access is allowed to a factory. When access is not allowed an 404 Not Found is sent in the response.

### GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT

    #define GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT  "auth.check.media.factory.construct"

Check if media can be constructed from a media factory A response should be sent on error.

### GST_RTSP_AUTH_CHECK_TRANSPORT_CLIENT_SETTINGS

    #define GST_RTSP_AUTH_CHECK_TRANSPORT_CLIENT_SETTINGS  "auth.check.transport.client-settings"

Check if the client can specify TTL, destination and port pair in multicast. No response is sent when the check returns `FALSE`.

### GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE

    #define GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE      "media.factory.role"

G_TYPE_STRING, the role to use when dealing with media factories

The default GstRTSPAuth object uses this string in the token to find the role of the media factory. It will then retrieve the GstRTSPPermissions of the media factory and retrieve the role with the same name.

### GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS

    #define GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS   "transport.client-settings"

G_TYPE_BOOLEAN, `TRUE` if the client can specify TTL, destination and port pair in multicast.

### GST_RTSP_PERM_MEDIA_FACTORY_ACCESS

    #define GST_RTSP_PERM_MEDIA_FACTORY_ACCESS      "media.factory.access"

G_TYPE_BOOLEAN, `TRUE` if the media can be accessed, `FALSE` will return a 404 Not Found error when trying to access the media.

### GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT

    #define GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT   "media.factory.construct"

G_TYPE_BOOLEAN, `TRUE` if the media can be constructed, `FALSE` will return a 404 Not Found error when trying to access the media.

## Signal Details

### The `“accept-certificate”` signal

    gboolean
    user_function (GstRTSPAuth         *auth,
                   GTlsConnection      *connection,
                   GTlsCertificate     *peer_cert,
                   GTlsCertificateFlags errors,
                   gpointer             user_data)

Emitted during the TLS handshake after the client certificate has been received. See also `gst_rtsp_auth_set_tls_authentication_mode()`.

#### Parameters

auth | a GstRTSPAuth |
connection | a GTlsConnection |
peer_cert | the peer's GTlsCertificate |
errors | the problems with `peer_cert` . |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` to accept `peer_cert` (which will also immediately end the signal emission). `FALSE` to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it.

Flags: Run Last

Since: 1.6

## See Also

GstRTSPPermissions, GstRTSPToken