5.5 RTCDtlsTransport Interface

The RTCDtlsTransport interface allows an application access to information about the Datagram Transport Layer Security (DTLS) transport over which RTP and RTCP packets are sent and received by RTCRtpSender and RTCRtpReceiver objects, as well other data such as SCTP packets sent and received by data channels. In particular, DTLS adds security to an underlying transport, and the RTCDtlsTransport interface allows access to information about the underlying transport and the security added. RTCDtlsTransport objects are constructed as a result of calls to setLocalDescription() and setRemoteDescription(). Each RTCDtlsTransport object represents the DTLS transport layer for the RTP or RTCP component of a specific RTCRtpTransceiver, or a group of RTCRtpTransceivers if such a group has been negotiated via [RFC8843].

Note

A new DTLS association for an existing RTCRtpTransceiver will be represented by an existing RTCDtlsTransport object, whose state will be updated accordingly, as opposed to being represented by a new object.

An RTCDtlsTransport has a [[DtlsTransportState]] internal slot initialized to “new“ and a [[RemoteCertificates]] slot initialized to an empty list.

When the underlying DTLS transport experiences an error, such as a certificate validation failure, or a fatal alert (see [RFC5246] section 7.2), the user agent MUST queue a task that runs the following steps:

1. Let transport be the RTCDtlsTransport object to receive the state update and error notification.

2. If the state of transport is already “failed“, abort these steps.

3. Set transport.[[DtlsTransportState]] to “failed“.

4. Fire an event named [`error`](#dfn-rtcdtlstransport-error) using the RTCErrorEvent interface with its errorDetail attribute set to either “dtls-failure“ or “fingerprint-failure“, as appropriate, and other fields set as described under the RTCErrorDetailType enum description, at transport.

5. Fire an event named [`statechange`](#event-dtlstransport-statechange) at transport.

When the underlying DTLS transport needs to update the state of the corresponding RTCDtlsTransport object for any other reason, the user agent MUST queue a task that runs the following steps:

1. Let transport be the RTCDtlsTransport object to receive the state update.

2. Let newState be the new state.

3. Set transport.[[DtlsTransportState]] to newState.

4. If newState is connected then let newRemoteCertificates be the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [X690], and set transport.[[RemoteCertificates]] to newRemoteCertificates.

5. Fire an event named [`statechange`](#event-dtlstransport-statechange) at transport.

WebIDL[Exposed=Window]
interface RTCDtlsTransport : EventTarget {
  [SameObject] readonly attribute RTCIceTransport iceTransport;
  readonly attribute RTCDtlsTransportState state;
  sequence<ArrayBuffer> getRemoteCertificates();
  attribute EventHandler onstatechange;
  attribute EventHandler onerror;
};

Attributes

iceTransport of type RTCIceTransport, readonly

The iceTransport attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active RTCDtlsTransport objects.

state of type RTCDtlsTransportState, readonly

The state attribute MUST, on getting, return the value of the [[DtlsTransportState]] slot.

onstatechange of type EventHandler

The event type of this event handler is [`statechange`](#event-dtlstransport-statechange).

onerror of type EventHandler

The event type of this event handler is error.

Methods

getRemoteCertificates

Returns the value of [[RemoteCertificates]].