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
typedef enum
{
LMRTSPAuthenticationType_Basic = 1,
LMRTSPAuthenticationType_Digest = 2,
} LMRTSPAuthenticationType;
Lists the possible authentication types specified by the AuthenticationRequired property.
Type |
Name |
Description |
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. |
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. |
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.
S_OK if successful, < 0 if 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. |
index |
0-based index of the user you want to remove. |
This method will remove a user from the list.
Obtain the index using the value returned by AddUser method or by using FindUser method.
S_OK if successful, < 0 if an error occurred.
DISP_E_BADINDEX |
[0x8002000B] Bad index (it should be between 0 and UserCount - 1). |
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. |
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.
S_OK if successful, < 0 if 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). |
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. |
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.
S_OK if successful, < 0 if 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). |
Index |
0-based index of the user whose password you want to set. |
newVal |
String containing the password.. |
This method will set the password for an authorized user.
S_OK if successful, < 0 if an error occurred.
E_OUTOFMEMORY |
Out of memory |
DISP_E_BADINDEX |
[0x8002000B] Bad index (it should be between 0 and UserCount - 1). |
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. |
This method will search for a user in the list of authorized users.
S_OK if successful, < 0 if 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 |
This method will remove all users.
S_OK (function never fails)
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. |
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.
S_OK if successful, < 0 if an error occurred.
E_OUTOFMEMORY |
Out of memory |
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. |
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.
S_OK if successful, < 0 if an error occurred.
E_POINTER |
nonce or pVal are NULL. |