| RFC 9248 | Relay User Equipment Profile | June 2022 |
| Rosen | Standards Track | [Page] |
Video Relay Service (VRS) is a term used to describe a method by which a hearing person can communicate with a sign language speaker who is deaf, deafblind, or hard of hearing (HoH) or has a speech disability using an interpreter (i.e., a Communications Assistant (CA)) connected via a videophone to the sign language speaker and an audio telephone call to the hearing user. The CA interprets using sign language on the videophone link and voice on the telephone link. Often the interpreters may be employed by a company or agency, termed a "provider" in this document. The provider also provides a video service that allows users to connect video devices to their service and subsequently to CAs and other sign language speakers. It is desirable that the videophones used by the sign language speaker conform to a standard so that any device may be used with any provider and that direct video calls between sign language speakers work. This document describes the interface between a videophone and a provider.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9248.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Video Relay Service (VRS) is a form of Telecommunications Relay Service (TRS) that enables people with hearing disabilities who use sign language, such as American Sign Language (ASL), to communicate with voice telephone users through video equipment. These services also enable communication between such individuals directly in suitable modalities, including any combination of sign language via video, real-time text, and speech.¶
This interoperability profile for Relay User Equipment (RUE) is a profile of the Session Initiation Protocol (SIP) and related media protocols that enables end-user equipment registration and calling for VRS calls. It specifies the minimal set of call flows and IETF and ITU-T standards that must be supported, provides guidance where the standards leave multiple implementation options, and specifies minimal and extended capabilities for RUE calls.¶
Both subscriber-to-provider (interpreted) and direct subscriber-to-subscriber calls are supported on this interface.While there are some accommodations in this document to maximize backwards compatibility with other devices and services that are used to provide VRS service, backwards compatibility is not a requirement, and some interwork may be required to allow direct video calls to older devices. This document only describes the interface between the device and the provider, not any other interface the provider may have.¶
The following illustrates a typical relay call. The RUE device and the communications assistant (sign language interpreter) have videophones. The hearing user has a telephone (mobile or fixed).¶
||== RUE Interface (this document) || \/ +------+ +------+ - +--------+ - +-------+ |User | |RUE | ( ) |Provider| ( ) |User | |who is| |Device|<-(Internet)->| | |who is | |Deaf |<->| | | |<-( PSTN )->|Hearing| +------+ +------+ -------- +--------+ ------ +-------+ ^ | +--------------+ |Communications| |Assistant | +--------------+¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14[RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here. Lower- or mixed-case uses of these key words are not to be interpreted as carrying special significance.¶
All HTTP/HTTPS[RFC9110][RFC9112] connections specified throughout this documentMUST use HTTPS. Both HTTPS and all SIP connectionsMUST use TLS conforming to at least[RFC7525] andMUST support[RFC8446].¶
All text data payloads not otherwise constrained by a specification in another standards documentMUST be encoded as Unicode UTF-8.¶
ImplementationsMUST support IPv4 and IPv6. Dual-stack support is NOT required, and provider implementationsMAY support separate interfaces for IPv4 and IPv6 by having more than one server in the appropriate SRV record where there is either an A or AAAA record in each server DNS record but not both. The same version of IPMUST be used for both signaling and media of a call unless Interactive Connectivity Establishment (ICE)[RFC8445] is used; in which case, candidates may explicitly offer IPv4, IPv6, or both for any media stream.¶
Implementations of the RUE interfaceMUST conform to the following core SIP standards:¶
In the above documents, the RUE device conforms to the requirements of a SIP user agent, and the provider conforms to the requirements of the registrar and proxy server where the document specifies different behavior for different roles. For providers offering a video mail service,[RFC6665] (SIP Events)MUST be implemented to support the Message-Waiting Indicator (MWI) (seeSection 8).¶
In addition, implementationsMUST conform to:¶
ImplementationsMUST implement full ICE, although theyMAY interwork with user agents that implement ICE-lite.¶
ImplementationsMUST include a "User-Agent" header field uniquely identifying the RUE application, platform, and version in all SIP requests andMUST include a "Server" header field with the same content in SIP responses.¶
Implementations intended to support mobile platformsMUST support[RFC8599] andMUST use it as at least one way to support waking up the client from the background state.¶
The SIP signaling for registration and placing/receiving calls depends on the configuration of various values into the RUE device.Section 9.2 describes the configuration mechanism that provides values that are used in the signaling. When the device starts, the configuration mechanism is run, which retrieves the configuration data; then, SIP registration occurs using the values from the configuration. After registration, calls may be sent or received by the RUE device.¶
The RUEMUST register with a SIP registrar, following[RFC3261] and[RFC5626], at a provider it has an account with. If the configuration (seeSection 9.2) contains multiple "outbound-proxies" in "RueConfigurationData", then the RUEMUST use them as specified in[RFC5626] to establish multiple flows.¶
The Request-URI for the REGISTER requestMUST contain the "provider-domain" from the configuration. The To URI and From URIMUST be identical URIs and formatted as follows:¶
The RUE determines the URI to resolve by initially determining if one or more "outbound-proxies" are configured. If they are configured, the URI will be that of one of the "outbound-proxies". If no "outbound-proxies" are configured, the URI will be the Request-URI from the REGISTER request. The RUE extracts the domain from that URI and consults the DNS record for that domain. The DNS entryMUST contain NAPTR records conforming to[RFC3263]. One of those NAPTR recordsMUST specify TLS as the preferred transport for SIP. For example, a DNS NAPTR query for "sip: p1.red.example.net" could return:¶
IN NAPTR 50 50 "s" "SIPS+D2T" "" _sips._tcp.p1.red.example.netIN NAPTR 90 50 "s" "SIP+D2T" "" _sip._tcp.p1.red.example.net¶
If the RUE receives a 439 (First Hop Lacks Outbound Support) response to a REGISTER request, itMUST reattempt registration without using the outbound mechanism.¶
The registrarMAY authenticate the RUE using SIP digest authentication. The credentials to be usedMUST come from the configuration inSection 9.2: "user-name" if provided or "phone-number" if user-name is not provided, and "sip-password". This "user-name"/"sip-password" combinationSHOULD NOT be the same as that used for other purposes, except as expressly described below, such as retrieving the RUE configuration or logging into the provider's customer service portal.[RFC8760]MUST be supported by all implementations, and SHA-512 digest algorithmsMUST be supported.¶
If the registration request fails with an indication that credentials from the configuration are invalid, then the RUEMUST retrieve a fresh version of the configuration. If credentials from a freshly retrieved configuration are found to be invalid, then the RUEMUST cease attempts to register and inform the RUE user of the problem.¶
Support for multiple simultaneous registrations with multiple providers by the RUE isOPTIONAL for the RUE (and providers do not need any support for this option).¶
Multiple simultaneous RUE SIP registrations from different RUE devices with the same SIP URISHOULD be permitted by the provider. The providerMAY limit the total number of simultaneous registrations. When a new registration request is received that results in exceeding the limit on simultaneous registrations, the providerMAY then prematurely terminate another registration; however, itSHOULD NOT do this if it would disconnect an active call.¶
If a provider prematurely terminates a registration to reduce the total number of concurrent registrations with the same URI, itSHOULD take some action to prevent the affected RUE from automatically re-registering and re-triggering the condition.¶
After initial SIP registration, the RUE adheres to SIP[RFC3261] basic call flows, as documented in[RFC3665].¶
A RUE deviceMUST route all outbound calls through an outbound proxy if configured.¶
The SIP URIs in the To field and the Request-URIMUST be formatted as specified inSection 5.4 using the destination phone number or as SIP URIs as provided in the configuration (Section 9.2). The domain field of the URIsSHOULD be the "provider-domain" from the configuration (e.g., sip:+15551234567@red.example.com;user=phone), except that an anonymous call would not use the provider domain.¶
Anonymous callsMUST be supported by all implementations. An anonymous call is signaled per[RFC3323].¶
The From URIMUST be formatted as specified inSection 5.4, using the "phone-number" and "provider-domain" from the configuration. ItSHOULD also contain the display-name from the configuration when present. (Please refer toSection 9.2.)¶
Negotiated mediaMUST follow the requirements specified inSection 6 of this document.¶
To allow time for an unanswered call to time out and direct it to a videomail server, the User Agent ClientMUST NOT impose a time limit less than the default SIP INVITE transaction timeout of 3 minutes.¶
Providers and RUE devicesMUST support both one-stage and two-stage dial-around.¶
Outbound dial-around calls allow a RUE user to select any provider to provide interpreting services for any call. "Two-stage" dial-around calls involve the RUE calling a telephone number that reaches the dial-around provider and using signing or dual-tone multi-frequency (DTMF) to provide the called party's telephone number. In two-stage dial-around, the To URI is the "front-door" URI (seeSection 9.2) in "ProviderConfigurationData" of the dial-around provider. The RUE Provider Selection service (Section 9.1) can be used by the RUE to obtain a list of providers; then, the provider configuration (Section 9.2.1) can be used to find the front-door URI for each of these providers.¶
One-stage dial-around is a method where the called party's telephone number is provided in the To URI and the Request-URI, using the domain of the dial-around provider.¶
For one-stage dial-around, the RUEMUST follow the procedures inSection 5.2.1 with the following exception: the domain part of the SIP URIs in the To field and the Request-URIMUST be the domain of the dial-around provider discovered as described inSection 9.1.¶
The following is a partial example of a one-stage dial-around call from VRS user +1-555-222-0001 hosted by red.example.com to a hearing user +1-555-123-4567 using dial-around to green.example.com for the relay service. Only important details of the messages are shown, and many header fields have been omitted:¶
,-+-. ,----+----. ,-----+-----. |RUE| |Default | |Dial-Around| | | |Provider | | Provider | `-+-' `----+----' `-----+-----' | | | | [1] INVITE | | |-------------->| [2] INVITE | | |-------------->| Message Details: [1] INVITE Rue -> Default Provider INVITE sip:+15551234567@green.example.net;user=phone SIP/2.0 To: <sip:+15551234567@green.example.net;user=phone> From: "Bob Smith" <sip:+15552220001@red.example.net;user=phone> [2] INVITE Default Provider -> Dial-Around Provider INVITE sip:+15551234567@green.example.net;user=phone SIP/2.0 To: <sip:+15551234567@green.example.net;user=phone> From: "Bob Smith" sip:+15552220001@red.example.net;user=phone P-Asserted-Identity: sip:+15552220001@red.example.net
To identify the owner of a RUE, the initial INVITE for a call from a RUE, or the 200 OK the RUE uses to accept a call, identifies the owner by sending a Call-Info header field with a purpose parameter of "rue-owner". The URIMAY be an HTTPS URI or Content-ID URL. The latter is defined by[RFC2392] to locate message body parts. This URI type is present in a SIP message to convey the RUE ownership information as a MIME body. The form of the RUE ownership information is an xCard[RFC6351]. Please refer to[RFC6442] for an example of using content indirection URLs in SIP messages. Note that use of the content indirection URL usually implies multiple message bodies ("mime/multipart"). The RUE owner is the entity that has local control over the device that is not necessarily the legal owner of the equipment. It often is the user, but that is not necessarily true. While no minimum fields in the xCard are specified, the name, address, phone number, and email address of the RUE owner are expected to be supplied.¶
The RUEMUST only accept inbound calls sent to it by a proxy mentioned in the configuration.¶
If multiple simultaneous RUE SIP registrations from different RUE devices with the same SIP URI exist, the providerMUST parallel fork the call to all registered RUEs so that they ring at the same time. The first RUE to reply with a 200 OK answers the call, and the providerMUST cancel other call branches using a CANCEL request.¶
ImplementationsMUST conform to[RFC6881] for handling of emergency calls, except that if the device is unable to determine its own location, itMAY send the emergency call without a Geolocation header field and without a Route header field (since it would be unable to query the Location-to-Service Translation (LoST) server for a route, per[RFC6881]). If an emergency call arrives at the provider without a Geolocation header field, the providerMUST supply location by adding the Geolocation header field andMUST supply the route by querying the LoST server with that location.¶
If the emergency call is to be handled using existing country-specific procedures, the provider is responsible for modifying the INVITE to conform to the country-specific requirements. In this case, the locationMAY be extracted from the[RFC6881] conformant INVITE and used to propagate it to the appropriate country-specific entities. If the configuration specifies it, an implementation of a RUE deviceMAY send a Geolocation header field containing its location in the REGISTER request. If implemented, usersMUST be offered an opt-out. Country-specific procedures might require the location to be preloaded in some entity prior to placing an emergency call; however, the RUE may have a more accurate and timely device location than the manual, preloaded entry. That informationMAY be used to populate the location to appropriate country-specific entities. Re-registrationSHOULD be used to update the location, so long as the rate of re-registration is limited if the device is moving.¶
ImplementationsMUST implement additional data[RFC7852]. RUE devicesMUST implement data provider information, device information, and owner/subscriber information blocks.¶
ImplementationsMUST support re-INVITE to renegotiate media session parameters (among other uses). PerSection 6.8, implementationsMUST be able to support an INFO message for full frame refresh for devices that do not support SRTCP (please refer toSection 6.1). ImplementationsMUST support an in-dialog REFER (as described in[RFC3515] and updated by[RFC7647], and including support for norefersub per[RFC4488]) with the Replaces header field[RFC3891] to enable call transfer.¶
SIP URIs constructed from non-URI sources (dial strings) and sent to SIP proxies by the RUEMUST be represented as follows, depending on whether they can be represented as an E.164 number. In this section, "expressed as an E.164 number" includes numbers, such as toll-free numbers that are not actually E.164 numbers but have the same format.¶
A dial string that can be expressed as an E.164 phone numberMUST be represented as a SIP URI with a URI ";user=phone" tag. The user part of the URIMUST be in conformance with "global-number", as defined in[RFC3966]. The user partMUST NOT contain any "visual-separator" characters, as defined in[RFC3966].¶
Dial strings that cannot be expressed as E.164 numbersMUST be represented as dialstring URIs, as specified by[RFC4967], e.g., sip:411@red.example.net;user=dialstring.¶
The domain part of relay service URIs and User Address of Records (AoR)MUST resolve (per[RFC3263]) to globally routable IPv4 and/or IPv6 addresses.¶
ImplementationsMUST conform to[RFC8835], except for its guidance on the WebRTC data channel, which this specification does not use. SeeSection 6.2 for how RUE supports real-time text without the data channel.¶
ImplementationsMUST support SIP outbound[RFC5626] (please also refer toSection 5.1).¶
This specification adopts the media specifications for WebRTC[RFC8825]. Where WebRTC defines how interactive media communications may be established using a browser as a client, this specification assumes a normal SIP call. Various RTPs, RTCPs, SDPs, and specific media requirements specified for WebRTC are adopted for this document. Explicit requirements from the WebRTC suite of documents are described below .¶
To use WebRTC with this document, a gateway that presents a WebRTC server interface towards a browser and a RUE client interface towards a provider is assumed. The gateway would interwork signaling and, as noted below, interwork at least any real-time text media in order to allow a standard browser-based WebRTC client to be a VRS client. The combination of the browser client and the gateway would be a RUE user. This document does not specify the gateway.¶
The following sections specify the WebRTC documents to which conformance is required. "Mandatory to Implement" means a conforming implementationMUST implement the specified capability. It does not mean that the capability must be used in every session. For example, Opus is a Mandatory-to-Implement audio codec, and all conforming implementations must support Opus. However, an implementation presenting a call across the RUE interface (where the call originates in the PSTN or an older, non-RUE-compatible device, which only offers G.711 audio) does not need to include the Opus codec in the offer, since it cannot be used with that call. Conformance to this document allows end-to-end RTCP and media congestion control for audio and video.¶
ImplementationsMUST support[RFC8834], except that MediaStreamTracks are not used. ImplementationsMUST conform toSection 6.4 of [RFC8827].¶
ImplementationsMUST support real-time text[RFC4102][RFC4103] via T.140 media. One original and two redundant generationsMUST be transmitted and supported with a 300 ms transmission interval. ImplementationsMUST support[RFC9071], especially for emergency calls. Note that[RFC4103] is not how real-time text is transmitted in WebRTC, and some form of transcoder would be required to interwork real-time text in the data channel of WebRTC to[RFC4103] real-time text.¶
Transport of T.140 real-time text in WebRTC is specified in[RFC8865], using the WebRTC data channel.[RFC8865] also has some advice on how gateways between[RFC4103] and[RFC8865] should operate. It isRECOMMENDED that[RFC8865], including multiparty support, be used for communication with browser-based WebRTC implementations. ImplementationsMUST support[RFC9071].¶
ImplementationsMUST conform to[RFC7742] with the following exceptions: only H.264, as specified in[RFC7742], is Mandatory to Implement, and VP8 support isOPTIONAL at both the device and providers. This is because backwards compatibility is desirable, and older devices do not support VP8.¶
ImplementationsMUST support the "audio/telephone-event"[RFC4733] media type. TheyMUST support conveying event codes 0 through 11 (DTMF digits "0"-"9", "*","#") defined in Table 7 of[RFC4733]. Handling of other tones isOPTIONAL.¶
The SDP offers and answersMUST conform to the SDP rules in[RFC8829] except that the RUE interface uses SIP transport for SDP. The SDP for real-time textMUST specify the T.140 payload type[RFC4103].¶
The RUEMUST provide for user privacy by implementing a local one-way mute, without signaling, for both audio and video. However, RUEMUST maintain any states in the network (e.g., NAT bindings) by periodically sending media packets on all active media sessions containing silence, comfort noise, blank screen, etc., per[RFC6263].¶
The NACK, FIR, and Picture Loss Indicator (PLI) features, as described in[RFC4585] and[RFC5104],MUST be implemented. Availability of these featuresMUST be announced with the "ccm" feedback value. NACK should be used when negotiated and conditions warrant its use and the other end supports it. Signaling picture losses as a PLI should be preferred. FIR should be used only in situations where not sending a decoder refresh point would render the video unusable for the users, as perSection 4.3.1.2 of [RFC5104].¶
For backwards compatibility with calling devices that do not support the foregoing methods, implementationsMUST implement SIP INFO messages to send and receive XML-encoded Picture Fast Update messages according to[RFC5168].¶
Support of vCard Extensions to WebDAV (CardDAV) by providers isOPTIONAL.¶
The RUEMUST and providersMAY be able to synchronize the user's contact directory between the RUE endpoint and one maintained by the user's VRS provider using CardDAV[RFC6352][RFC6764].¶
The configuration (seeSection 9.2) RueConfigurationDataMAY supply a "carddav-username" and "carddav-domain" identifying a CardDAV server and address book for this account, plus an optional "carddav-password".¶
To access the CardDAV server and address book, the RUEMUST followSection 6 of [RFC6764], using the configured carddav-username and carddav-domain in place of an email address. If the request triggers a challenge for digest authentication credentials, the RUEMUST continue using matching carddav-username and carddav-password from the configuration. If no carddav-username and carddav-password are configured, the RUEMUST use the SIP user-name and sip-password from the configuration. If the SIP credentials fail, the RUEMUST query the user.¶
Synchronization using CardDAVMUST be a two-way synchronization service, with proper handling of asynchronous adds, changes, and deletes at either end of the transport channel.¶
The RUEMAY support other CardDAV services.¶
ImplementationsMUST be able to export/import the list of contacts in xCard[RFC6351] XML format.¶
The RUE accesses this service via the "contacts-uri" in the configuration. The URLMUST resolve to identify a web server resource that imports/exports contact lists for authorized users.¶
The RUE stores/retrieves the contact list (address book) by issuing an HTTPS POST or GET request. If the request triggers a challenge for digest authentication credentials, the RUEMUST attempt to continue using the "contacts-username" and "contacts-password" from the configuration. If no contacts-username is configured, the SIP user-name from the configuration is used; if the SIP user-name is not configured, the phone-number is used. If user-name or phone-number is used, the sip-password is used to authenticate to the contact list server.¶
Support for video mail includes a retrieval mechanism and a Message-Waiting Indicator (MWI). Message storage is not specified by this document. RUE devicesMUST support message retrieval using a SIP call to a specified SIP URI using DTMF to manage the mailbox, as well as a browser-based interface reached at a specified HTTPS URI. If a provider supports video mail, at least one of these mechanismsMUST be supported. RUE devicesMUST support both. SeeSection 9.2 for how the URI to reach the retrieval interface is obtained.¶
ImplementationsMUST support subscriptions to "message-summary" events[RFC3842] to the URI specified in the configuration. ProvidersMUST support MWI if they support video mail. RUE devicesMUST support MWI.¶
The "videomail" and "mwi" properties in the configuration (see RueConfigurationData inSection 9.2.2) give the URIs for message retrieval and "message-summary" subscription.¶
In notification bodies, if detailed message summaries are available, messages with videoMUST be reported using "message-context-class multimedia-message", as defined in[RFC3458] .¶
To simplify how users interact with RUE devices, the RUE interface separates provisioning into two parts. One provides a directory of providers so that a user interface can allow easy provider selection either for registering or for dial-around. The other provides configuration data for the device for each provider.¶
To allow the user to select a relay service, the RUEMAY at any time obtain (typically on startup) a list of providers that provide service in a country. IANA has established a registry that contains a two-letter country code and a list entry point string (seeSection 10.1). The entry point, when used with the following OpenAPI interface, returns a list of provider names for a country code suitable for display, with a corresponding entry point to obtain information about that provider. No mechanism to determine the country where the RUE is located is specified in this document. Typically, the country is the home country of the user but may be a local country while traveling. Some countries allow support from their home country when traveling abroad. Regardless, the RUE device will need to allow the user to choose the country.¶
Each country that supports VRS using this specificationMAY support the provider list. This document does not specify who maintains the list. Some possibilities are a regulator or an entity designated by a regulator, an agreement among providers to provide the list, or a user group.¶
The interface to obtain the list of providers is described by an OpenAPI[OpenAPI] interface description. In that interface description, the "servers" component includes an occurrence of "localhost". The value from the registry of the "list entry point" string for the desired country is substituted for "localhost" in the "servers" component to obtain the server URI prefix of the interface to be used to obtain the list of providers for that country. The "Providers" path then specifies the rest of the URI used to obtain the list. For example, if the list entryPoint is "example.com/api", the provider list would be obtained from https://example.com/api/rum/v1/Providers.¶
The V1.0 "ProviderList" is a JSON object consisting of an array where each entry describes one provider. Each entry consists of the following items:¶
The VRS user interacts with the RUE to select from the provider list one or more providers with whom the user has already established an account, wishes to establish an account, or wishes to use the provider for a one-stage dial-around.¶
{ "providers": [ { "name": "Red", "entryPoint": "red.example.net" }, { "name": "Green", "entryPoint": "green.example.net" }, { "name": "Blue", "entryPoint": "blue.example.net" } ]}A RUE device may retrieve a provider configuration using a simple HTTPs web service. There are two entry points. One is used without user credentials, and the response includes configuration data for new user signup and dial-around. The other uses a locally stored username and password that results from a new user signup to authenticate to the interface and returns configuration data for the RUE.¶
The interface to obtain configuration data is described by an OpenAPI[OpenAPI] interface description. In that interface description, the "servers" component string includes an occurrence of "localhost". The entry point string obtained from the provider list (Section 9.1) is substituted for "localhost" to obtain the server prefix of the interface. The path then specifies the rest of the URI used to obtain the list. For example, if the entryPoint from the provider list is "red.example.net", the provider configuration would be obtained from https://red.example.net/rum/V1/ProviderConfig and the RUE configuration would be obtained from https://red.example.net/rum/V1/RueConfig.¶
In both the queries, an optional parameter may be provided to the interface, which is an API Key (apiKey). The implementationMAY have an apiKey obtained from the provider and specific to the implementation. The method used to obtain the apiKey is not specified in this document. The providerMAY refuse to provide service to an implementation presenting an apiKey it does not recognize.¶
Also in both queries, the RUE device provides a client-provided, required parameter, which contains an instance identifier (instanceId). This parameterMUST be the same value each time this instance (same implementation on same device) queries the interface. ThisMAY be used by the provider, for example, to associate a location with the instance for emergency calls. This should be globally unique. A Universally Unique Identifier (UUID) is suggested.¶
For example, a query for the RUE configuration could behttps://red.example.net/rum/V1/RueConfig?apiKey="t65667Ajjss90uuuDisKt8999"&instanceId="5595b5a3-0687-4b8e-9913-a7f2a04fb7bd"¶
The data returned is a JSON object consisting of key/value configuration parameters to be used by the RUE.¶
The configuration data payload includes the following data items. Items not noted as (OPTIONAL) areREQUIRED. If other unexpected items are found, theyMUST be ignored.¶
signup: (OPTIONAL) an array of JSON objects consisting of:¶
dial-around: an array of JSON objects consisting of:¶
helpDesk: (OPTIONAL) an array of JSON objects consisting of:¶
A list is specified so that the provider can offer multiple choices to users for language and interface styles.¶
Both web services also have a simple version mechanism that returns a list of versions of the web service it supports. This document describes version 1.0.Versions are displayed as a major version, followed bya period ".", followed by a minor version, where the major and minorversions are integers. A backwards compatible change within a major versionMAY increment only the minor version number. A non-backwards, compatible changeMUST increment the major version number. Backwards compatibility applies to both the server and the client. Either may have any higher or lower minor revision and interoperate with its counterpart with the same major version. To achieve backwards compatibility, implementationsMUST ignore any object members they do not implement. Minor version definitionsSHALL only add objects, optional members of existing objects, and non-mandatory-to-use functions andSHALL NOT delete or change any objects, members of objects, or functions. This means an implementation of a specific major version and minor version is backwards compatible with all minor versions of the major version. The version mechanism returns an array of supported versions, one for each major version supported, with the minor version listed being the highest-supported minor version.¶
Unless the per-country provider list service is operated by a provider at the same base URI as that provider's configuration service, the version of the configuration serviceMAY be different from the version of the provider list service.¶
{ "versions": [ { "major": 1, "minor": 6 }, { "major": 2, "minor": 13 }, { "major": 3, "minor": 2 } ]}{ "signUp": [ { "language" : "en", "uri" : "https:hello-en.example.net"}, { "language" : "es", "uri" : "https:hello-es.example.net"} ] , "dial-around": [ { "language" : "en", "front-door" : "sip:fd-en.example.net", "oneStage" : "sip:1stg-eng.example.com" } , { "language" : "es", "front-door" : "sip:fd-es.example.net", "oneStage" : "sip:1stg-spn.example.com" } ] , "helpDesk": [ { "language" : "en", "uri" : "sip:help-en.example.net"} , { "language" : "es", "uri" : "sip:help-es.example.net"} ]}{ "lifetime": 86400, "display-name" : "Bob Smith", "phone-number": "+15551234567", "provider-domain": "red.example.net", "outbound-proxies": [ "sip:p1.red.example.net", "sip:p2.red.example.net" ], "mwi": "sip:+15551234567@red.example.net;user=phone", "videomail": "sip:+15551234567@vm.red.example.net;user=phone", "contacts": { "contacts-uri": "https://red.example.net:443/c/3617b719-2c3a-46f4-9c13", "contacts-username": "bob", "contacts-password": "XhOT4ch@ZEi&3u2xEYQNMO^5UGb" }, "carddav": { "carddav-domain": "carddav.example.com", "carddav-username": "bob", "carddav-password": "sj887%dd*jJty%87hyys5hHT" }, "sendLocationWithRegistration": false, "ice-servers": [ {"stun":"stun.red.example.com:19302" }, {"turn":"turn.red.example.com:3478"} ]}One way to use these two services is:¶
For each provider in the list:¶
The interfaces in Sections9.1 and9.2 are formally specified with OpenAPI 3.0[OpenAPI] descriptions in YAML form.¶
The OpenAPI description below is normative. If there is any conflict between the text or examples and this section, the OpenAPI description takes precedence.¶
openapi: 3.0.1info: title: RUM Provider List API version: "1.0"servers: - url: https://localhost/rum/v1paths: /Providers: get: summary: Get a list of providers and domains to get config data from operationId: GetProviderList responses: '200': description: List of providers for a country content: application/json: schema: $ref: '#/components/schemas/ProviderList' /Versions: servers: - url: https://localhost/rum description: Override base path for Versions query get: summary: Retrieves all supported versions operationId: RetrieveVersions responses: '200': description: Versions supported content: application/json: schema: $ref: '#/components/schemas/VersionsArray'components: schemas: ProviderList: type: object required: - providers properties: providers: type: array items: type: object required: - name - providerEntryPoint properties: name: type: string description: Human-readable provider name providerEntryPoint: type: string description: Provider entry point for interface VersionsArray: type: object required: - versions properties: versions: type: array items: type: object required: - major - minor properties: major: type: integer format: int32 description: Version major number minor: type: integer format: int32 description: Version minor number
openapi: 3.0.1info: title: RUM Configuration API version: "1.0"servers: - url: https://localhost/rum/v1paths: /ProviderConfig: get: summary: Configuration data for one provider operationId: GetProviderConfiguration parameters: - in: query name: apiKey schema: type: string description: API Key assigned to this implementation - in: query name: instanceId schema: type: string required: true description: Unique string for this implementation on this device responses: '200': description: Configuration object content: application/json: schema: $ref: '#/components/schemas/ProviderConfigurationData' /RueConfig: get: summary: Configuration data for one RUE operationId: GetRueConfiguration parameters: - in: query name: apiKey schema: type: string description: API Key assigned to this implementation - in: query name: instanceId schema: type: string required: true description: Unique string for this implementation on this device responses: '200': description: Configuration object content: application/json: schema: $ref: '#/components/schemas/RueConfigurationData' /Versions: servers: - url: https://localhost/rum description: Override base path for Versions query get: summary: Retrieves all supported versions operationId: RetrieveVersions responses: '200': description: Versions supported content: application/json: schema: $ref: '#/components/schemas/VersionsArray'components: schemas: ProviderConfigurationData: type: object required: - dial-around properties: signup: type: array items: type: object required: - language - uri properties: language: type: string description: Entry from IANA "Language Subtag Registry" uri: type: string format: uri description: URI to signup website supporting this language dial-around: type: array items: type: object required: - language - front-door - oneStage properties: language: type: string description: Entry from IANA "Language Subtag Registry" front-door: type: string format: uri description: SIP URI for two-stage dial-around oneStage: type: string format: uri description: SIP URI for one-stage dial-around helpDesk: type: array items: type: object required: - language - uri properties: language: type: string description: Entry from IANA "Language Subtag Registry" uri: type: string format: uri description: SIP URI of help desk supporting language RueConfigurationData: type: object required: - phone-number - provider-domain properties: lifetime: type: integer description: How long (in seconds) the RUE MAY cache the configuration values sip-password: type: string phone-number: type: string description: Telephone number assigned this subscriber in E.164 format user-name: type: string description: A username assigned to this subscriber display-name: type: string description: Display name for the subscriber provider-domain: type: string description: Domain of the provider for this subscriber outbound-proxies: type: array items: type: string format: uri description: SIP URI of a proxy to be used when sending requests to the provider mwi: type: string format: uri description: A URI identifying a SIP event server that generates "message-summary" events for this subscriber videomail: type: string format: uri description: An HTTPS or SIP URI that can be used to retrieve video mail messages contacts: type: object description: Server and credentials for contact import/export required: - contacts-uri properties: contacts-uri: type: string format: uri description: An HTTPS URI that may be used to export (retrieve) the subscriber's complete contact list managed by the provider contacts-username: type: string description: Username for authentication with the CardDAV server. Use SIP user-name if not provided contacts-password: type: string description: Password for authentication. Use provider sip-password if not provided carddav: type: object description: CardDAV server and user information that can be used to synchronize the RUE's contact list with the contact list managed by the provider required: - carddav-domain properties: carddav-domain: type: string description: CardDAV server address carddav-username: type: string description: Username for authentication with the CardDAV server. Use SIP user-name if not provided carddav-password: type: string description: Password for authentication to the CardDAV server. Use provider sip-password if not provided sendLocationWithRegistration: type: boolean description: True if the RUE should send a Geolocation header field with REGISTER; false if it should not. Defaults to false if not present ice-servers: type: array items: type: object required: - server-type - uri properties: server-type: type: string description: Server type ("stun" or "turn") uri: type: string format: uri description: URIs identifying STUN and TURN servers available for use by the RUE for establishing media streams in calls via the provider VersionsArray: type: object required: - versions properties: versions: type: array items: type: object required: - major - minor properties: major: type: integer format: int32 description: Version major number minor: type: integer format: int32 description: Version minor numberIANA has created the "RUE Provider List" registry. The registration policy is "Expert Review"[RFC8126]. A regulator operated or designated list interface operator is preferred. Otherwise, evidence that the proposed list interface operator will provide a complete list of providers is required to add the entry to the registry. Updates to the registry are permitted if the expert determines that the proposed URI provides a more accurate list than the existing entry. Each entry has two fields; values for bothMUST be provided when registering or updating an entry:¶
This document defines the new predefined value "rue-owner" for the "purpose" header field parameter of the Call-Info header field. The use for rue-owner is defined inSection 5.2.3. IANA has added a reference to this document in the "Header Field Parameters and Parameter Values" subregistry of the "Session Initiation Protocol (SIP) Parameters" for the header field "Call-Info" and parameter name "purpose".¶
The RUE is required to communicate with servers on public IP addresses and specific ports to perform its required functions. If it is necessary for the RUE to function on a corporate or other network that operates a default-deny firewall between the RUE and these services, the user must arrange with their network manager for passage of traffic through such a firewall in accordance with the protocols and associated SRV records as exposed by the provider. Because VRS providers may use different ports for different services, these port numbers may differ from provider to provider.¶
This document requires implementation and use of a number of other specifications in order to fulfill the RUE profile; the security considerations described in those documents apply accordingly to the RUE interactions.¶
When a CA participates in a conversation, they have access to the content of the conversation even though it is nominally a conversation between the two endpoints. There is an expectation that the CA will keep the communication contents in confidence. This is usually defined by contractual or legal requirements.¶
Since different providers (within a given country) may have different policies, RUE implementationsMUST include a user interaction step to select from available providers before proceeding to actually register with any given provider.¶
Brett Henderson andJim Malloy provided many helpful edits to prior draft versions of this document.Paul Kyzivat provided extensive reviews and comments.¶