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 a 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.

Interface 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.

Interface Methods:

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

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.

Description

This method adds a user to the list of authorized users maintained by this interface. Note that 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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

Parameters

index

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

Description

This method will remove a user from the list.

Obtain the index using the value returned by AddUser method or by using FindUser method.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

DISP_E_BADINDEX

[0x8002000B] Bad index (it should be between 0 and UserCount - 1).

HRESULT  GetUsername(long Index, BSTR* pVal)

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.

Description

This method will get the name of an authorized user.

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

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

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.

Description

This method will get the password of an authorized user.

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

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

Parameters

Index

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

newVal

String containing the password..

Description

This method will set the password for an authorized user.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

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.

Description

This method will search for a user in the list of authorized users.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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

This method will remove all users.

Returns

S_OK (function never fails)

 

 

HRESULT  GenerateNonce(BSTR Key, BSTR* pVal)

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.

Description

This method will generate the Nonce string used by the Digest authentication and add it to the list of valid Nonce keys.

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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_OUTOFMEMORY

Out of memory

 

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

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.

Description

This method will check whether the Nonce string reported by the RTSP client is valid.

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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_POINTER

nonce or pVal are NULL.

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS Filters C API Help