ILMRTSPSecurity Interface

Show in webframe

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:

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

Get a ILMRTSPSecurity interface from the LEAD RTSP Sink filter (or you can also implement your own class)
Specify the desired authentication method by setting the AuthenticationRequired property.
Specify the name of your realm by setting the RealmName property.
Add the authorized users with the AddUser method
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.