ILMRTSPSecurity Interface

This interface is used for implementing security in the RTSP server. RTSP Servers use similar security to HTML servers and is based on authentication. The authentication methods rely on the servers specifying a user name and a password pair with the right to access a certain Media file.

There are two authentication methods:

  1. Basic - in the Basic authentication method, the RTSP client sends the server an encrypted version of the user name and password. If these match, the server grants access, otherwise it denies access

  2. Digest - in the Digest authentication method, the RTSP client generates an encrypted string from the user name and password and sends it to the server. The server generates the same string from the user name and password that it has and grants access if the string sent by the client matches the string generated by the server. This is a more secure method, since the user name and password are never sent to the server.

From a performance standpoint, the two authentication methods have roughly the same speed. So the choice of method depends on the security level desired for the server and in what kind of authentication is supported in the clients.

The LEAD RTSP Source filter support both authentication methods.

The authentication is optional, if nothing is done, the server will not restrict any access.

To implement security, create an ILMRTSPSecurity interface and set it to the ILMRTSPServerSession interface using the ILMRTSPServerSession::Security property. The ILMRTSPServerSession::Security property keeps a pointer to the actual interface, so if users are added or removed to the ILMRTSPSecurity interface after it is set the ILMRTSPServerSession::Security property, these changes will be reflected in the security settings for that ILMRTSPServerSession instance.

To implement different security settings for each file, create different ILMRTSPSecurity interface for each session.

To use the same security settings for all the files, create one ILMRTSPSecurity interface and use it for all sessions that are created.

Use this same ILMRTSPSecurity interface with the high level LEADTOOLS Multimedia modules.

In general, do the following:

  1. Get an ILMRTSPSecurity interface from the LEAD RTSP Sink filter (or you can also implement your own class)

  2. Specify the desired authentication method by setting the AuthenticationRequired property.

  3. Specify the name of your realm by setting the RealmName property.

  4. Add the authorized users with the AddUser method

  5. Set the ILMRTSPSecurity interface to the session (using ILMRTSPServerSession::Security property) or to the high level Multimedia modules

Data Types

LMRTSPAuthenticationType

typedef enum 
{ 
   LMRTSPAuthenticationType_Basic = 1, 
   LMRTSPAuthenticationType_Digest = 2, 
} LMRTSPAuthenticationType; 

Lists the possible authentication types specified by the AuthenticationRequired property.

Properties

Type Name Description
LMRTSPAuthenticationType AuthenticationRequired This property indicates the authentication method (Basic or Digest). See the top of this page for a discussion on the differences between the two methods.
BSTR RealmName A string specifying the realm name. You can set this string to whatever you choose. It is a form of identifying your server to the RTSP client.
long UserCount A read-only property indicating how many users have been added using the AddUser method.

Methods

HRESULT AddUser(BSTR Username, BSTR Password, long* pVal)

Description

Adds a user to the list of authorized users maintained by this interface.

Parameters

Username

String indicating the user name. Cannot be NULL.

Password

String indicating the password. Can be NULL if no password is desired. In this case, all they to enter is the username.

pVal

Optional parameter that will return the 0-based index of this user in the list of users maintained by the interface. You can pass NULL if you are not interested in this information.

Comments

All users have the same privileges, so when a user is added to this interface the user is granted access to all the media that will use this interface.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY Out of memory.
E_POINTER Username is NULL.
LTMM_E_USER_EXISTS [0x80050049] Username exists already and has a different password.

HRESULT RemoveUser(long index)

Description

Removes a user from the list.

Parameters

index

0-based index of the user you want to remove.

Comments

To obtain the index, use the value returned by AddUser or FindUser method.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
DISP_E_BADINDEX [0x8002000B] Bad index (it should be between 0 and UserCount - 1).

HRESULT GetUsername(long Index, BSTR* pVal)

Description

Gets the name of an authorized user.

Parameters

Index

0-based index of the user whose name you want to retrieve.

pVal

Pointer to a variable that will be filled with the user name.

Comments

The string returned has been allocated with the Win32 API SysAllocString, so you must free it using SysFreeString.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY Out of memory.
E_POINTER pVal is NULL.
DISP_E_BADINDEX [0x8002000B] Bad index (it should be between 0 and UserCount - 1).

HRESULT GetPassword(long Index, BSTR* pVal)

Description

Gets the password of an authorized user.

Parameters

Index

0-based index of the user whose password you want to retrieve.

pVal

Pointer to a variable that will be filled with the password.

Comments

The string returned has been allocated with the Win32 API SysAllocString, so you must free it using SysFreeString.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY Out of memory.
E_POINTER pVal is NULL.
DISP_E_BADINDEX [0x8002000B] Bad index (it should be between 0 and UserCount - 1).

HRESULT SetPassword(long Index, BSTR newVal)

Description

Sets the password for an authorized user.

Parameters

Index

0-based index of the user whose password you want to set.

newVal

String containing the password.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY Out of memory.
DISP_E_BADINDEX [0x8002000B] Bad index (it should be between 0 and UserCount - 1).

HRESULT FindUser(BSTR Username, long* pVal)

Description

Searches for a user in the list of authorized users.

Parameters

Username

String containing the name of the user you wish to find.

pVal

Pointer to a variable that will be updated with the 0-based user index.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
LTMM_E_ITEM_NOT_FOUND [0x80050040] The user is not in the list
E_POINTER Username is NULL.
E_OUTOFMEMORY Out of memory.

HRESULT RemoveAllUsers()

Description

Removes all users.

Returns

S_OK (function never fails).

HRESULT GenerateNonce(BSTR key, BSTR* pVal)

Description

Generates the Nonce string used by the Digest authentication and add it to the list of valid Nonce keys.

Parameters

key

String containing the key you wish to use to generate the Nonce string used by Digest authentication.

pVal

Pointer to a variable that will be updated with the generated string.

Comments

This is an internal method used by the LEAD RTSP Sink filter for authentication when the Digest authentication method is used. You don't ever need to call it.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY Out of memory.

HRESULT IsNonceValid(BSTR nonce, BSTR key, VARIANT_BOOL *pVal)

Description

Checks whether the Nonce string reported by the RTSP client is valid.

Parameters

nonce

String containing the nonce key that should be verified.

Key

String containing the key that was used to generate the Nonce string.

pVal

Pointer to a variable that will be updated to indicate whether the Nonce is valid or not.

Comments

This is an internal method used by the LEAD RTSP Sink filter when the Digest authentication is used. You don't ever need to call it.

pVal will be set to VARIANT_TRUE (-1) if the key is valid, or VARIANT_FALSE (0) if the key is invalid.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_POINTER nonce or pVal are NULL.
Help Version 22.0.2022.4.7
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2022 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Filters C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2022 LEAD Technologies, Inc. All Rights Reserved.