Share via

Setting Security Levels on the Session Object

  • Article

The RTC Client API version 1.2 allows encryption levels to be set on the client object and the Session object separately. The encryption levels set on the client object are used for all sessions created after the levels are set. The encryption levels set on the session object are used to set the encryption on a per-session basis. The RTC Client 1.2 application can specify encryption levels for any of the security types specified in the RTC_SECURITY_TYPE enumeration.

The IRTCSession2:put_PreferredSecurityLevel method gives the application the flexibility to determine what security levels should be applied on a per-session basis. The security levels set by this method affect only the session that the method is called on. For example, the application may want to look at the URI of an incoming session by calling IRTCSessionStateChangeEvent2::get_RemotePreferredSecurityLevel, to determine the required security level for the session. Then, if the application determines that the incoming session requires audio/video encryption and the encryption level is currently set to RTCSECL_SUPPORTED for both the remote and the local clients, it calls the put_PreferredSecurityLevel method and specifies RTCSECT_AUDIO_VIDEO_MEDIA_ENCRYPTION and RTCSECL_REQUIRED for the enSecurityType and enSecurityLevel parameters before accepting the incoming session.

The IRTCSession2:put_PreferredSecurityLevel method can be called for sessions that are in the RTCSS_IDLE, RTCSS_INCOMING, or RTCSS_CONNECTED state as follows:

  • If the session is in the RTCSS_IDLE state, the application can set the security level for this session before adding a participant with the IRTCSession::AddParticipant method.
  • If the session is in the RTCSS_INCOMING state, the application can call IRTCSession2::put_PreferredSecurityLevel before accepting the incoming session.
  • If the session is in the IRTCSS_CONNECTED state, a call to IRTCSession2::put_PreferredSecurityLevel will not affect a security type already in use. However, the new security settings will apply to security types that are added to the session (by calling IRTCSession::AddStream, for example) after the call to IRTCSession2::put_PreferredSecurityLevel. If IRTCSession2::put_PreferredSecurityLevel is called with security levels that are already active in a session, the call will fail. For example, if a session is in the RTCSS_CONNECTED state with active audio and video streams and the application calls the IRTCSession2::put_PreferredSecurityLevel method specifying the RTCSECT_AUDIO_VIDEO_MEDIA_ENCRYPTION security type, the call to IRTCSession2::put_PreferredSecurityLevel will fail.
  • If the application wants to change security levels for a security type that is currently active in the session, the application must perform the following steps:
    1. Stop the media stream.
    2. Call the IRTCSession2::put_PreferredSecurityLevel method with the required security type and security level.
    3. Restart the media stream.

For a session to be successfully established or for a new security type to be successfully added in a connected session, the security levels of the local participant must be compatible with the security levels of the remote participant. For example, if the local party sends to the remote party a session INVITE that requires audio/video encryption and the remote party does not support audio/video encryption, a session cannot be established.

When a Reinvite fails to add a new stream to an existing session because of incompatible security levels, the session will continue with the same setting as before. For example, if an existing session with audio/video streams failed to add a T120 stream to the session due to incompatible security levels, the session will continue with the active audio/video streams.

If the application calls the IRTCSession2:put_PreferredSecurityLevel method to lower the security setting to RTCSECL_UNSUPPORTED for an incoming request that has RTCSECL_REQUIRED specified, the call will fail.